sendgrid / docs

Repository of Twilio SendGrid's product documentation.

THIS REPOSITORY WILL NO LONGER BE MONITORED AFTER JUNE 15, 2021

SendGrid Documentation

Introduction

This is a Gatsby site.

The develop branch is merged to production weekly (unless we need to do a release sooner than that).

The main branch is continuously deployed to production.

• Please, feel free to make any contributions you feel will make SendGrid Documentation better.

  • Familiarize yourself with our Styleguide

• Submit all pull requests to the develop branch

• All third party contributors acknowledge that any contributions they provide will be made under the same open source license that the open source project is provided under.

  • When making contributions, be sure to place an "x" in the brackets of the PR description where it says "[ ] I acknowledge that all my contributions will be made under the project's license."

Table of Contents

• Local Dependency Setup
  • Mac
  • Windows
  • Linux
• Local Repository Setup
• About
• License

Local Dependency Setup

Dependencies

• Required:
  • Git
  • npm
  • Gatsby

Note: Dependencies differ for work on the old-develop branch. If you need to work on old-develop, please see the README file after checking out that branch. This is uncommon.

Setup Steps

Mac

• Install Git
  • Git for Mac

We recommend using Homebrew to install and manage packages on a MacOS.

• Install Homebrew:

  $ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

• Install npm:

  $ brew install npm

• Set your Node.js version to 12

  $ npm install -g n
  
  $ n 12.16.1

Windows

• Install Git

  • Git for Windows

• Install npm

  • To install Node.js and npm on Windows, you can download the installer here:
    • https://nodejs.org/en/#home-downloadhead
  • Use Node.js version 12, the current Long Term Support (LTS) version.

Linux

• Install Git:

  • Git for Linux

• Install npm:

  • To install Node.js and npm on Linux, select the package and instillation appropriate for your Linux distribution. You can find help here:
    • https://nodejs.org/en/download/package-manager/
  • Use Node.js version 12, the current Long Term Support (LTS) version.

Local Repository Setup

Note: When working on Windows, you may need to run Command Prompt or PowerShell as an Administrator.

Note: When working on Mac or Linux, you may need to run some commands using "sudo."

• Clone the SendGrid Docs Repo

  • SSH:

    $ git clone [email protected]:sendgrid/docs.git

  • HTTPS:

    $ git clone https://github.com/sendgrid/docs.git

• Go to your docs directory

  $ cd docs

• Switch to develop branch to make changes

  $ git checkout develop

• Install the Gatsby CLI

  $ npm install -g gatsby-cli

• Install npm package dependencies

  $ npm ci

• Build the local site

  • With the Gatsby CLI installed globally, you can run:

    $ gatsby develop

  • Alternatively, you can run:

    $ npm run develop

  • Either of the above commands should start a hot-reloading development environment accessible at localhost:8000

About

SendGrid is guided and supported by the SendGrid Developer Experience Team. It is maintained and funded by SendGrid, Inc. The names and logos are trademarks of SendGrid, Inc.

License

SendGrid Documentation is licensed under the MIT License (MIT)

docs's Issues

Add note that special characters can be used in headers if encoded as unicode

Show example of multiple categories on the SMTP API categories page

Event webhook requires SSLv2

[12/7/12 9:23:56 AM] Adam Jackson (@adam): Hey @brandon, based on a ticket and some help from TimJ yesterday it looks like our Event API requires customers to have SSLv2 setup on their URL in order to accept POSTs from us. A customer I was working with yesterday was using TLSv1 which caused all POSTs to fail. If we could add a mention that SSLv2 is required to our documentation it may help future customers. Thanks!

Pretty-print all JSON and XML codeblocks so they can be viewed without scrolling horizontally

Add sample post and all potential params to event webhook docs

Update Deliver Metrics page to show which blacklists we monitor

From PKS: 1. Please take a look at this page http://sendgrid.com/docs/Delivery%20Metrics/alerts.html . Could you update it the "IP Blacklisted" section to tell the customer which blacklists we check and generate alerts for.

Update outlook instructions to be more clear than username doesn't have to be an email address

[10/24/12 5:17:32 AM] sebi.mihalache: @docs @brandon - http://docs.sendgrid.com/documentation/get-started/integrate/examples/outlook/ The Log on information in the Outlook settings is slightly confusing for some users. (Internet Email Settings -> Outgoing Server -> Log on using). They tend to add their SendGrid username incorrectly. Assuming that ones username is "someone",  he believes he must add in the User Name field "[email protected]", because the Docs information holds "[email protected]" - changing this to someting more specific like "sendgrid_username" would help. Thanks.

Update blog theme design to match refreshed site

Add more info to Event API docs regarding use cases

Per PKS: Could you update the preamble to the Event API docs to highlight how customers can use events to track customer engagement? Customers need to prune/segment their address lists and remove recipients that aren't opening or clicking on links within their emails. The Event API gives them insight to engagement levels. Perhaps give another example, like how TeamSnap dramatically reduced their support load by using our Event API (Amy can provide details.) This would support the Compliance team's efforts to help customers send only to recipients who want the mail.

Update C# example to match github readme

https://github.com/sendgrid/sendgrid-csharp

Documentation error concerning Event API sending integer when it should state string.

Add web.config settings section to .NET docs

<system.net>





</system.net>

Move Billing error codes Post into a Page nested under /billing/

http://docs.sendgrid.com/docs/billing/billing-error-code/ has some useful information in it for users who are trying to sign up and get an error w/ their payments. Suggest move into a Page from a Post and next under Billing drop down.

If URL changes, let me or Jacob know. there is a Zoura template that references it.

Newsletter API documentation to have the new pricing changes detailed.

As a user I would like for the Newsletter API documentation to have the new pricing changes for Newsletter detailed.

Currently this document is purely technical but should be made to include this new pricing info as its unique to this product and a 1st time change for Sendgrid.

Update Magento example

current example only works up to version 1.5, latest version is 1.7

Bring footer up to date with site redesign

Add the php curl examples back

https://gist.github.com/4512396

IO Docs url shows password in plain text

When you use the IO Docs and run a test, a url is displayed below the response that you could plug in to a browser. The url contains a plain text copy of your password and it should be starred out or not displayed at all

Add example calls and responses to Newsletter Variations page

Add a "partners" section to the docs will links to relevant integration docs for e.g. azure, heroku, appharbor, etc

Swift specifically wants to know about Temboo

Clarify SMTP ports

We accept unencrypted connections on ports 25, 587, & 2525, TLS encryption on on ports 25, 587, & 2525, and SSL encryption on 465

Convert JPEGs to optimized PNGs where possible

Add conditional stylesheet for IE7 and below that doesn't use data-uri embeds.

Already generated by rake generate, just need to conditionally add it to head.html

Add article under 'sending practice and limitations' for re-opt in emails

"Reconfirmation Email Campaigns"

In order to maximize your email deliverability it is important to keep your address list current and clean. What does this mean and why does it matter? A reconfirmation email, otherwise known as a re-opt in email, is a good means to remind clients you once corresponded with about your business (which can increase your inbound marketing), effectively clean your lists with minimal impact to your deliverability, and to prevent inadvertently spamming your clients.

As you opt-in your recipients, the email addresses provided to you initially may become obsolete. These addresses might become abandoned and eventually recycled or converted to spam traps. Another possibility is that your recipients might simply become disinterested in receiving your emails after some time.

This can cause problems for your email deliverability. Old abandoned addresses become undeliverable and subsequent sending will result in bounces. Even your older recipients that had once opted-in to your emails might become disinterested and are more likely to mark your mail as spam, especially if there is no easy opt-out method in the email.

To prevent these problems, we recommend using re opt-in messages. These emails remind your recipients of your services they once opted into and politely ask for the recipient's permission to continue sending emails. A typical means to do this would be to send an email with two links: one link to re-opt in the recipient, and the other link to opt-out the recipient. If they do not explicitly opt back in with this email, their address should be removed from your list as this is an indication your recipient is not engaging in your emails. This could be a sign that you are sending to someone that does not care for your emails, or even worse, you could be sending to a spam trap.

Ultimately, this is a win-win as you are both reminding your recipients of your services, which helps to keep them in the loop, while you are benefiting by being able to track your recipient engagement and maintaining a clean list.

If you are set up with SendGrid's Event API, click and open events are an excellent way to track which of your users have been unengaged and might be the best targets for your reconfirmation emails. You can even make your reconfirmation emails specific to a particular segmented list if your address lists are set up in this fashion.

This approach is much more favorable than trying to clean a large old address list all at once. Sending to a 10-year-old list (or even a 3-month-old list) can produce a high bounce rate and cause your unengaged recipients to mark your emails as spam. Email service providers discourage this type of sending because of these results. Keep in mind, the older the list, the bigger the headache it will be to clean.

How often and to whom should these be sent out? We recommend sending re opt-in messages to recipients if you haven't corresponded with or otherwise interacted with via email in over 3 months. This may seem like a short duration, however, you might be surprised with how quickly your recipients can lose interest in your emails. Of course there are many types of businesses and this recommendation of 3 months is only a suggestion. You know your business better than anyone so decide what works for you. Ultimately however, the more frequently you clean your address list, the less likely you will be to have deliverability problems related to old lists.

Add image optimization to the jekyll build

Document Create New Sub-user guide for DOCS

As a user I would like for a new subuser creation guide to be added to the website to help guide me through the creation process for a subuser from my parent account. This should ideally include a video and or screenshot based walk through for the creation process including whitelabeling the new subuser and the IP assignment process.

Can't start the docs in development mode

I'm trying to get the docs running locally so I can verify the changes that I'm making look good before I push them upstream. The steps I did were:

1. Copy over _config.sample.yml to _config.yml
2. Setting the root property to /
3. installing dependencies w/ bundle install
4. Running in preview mode with bundle exec rake preview

The error I get is:

 Sorry, I cannot find /

Any thoughts?

Add note about categories and impending cap, per Adam Jackson

We need to get this page updated to reflect the troof about Categories

The more you have the slower Stats load and soon there will be a cap. Should mention Unique Arguments and the Event API if further tracking is needed'

create generic ruby wrapper

Update substitution tags docs to show that they work in subject line as well

Expound upon alert settings for SNDS yellow/red. delivery-metrics/alerts/

Per Ian G

Node.js example needs to be updated -- currently uses deprecated libraries, etc

Add instructions to Sendmail docs on using TLS, per David Williams

Paginate the search results

Update blocks endpoint documentation to show the limit and offset params for retrieving records in blocks, also note that a limit of 2000 records per call will be enforced

Other methods might also support limit and offset params -- should check with MP

Add link to event webhook page from event notification app page

"For more information on the Event Notification service please see the following page: http://sendgrid.com/docs/API_Reference/Webhooks/event.html"

Add note about category encoding

Per Jayson: @docs @brandon - Do we have anything that says "Categories must be in 7bit encoding with US-ASCII character set"?

Document custom newsletter tags

In the newsletter tags section, we document the default tags (unsubscribe, weblink, etc), but we never document the tags for recipient list fields (first_name, last_name, etc)

http://sendgrid.com/docs/Newsletters/tags.html

Add examples for event webhook handlers

Should probably do this for all languages for which we provide integration examples.

add enable_text parameter to SMTPAPI filter settings for click tracking app

ask Jacob for more info

Discuss reducing # of rewrites

Add VB.net integration example that includes WEB API implementation

Primarily for users with Azure integrations using Microsoft Visual Studio 2010 who want to call a weblink to utilize our REST API through their Azure instance.

Documentation page for the event API to include notice to users informing them that this feature is only available for Silver and higher accounts or for our Free "demo" accounts.

The documentation page for the event API should include a notice to users that this feature is only available for Silver and higher accounts or for our free demo accounts.

The page in question is located here: http://docs.sendgrid.com/documentation/api/event-api/

Add note that to[] on mail.send works like email client to, not like X-SMTPAPI to, so all recipients will be visible to each other

add keyword "split testing" to A/B testing page somewhere

Add note to SMTP API reference that full recipients, including display name, can be used in the X-SMTPAPI header

user guide for additional domains

user guide to when you need an additional domain, and what to do. covering the proper setup for new whitelabel vs existing whitelabel, cost, etc

Add note to Reseller API clarifying the usage

Emily says that sales often gets calls regarding "permission denied" errors encountered when people try to use the reseller API

Some customer subuser API links go back to v1 docs

Add inline images example for web api