With yesterday’s announcement that Mandrill is becoming a paid “add-on” to MailChimp, we understand that current Mandrill customers are looking for other providers to help send their mail and to do it quickly. We want to make that as easy as possible here at SendGrid.

This how-to will highlight some of the main differences between sending email via Mandrill and sending email via SendGrid to help make migration as easy as possible.

You might want to take a quick look at the SendGrid documentation before proceeding. The Classroom is a great place to start before diving into the lower level details of moving mail and making API calls.

If you’re looking for the SendGrid equivalent of certain Mandrill functionality, the following table can help:

SendGrid Term Mandrill Term
substitutions/sections merge_vars
categories tags
unique_args metadata
subuser subaccount
suppressions rejections

Getting an API Key

Let’s get going. To start, you need a SendGrid account. After you have a SendGrid account, you’ll want to create an API key that you’ll use for sending.  Go to Settings -> API keys, or use this link if you’re logged in. It’s a good security practice to use a different API key for each of your different apps. You can also define permissions for API keys, enabling or disabling read or write access for individual endpoints. For now, you’ll just need one that has full access to Mail Send. (Note: You must pass provisioning before being able to create an API key.)

API Libraries

We have a number of officially supported API Libraries that will help make sending email easier. If you’re rewriting any code or refactoring how you communicate with your ESP as part of your migration, now is a good time to utilize one of these libraries to speed up your integration:


If you’re not using one of our libraries, and are sending via SMTP, there are a few differences you should be aware of. To authenticate when sending via SMTP, provide the string ‘apikey’ as the SMTP username, and use your API key as the password. Then point your hostname to smtp.sendgrid.net.

You can connect using SMTP via unencrypted or TLS on ports 25, 2525, and 587. You can also connect via SSL on port 465. In general, we recommend port 587 as it tends to result in the fewest issues with hosting providers.

The mechanism for customizing email sent via SMTP is our X-SMTPAPI header. This header will allow you to define substitutions, send batched mail-merge style requests, and control filters (like click tracking) that are active for your send.


The main endpoint for sending email is the mail.send endpoint. Requests to this endpoint are authenticated via an authorization header with your API key presented as a bearer token. You can find a more detailed example in our docs.

Personalizations allow you to define recipients and metadata for each message, such as substitution values for customizing content or custom_args for associating messages with user ids or order numbers. There are a number of examples of personalizations for common use cases. You can also find cURL example calls.

Features like click tracking  are configured via the tracking_settings and mail_settings parameters.

Attachments sent via HTTP are handled in a fashion similar to Mandrill, where the content is encoded as Base64 and embedded directly in the JSON payload alongside MIME information, like so.

Note that SendGrid’s mail.send endpoint is entirely asynchronous. We will accept the request (as long as it’s well-formed) and then attempt to process the delivery of the mail as soon as possible. Mandrill allows requests for fewer than 10 emails to be executed synchronously. SendGrid does not offer a synchronous mode.

You can also schedule sends up to 72 hours in advance by using the “send_at” parameter.


SendGrid provides two webhooks: the Event Webhook for posting real-time events and the Inbound Parse Webhook for receiving emails and programmatically responding to them. The data shapes and payloads are a bit different from what Mandrill provides—SendGrid does not have an equivalent to Mandrill’s “sync” webhook.

Non-email API Endpoints

For API endpoints that don’t send email, check out the API v3 overview. We use intuitive HTTP methods and response codes in most cases, and enforce rate limits for calls. API v2 is deprecated though there is no timeline to stop supporting it. All new integrations should prefer v3. API v3 authentication is accomplished by an authentication header with a Bearer token.

A Few FAQs

Q: Do you support templates for transactional emails?

A: Yes, although our transactional templates do not support enumerations or conditionals at this time.

Q: Is there a sandbox or a way to test my emails without sending them?

A: You can enable sandbox mode when sending via HTTP. There is also a “sink” address that you can use for testing.

Q: Is it possible to transfer my IP address/sender reputation to SendGrid?

A: We can’t migrate an IP or reputation but we can help warm up a new IP for you automatically.

Q: Does SendGrid support enforced TLS?

A: Absolutely. You can require that receiving servers support TLS and drop messages going to servers that don’t comply.

Q: Can I allow my recipients to define the types of emails they want to receive?

A: Yes. Giving your recipients more control of their email lets you send email people want, which is better for everyone. Check out unsubscribe groups for more information.

To learn more about switching to SendGrid, visit: https://go.sendgrid.com/switch.html.

Brandon West
As Director of Developer Relations for SendGrid, Brandon's focus is on empowering developers to build things, gathering feedback for new features and improvements, and fostering a cooperative developer community for anything that needs email integration.