In 2016, Mandrill—now known as Mailchimp Transactional API—became an exclusive add-on service to Mailchimp. This meant that only Mailchimp monthly members could access Mandrill’s email transaction features. For other users, they had to either choose another platform or opt to pay for a Mailchimp account they wouldn’t always need. 

We understood then that many customers would seek an alternate provider that could efficiently send out emails. Twilio SendGrid wanted to help make that process as smooth as possible. 

Migrating from Mailchimp Transactional API to SendGrid

As strictly an add-on, Mailchimp Transactional API is not set up to reliably deliver email at the scale you need for your business. But here at Twilio SendGrid, we’re the leaders in trustworthy, secure email delivery, processing over 100 billion emails per month for our leading senders, including Uber, Airbnb, and Spotify. 

In this tutorial, we’ll walk through the key advantages you can expect when sending emails with Twilio SendGrid. Our step-by-step migration guide will ensure a smooth and streamlined transition. 

Twilio SendGrid Documentation is the best resource for those looking for an answer to all SMTP, API, and email-related inquiries. It’s a great place to start before diving into the more nitty-gritty details of moving mail and making API calls. 

But first, if you’re looking for the Twilio SendGrid equivalent of certain Mailchimp Transactional API  functionality, the following table can help: 

SendGrid term Mailchimp Transactional API term
substitutions merge_vars
categories tags
custom args  metadata
subuser subaccount
suppressions rejections
X-SMTPAPI X-MC-*
dynamic templates templates

Getting an API key

To start, you need a Twilio SendGrid account. Then, 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 into your account. It’s a wise security practice to use a different API key for each of your different apps. You can also define permissions for API keys by 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 further optimize the email sending process. If you’re rewriting any code or refactoring how you communicate with your email service provider (ESP) as part of your migration, now is a good time to utilize one of these libraries to speed up your integration:

SMTP

If you’re not using one of our libraries and sending via Simple Mail Transfer Protocol or SMTP, there are a few differences you should know. 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. Or, 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.

HTTP

The main endpoint for sending email is the mail.send endpoint. You can authenticate requests to this endpoint via an authorization header with your API key presented as a Bearer token. 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 several examples of personalizations for common use cases. You can also find cURL example calls

Features, like click tracking, can be configured via the tracking_settings and mail_settings parameters.

For attachments sent via HTTP, handle them in a fashion similar to Mailchimp Transactional API, where the content is encoded as Base64 and embedded directly in the JSON payload alongside Multipurpose Internet Mail Extensions or MIME information, like so

Note that Twilio SendGrid’s mail.send endpoint is entirely asynchronous. We’ll accept the request—as long as it’s well-formed—and attempt to process its mail delivery as soon as possible. Mailchimp Transactional API allows requests for fewer than 10 emails to execute synchronously. Twilio SendGrid, however, doesn’t offer synchronous mode. 

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

Webhooks

Twilio SendGrid provides two webhooks: the Event Webhook for posting real-time events and the Inbound Email Parse Webhook for receiving emails and programmatically responding to them. The data shapes and payloads are a bit different from what Mailchimp Transactional API offers—Twilio SendGrid doesn’t have an equivalent to the “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. Despite no timeline to stop supporting it, API v2 is still available minimally. All new integrations, however, should lean toward v3. API v3 authentication is accessible via an authentication header with a Bearer token.

Migrating to Twilio SendGrid FAQs

Q: Do you support templates for transactional emails?

A: Yes—and the templates are dynamic! Twilio SendGrid’s transactional templates feature native support for Handlebars syntax. In addition to basic replacement and substitutions, you can use enumerations/iterate over lists, take advantage of conditionals, and more. To learn more about our templates, click here.

Q: Is it possible for me to test out my emails without having to send them?

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

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

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

Q: Does Twilio SendGrid support enforced TLS?

A: Absolutely. Our receiving servers support TLS and drop outgoing messages 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 allows you to send emails to subscribers who genuinely want them, which is better for everyone in the long run. Check out our unsubscribe groups for more information.

Q: Can you send emails to multiple recipients per request? 

A: Yes. API v3 customers using personalizations can include up to 1,000 recipients per request. SMTP users can include up to 10,000 recipients per message—but we often recommend that you go with 1,000 recipients per request. 

Learn more about switching from Mailchimp Transactional API to Twilio SendGrid



Expert advice and insight about all things email including best practices tips, examples, and advice for marketers, developers, and everyone in between.