How to Migrate From Messagebird to SendGrid

August 22, 2017
Written by
Opinions expressed by Twilio contributors are their own

How to Migrate From Messagebird to SendGrid

As the pioneer of cloud-based transactional email, we’ve seen many changes and new companies in the space. The trend we’ve seen with these companies is that first they imitate us, then they attack us, then they imitate us some more. In addition to providing detailed migration guidance below, we want to provide a few thoughts about the value our customers get from SendGrid.

First, every one of our customers, including those using our Free plan, receive support from our highly experienced support team. For customers on our Free plan, this support continues even if they don’t upgrade to a paid plan. And for all customers, support is available 24 hours per day, every day of the year, for every region where our customers are located. Our support offerings are part of our commitment to making all users of the SendGrid platform successful by being there for them anytime.

Next, from the tiniest startups to the largest enterprises, API-driven programmatic email isn’t the only way these companies use email to reach customers. They also send newsletters, announcements, and campaigns to grow customer engagement and drive purchases. At SendGrid, we’re dedicated to meeting all customer communications needs, with full team enablement for marketing and promotion as well as for programmatic. Our Marketing Campaigns product lets you engage your customers using our intuitive UI with advanced segmentation, analytics, and design tools.

Finally, there’s a reason we have more than 55,000 paying customers processing over one billion emails per day. The reason is that we use our passion for customer communications and our deep email expertise to help our customers grow their business. Each day they work with us, our customers feel our culture and our commitment to their success.

How to migrate to SendGrid from Messagebird

Note: The following migration plan has been provided courtesy of our community development team. This how-to will highlight some differences between sending email via Messagebird and sending email via SendGrid to help make migration as easy as possible.

If you'd like to take a look around before getting going, check out the SendGrid documentation. The Classroom is a great place to start learning about email before diving into the API reference and details.


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

SendGrid TermMessagebird Term
substitutions/sectionssubstitution data
suppressionssuppression list
Inbound Parse WebhookInbound Domains
Marketing CampaignsNo Equivalent

Getting an API Key

First, you'll need a SendGrid account. Next, you should create an API key that you’ll use for sending. Go to Settings -> API keys, or use this link. A SendGrid and security best practice is to use a different API key for each of your different apps. API keys have granular permissions, so you can enable or disable read or write access for individual endpoints. Make sure the API key you create has full access to Mail Send. (Note: Your account must pass provisioning before you can create an API key.)

API Libraries

We have a number of officially supported API Libraries to make integration easier for our customers. 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 evaluate these libraries:


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

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 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. You can also schedule sends up to 72 hours in advance by using the "send_at" parameter.

Attachments sent via HTTP are handled in a fashion similar to Messagebird, where the content is encoded as Base64 and embedded directly in the JSON payload alongside MIME information. You can read more about including attachments in the following section of our Documentation Classroom.


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 Messagebird provides.

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.

Marketing Campaigns

We have a fully-featured platform for managing contact lists, creating and designing templates, A/B testing different templates, and scheduling campaigns. This is all wrapped in a UI that is easy to use for non-developers. And of course, you can also access all of these features via our Marketing Campaigns API.

A Few FAQs

Q: Do you support templates for transactional emails?

A: Yes—and they’re dynamic! 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, click here.

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.

If you're interested in migrating to SendGrid, you can find more information at

Recommended For You

Most Popular

Send With Confidence

Partner with the email service trusted by developers and marketers for time-savings, scalability, and delivery expertise.