API Guide |

API Guide

Contents
2 Introduction
3 Event Webhook
5 Inbound Parse Webhook
7 Web API
9 Marketing Campaigns
10 Contact Management API
11 Campaigns API
12 SMTP API
14 Subuser API & Reseller API
15 Resources
16 Get Started

Contents | 1
>
 API Guide

Introduction
SendGrid’s webhooks and application programming interfaces
(APIs) extend the capabilities of our email platform, allowing users
to quickly integrate with our system, measure delivery effectiveness, What’s an API? API
and expand the management of their email. stands for Application
Programming Interface,
After implementing our APIs and webhooks, users can have which is essentially a
their applications parse emails, retrieve account statistics, see language and message
email events occurring in real-time, and specify custom-handling that allows a program to
retrieve information from
instructions for messages.
a web application. Learn
More: Webhook vs API:
This API Guide will describe how to maximize the capabilities of a What’s the Difference
SendGrid account. By using one, or even a combination, of our Between Them?
APIs and webhooks, users can tailor SendGrid to meet their
specific business needs.

This guide provides:

Overviews of each API and webhook
Metrics, analytics, and use cases
Hacks, tips, and tricks
Additional resources and tools for extra learning

We allow everyone to test, hack, and experiment with our entire Webhook and API library through
our free accounts.

Sign Up for Your Free Account and Start Experimenting Today

Contents | 2
>
 API Guide

Event Webhook
With the Event Webhook, users can set up real-time notifications What’s a Webhook? A
based on a variety of parameters and categories. Depending on webhook is an API concept
that is also called
how users configure the Event Webhook, they can view detailed
a web callback, HTTP
information such as who opened which email or who clicked a
push API, or reverse API.
specific link, as far back as their records go.
Webhooks enable
apps to push data to other
This means that users can now see what happens to their messages applications as it happens
AFTER they send them, rather than just know they’ve been sent out. in real-time.
The events that the Event Webhook can track include: Learn More: What’s a
Webhook?

Event Criteria
Processed Message has been received and is ready to be delivered.
Dropped Recipient exists in one or more of your Suppression Lists: Bounces,
Spam Reports, Unsubscribes.
Delivered Message has been successfully delivered to the receiving server.
Deferred Recipient’s email server temporarily rejected message. Learn More: The Event
Bounce Receiving server could not or would not accept message. Webhook Guide provides
Open Recipient has opened the HTML message. more detailed information
Click Recipient clicked on a link within the message. about how senders can
Spam Report Recipient marked email message as spam. use the Event Webhook in
Unsubscribe Recipient clicked on message’s unsubscribe link. your application.

When implemented, SendGrid will notify a URL of the user’s choice about the above events. Through
customized reporting and relevant category and unique argument information, the Event Webhook
potentially gives users the entire sending activity of their account and is not restricted by SendGrid’s
internal storage limitations.

Contents | 3
>
 API Guide

Additionally, as events are posted in real-time, users can have

automated systems on their end take action. The Event Webhook
enables users to: Quick Tip: The Event
Automatically remove unsubscribes from the master Webhook is great for
mailing list. accessing ongoing email
activity data for reporting
Associate a spam report with a specific campaign and user
or trending purposes. Due
in an application.
to SendGrid’s volume, our
Know real-time when a user has clicked on a Email Activity page holds
confirmation email. records for 7 days.
Get the specific link clicked on in an email.
Get the browser version used by a customer.
Know the specific MTA response for a customer.

For a more technical breakdown of how the Event Webhook works and how to implement it,
visit the Event Webhook Documentation.

See it in Action
TheLadders use the Event Webhook to see which job seekers
are engaged with each of their email streams to make sure
they’re sending the best content possible. Learn more in
their case study: TheLadders Have Found that
SendGrid “Just Works.”

Implement Faster: The open source EventKit Rails project on GitHub can be deployed
to a rails server to quickly deploy to Heroku and allows you to receive notifications for
SendGrid’s Event Webhook.

Contents | 4
>
 API Guide

Inbound Parse Webhook

The Inbound Parse Webhook allows users to accept incoming emails from recipients, eliminating
“no-reply” in the from-address. This encourages recipients to communicate with senders
and improves engagement.

SendGrid’s Inbound Parse Webhook works in a simple three-part process:

1. Recipient(s) replies to an email at the SendGrid user’s domain
2. SendGrid processes the email and extracts each part of the message
3. SendGrid POSTS each message part to a URL of the user’s choice

Learn More: Our Parse Webhook Guide dives even deeper into the applications for
this tool and provides additional examples of companies taking advantage of it.

Watch this video tutorial to learn how you can set up the Inbound Parse Webhook in just
a few minutes.

Contents | 5
>
 API Guide

Since the Inbound Parse Webhook can parse headers, subjects, body, attachments, and more from
messages, it enables users to do a wide variety of things, including:
Post blog articles via email.
Process email replies and update mailing lists or databases.
Upload pictures to social media profiles via email.
Submit support requests via email.
Track changes in user data in real-time using custom code.
Automatically filter overtly “spammy” emails.

Learn more about the different capabilities of the Inbound Parse Webhook and how to integrate it
into your email program by visiting the Inbound Parse Webhook Documentation page.

See it in Action
The Inbound Parse Webhook can be used for a variety of applications. Read about how to use the
Inbound Parse Webhook to have email replies read aloud in our blog post Get Your Mac to Speak
Incoming Emails.

Quick Tip: SendGrid automatically queues and retries unsuccessful POSTs that have
responded with 4XX or 5XX statuses. This ensures that data isn’t lost if there are
configuration issues with customer websites or POST URLs. Please ensure you grant a 200
OK status on a successful POST.

Great Idea: Be practical. An expense-tracking system could allow users to email a list of
purchased items to a specific email address. The Inbound Parse Webhook could extract
the data and update the expense tracker seamlessly. Users don’t have to log onto their
system and can easily update their expenses from their mobile phone.

Contents | 6
>
 API Guide

Web API
Currently, SendGrid has two versions of our Web API: Web API v2 and
Web API v3. The largest difference between the two is:

The only way for users to send mail via API is through Web API v2.
Learn More: To learn
Since mail.send is only available with Web API v2, code examples more about how to
and libraries for sending mail have been created for Web API v2 retrieve important
and NOT Web API v3. However, due to its improved functionality, we information like bounces,
recommend users perform all other account functions through Web blocks, and unsubscribes,
API v3. or to see how our
unsubscribe groups can
As additional API endpoints and documentation about them are be implemented, visit the
created, we encourage you to check SendGrid Docs to get the most following pages:
up to date information about Web API v3 functionality. Web API Overview
Documentation
Web API v3 Web API v3 Overview
Web API v3 is SendGrid’s preferred method for retrieving account Documentation
information without logging into your SendGrid dashboard. Web API
v3 features much different behaviors and capabilities in comparison
to the Web API v2, in addition to being much more secure with
the addition of API keys, which is why we recommend you use it to
perform most account functions.

Within Web API v3, there are a host of other APIs and endpoints designed to make your SendGrid
account easier to use and more customizable. These features include:

Bounces API - View and delete email bounces by timestamp or by email address.
Subuser API - Create, list, enable, disable, delete, monitor settings, retrieve reputations, and
update IPs of subusers.
Users API - View, create, or edit user profile information such as address or name.
Cancel Scheduled Sends - If you set the SMTPAPI header batch_id, you can then cancel
or pause a scheduled send based on that batch_id by calling the Cancel Scheduled
Send endpoint.

Contents | 7
>
 API Guide

Marketing Campaigns API - Create, manage, and segment lists from the Contacts API, or
build and send email through the Campaigns API.
Categories API - Once you’ve created categories, you can use this API to retrieve a list of
emails under that topic.
IP Management API - Create IP pools, assign IP addresses to them, and enable IP warmup
for the pools and IP addresses you’ve created.
Settings - In addition to the settings available in the Web API, Web API v3 allows you to set
and check the status of user settings like enforced TLS and partner settings.
Stats - The statistics available to users in Web API v3 are very advanced, and can provide you
with almost any information you need for any recipient or category.
Suppression Management - Allows your recipients to unsubscribe from groups of emails
rather than globally from your email list.
Transactional Templates API - Programmatically create and send templates for your
transactional email.
Whitelabel API - View, create, or edit domain, link, and IP whitelabels to improve
your deliverability.

Web API v2
For users learning about our mail send functionality and our API endpoints, refer to the
Web API v2 documentation.

Contents | 8
>
 API Guide

Marketing Campaigns
SendGrid’s Marketing Campaigns allows you to eliminate the need for
multiple email vendors to manage both transactional and marketing
email streams. Marketing Campaigns makes managing contacts,
Learn More: Create and
building campaigns, and tracking recipient engagement easier
send your next marketing
than ever.
emails through the
Marketing Campaigns
The Marketing Campaigns feature set was built for developers and feature set by visiting the
designed for marketers. Some of the features Marketing Campaigns Marketing Campaigns
offers include: documentation.
Custom Fields - To automatically generate substitution tags
for emails and segment contacts.
Email Templates - Upload your preferred template code into
our editor and save it for later use or use one of the
pre-designed, responsive templates within the library.
Drag & Drop Editor - Quickly and easily create a custom, Quick Tip: Use A/B testing
responsive email template with our drag & drop email editor. (also called split testing)
to add variations to
A/B Testing - Test different versions of your email to drafted marketing emails.
determine what your recipients are engaging with and improve Learn more about A/B
the performance of future sends. testing in our guide: Why
Create and Send Campaigns - Easily create new email A/B Testing is Critical to
campaigns, add contacts, add groups, and add custom Email Campaign Success
categories for stats tracking before sending right away or or visit the A/B Testing
scheduling a time to send in the future. Documentation page.

Once you’ve sent your emails through Marketing Campaigns, you can use the dashboard to view
aggregate stats about the status of those messages:

See it in Action
Pandora is just one of the
great companies that
sends their marketing email through SendGrid.
See what we love about their messages in our
post Personalized Music Metrics from Pandora.

Contents | 9
>
 API Guide

Contacts API
Manage your Marketing Campaigns contacts via the Contacts API. All contact
list management functionality available within the user interface is made available via the
API, providing developers with the ability to manage lists, contacts, and custom
segments programmatically.

Through the Contacts API, users can programmatically:

Create or delete custom fields
Retrieve all custom fields, all lists, all segments, and recipient counts
Create, update, or delete lists
Retrieve the recipients included in a list or segment
Add or delete recipients to/from a list or segment
Create, update, or delete a segment

Learn More: For more information about the Contacts API and a more technical
walkthrough of how to use it, visit the Contacts API Documentation page.

Contents | 10
>
 API Guide

Campaigns API
Programmatically build and send your marketing campaigns. Create, save, review, schedule, and
send campaigns within SendGrid’s Marketing Campaigns feature set.

Rather than log into the Marketing Campaigns feature set, you can use the Campaigns API to
programmatically accomplish many actions without the user interface, including:
Create, view, update, and delete a campaign
Retrieve all campaigns
Schedule or send a campaign
View, update, or unschedule a previously scheduled campaign time
Send a text campaign

Learn More: If you’d rather use the Campaigns API to create and send marketing emails
instead of logging into the UI, visit the Campaigns API Documentation to learn how
to start sending.

Contents | 11
>
 API Guide

SMTP API
The SMTP API may be SendGrid’s most robust API. It allows users
to deliver custom-handling instructions for email through a header
inserted into the message labeled X-SMTPAPI. This header is a JSON- Learn More: For a
encoded list of instructions and options for that message. walkthrough of the SMTP
API, and some additional
The X-SMTPAPI header can be added to any SMTP message sent requirements and
limitations of the API, just
to SendGrid so that the message can be interpreted and applied.
visit the Documentation
Handling instructions that can be included in the X-SMTPAPI
page Using the SMTP API.
header are:
Apps - Also called filters, can be used to override filter settings
already set up for the account.
Categories -Allows you to track emails based on your own
categorization system.
Scheduling Parameters - Delay sending to improve mail flow
and mail delivery time. Quick Tip: The custom
X-SMTPAPI header added
Section Tags - Specific to the message, but not the recipient,
to messages will not be
these tags can be used to create extremely customizable
seen in the final email
emails for recipients.
because it is an instruction
Substitution Tags - Specific for each recipient, these tags allow header for SendGrid, and
you to deliver dynamic content, like inserting the first name of is stripped out of the
a recipient in the greeting. final email.
Unique Arguments - Allow for even more detailed email
tracking, like specific password resets or newsletter dates.
IP Pools - Control the IP address that messages are sent from
to dynamically segment mail streams.

Contents | 12
>
 API Guide

Through the X-SMTPAPI header, users are able to accomplish a wide variety of things
with their email:
Tag emails to get detailed statistics on each tag.
Send multiple customized emails in one request via a mail merge.
Configure each app on a per-email basis.
Deliver dynamic content to your recipients in each email.
Customize filtering instructions to control the amount and type of data you receive
from each email stream.

See it in Action
See a great example of how to create a native app using Titanium
Appcelerator and some SendGrid Apps (or filters) in the blog post
Send Email with Titanium and SendGrid.

Contents | 13
>
 API Guide

Subuser API & Reseller API

The SendGrid Subuser API and Reseller API are excellent Partner Program tools for users to set up
child accounts for their customers to send email and view analytics, or to offer our delivery services
to customers. Some of the partner programs these work well for include:
Cloud Platform - Ideal for IaaS, MBaaS, PaaS, hosting, or other cloud stack services that want
to provide email delivery solutions to customers.
Marketing Solution - Build features or entire products on SendGrid’s email platform and let us
take care of the backend work.
Agency - Allow SendGrid to provide the robust email solution for client web
and mobile applications.
System Integrator - Perfect for software consulting firms and developer shops that need a
cloud-based email infrastructure solution.
Affiliate - The easiest way to partner with SendGrid and begin to leverage our industry-leading
email delivery platform.
Accelerate - SendGrid is happy to work with startup accelerators to support
early-stage companies.

To become a SendGrid partner, please visit the SendGrid Partner Programs page to learn
more or Contact Us.

See it in Action
Read about how we’ve made it easier to deploy some of our main
applications such as the SendGrid Event Webhook and Inbound Parse
Webhook. Read the blog post It’s Now Easier to Deploy Some Demo
Applications With the Heroku Button.

Great Idea: The Subuser API isn’t limited to Partner Programs. Many of our higher-volume
users take advantage of the Subuser API and create child accounts to segment various
types of email they send. To learn more about how to implement the Subuser API, please
contact SendGrid Sales or Support.

Contents | 14
>
 API Guide

Resources
The following resources are designed to help users take even more advantage of SendGrid’s APIs and
webhooks. Whether it’s more information before implementing a new tool, or trying to troubleshoot a
problem, the following links will help.

As always, if you have more technical or account-specific questions, you can Contact SendGrid Support any
time to get answers.

Blog – The SendGrid Blog is the best place for staying up-to-date on everything email and SendGrid-related.
Our posts range from email best practices tips, to technical tutorials for implementing new features,
to announcements about product updates, or guest posts from partners. Check in often or subscribe
to stay informed.

Code Workshop – SendGrid’s Code Workshop is designed to make implementing code and integrating with
the SendGrid platform as easy as possible. The Code Workshop tool allows you to select one of five different
coding languages (C#, Node.js, PHP, Python, or Ruby) and then generate example code. This tool is great for
creating SMTP API headers, creating message examples for multiple recipients, or showing examples of how
to make attachments for messages.

Documentation – SendGrid’s Documentation is where you can find more technical information about every-
thing surrounding SendGrid accounts, APIs, and products. Whether it’s integration, determining what metrics
mean, or definitions for email terms, our Documentation is where all this information lives, and it’s being
updated constantly.

GitHub – SendGrid is a great believer in Open Source, so all of our API Libraries, SDKs, Apps, and even our
Documentation can be found on our GitHub profile. Extensive documentation for each API Library can also
be found in each relevant repository.

Guides – Our other email best practice guides are excellent resources to have if you’re working on an email
campaign. Our topics cover calls-to-action, design, deliverability, and even A/B testing.

Knowledge Base – Our Knowledge Base is a collection of articles written and posted by SendGrid Support
to answer common customer questions. This is a great place to look for answers for any account question,
including those about IPs, apps, and even account billing.

Support – We’re proud to have the best account and email support team in the industry. If you’re having any
issues with your SendGrid account, you can feel free to contact us 24/7 via phone, chat, or email.

Contents | 15
>
 Get Started with
SendGrid
Learn More
Read Our Customer Success Stories
Sign Up

About SendGrid
SendGrid helps you focus on your business without the cost and com-
plexity of owning and maintaining an email infrastructure. We manage
all of the technical details, from scaling infrastructure, to ISP outreach
and reputation monitoring, to whitelist services and real-time analytics.
We offer world-class deliverability expertise to make sure your emails
get delivered, handle ISP monitoring, DKIM, domain keys, SPF, feedback
loops, whitelabeling, link customization, and more. To learn more, visit
www.sendgrid.com.

Contents
>