We receive a continual flow of comments, use case questions and feature requests from our community. One constant we have identified while listening to you all is that you each come from somewhere, usually another email service. In response, we published migration guides for Mandrill, MailGun and SendGrid. We also heard that moving email templates between services was a regular pain so we built a Mandrill template migration tool to help with that.

We had some nice feedback from those efforts so, to build on that, I’m excited to to announce our new SendGrid template migration tool. Now people coming from SendGrid can bring their transactional and marketing campaign email templates with them to SparkPost. Read on for details on how it works, where to get it and how to get help.


For the impatient and technically-minded, you can grab the code from GitHub and follow the deployment steps in the readme. You’ll need Node.js installed as a prerequisite. Happy translating!

Deployment: How Do I Get It?

Using Heroku

If you’re a Heroku user, you can just click the purple “Deploy to Heroku” button below or from the GitHub Repo to bring the tool up in your Heroku account. Quick and easy.


Running It Yourself

You can also run it like any other service. Here are some minimal steps to get you started. You’ll need Git and Node.js installed.

git clone https://github.com/SparkPost/sendgrid-sparkpost-templates.git
cd sendgrid-sparkpost-templates
npm install
npm start

Once started, you can access the UI from http://localhost:4000/. Incidentally, the app is the same whether running locally or on Heroku:


How To Use It

Translating SendGrid Template Content

The simplest way to use the tool is just to translate a piece of SendGrid template text into its SparkPost equivalent. To do that, choose the “Translate template text” button to show the side-by-side translation page. You can paste your template into the text box on the left, select “Transactional template” or “Marketing template” depending on the type of content you want to convert, then hit “Translate!” and your SparkPost template will appear on the right.


Migrating a SendGrid Template Into SparkPost

The app can also migrate transactional and marketing campaign templates directly from your SendGrid account into SparkPost on your behalf. Naturally, you’ll need both SendGrid and SparkPost accounts to pull this off. Your SendGrid API key needs Template Engine permission if you’re migrating a transactional template and Marketing Campaigns permission for a marketing campaign template. Your SparkPost API key needs Templates Read/Write privilege to save the translated template on your account.

Identifying SendGrid Templates By ID

As a quick aside, you’ll need to know how to identify your SendGrid templates to migrate them into SparkPost. SendGrid’s transactional templates are identified by a UUID which is visible under Templates -> Transactional beside each template. Marketing Campaigns are identified differently. Campaigns each have an integer which is visible in the editor URL for that campaign. You can see each marketing campaign’s URL by visiting Marketing -> Campaigns and hovering over that campaign’s link.

…and now back to the matter in hand. Once you have your API keys and template ID, choose the “Migrate a template” button in the migration tool to show the template migration page. Paste in your SendGrid API key, SendGrid template ID and SparkPost API key into the form, then click the “Begin migration” button. This will bring the template over from your SendGrid account, translate it into SparkPost-speak and deposit it into your SparkPost account.


Automating Migration

So much for mouse-driven migration. Let’s say you actually have 10 or ~500~ 300 templates to migrate. That’s a lot of clicking around. Instead, you could use the migration tool’s API directly to rip through all your templates at once in an automated, repeatable manner. Here’s a sample HTTP API call which migrates a transactional template:

  "sendgridAPIKey": "...",
  "sendgridTemplateId": "...",
  "sparkPostAPIKey", "...",
  "options": {
    "useHerokuSPAPIKey": false,
    "isSendgridCampaign": false,
    "useSandboxDomain": true,
    "startingDelimiter": "%",
    "endingDelimiter": "%"

Here’s the same thing in a convenient cURL command:

curl -X POST http://localhost:4000/api/migrate -H "Content-type: application/
json; charset=utf-8" -d '{"sendgridAPIKey": "...", "sendgridTemplateId":
"...", "sparkPostAPIKey", "...", "options": {"useHerokuSPAPIKey": false,
"isSendgridCampaign": false, "useSandboxDomain": true, "startingDelimiter":
"%", "endingDelimiter": "%"}}'

The Devil’s Details

Not all email template features were made the same so there will always be some interesting edge cases to consider as you migrate. Here are a few key differences to consider when coming from SendGrid to SparkPost.

  • SparkPost uses a single template featureset for both transactional and marketing content.
  • SparkPost templates support logic, iteration and structured substitution variables so once you migrate, you can do more with your email.
  • SendGrid transactional templates have several different ways to personalise each email including the body tag, substitution variables and sections. SparkPost uses a simpler model: you only need substitution data to personalise each template for a recipient.
  • SparkPost handles only “global” unsubscribes and not SendGrid’s preference group concept.

You can also read our SendGrid migration guide which covers the broader task of bringing your email activities over to SparkPost.

Getting Help And Learning More

As always, if you run into an issue, have a how-to question, or you’d like to talk your specific situation through, come speak to us on SparkPost’s community Slack team. If you have a tool-specific issue or query, you can open an issue in GitHub. Our template syntax documentation is here and also check out our sample templates.

Contributions: Giving Back

The SendGrid template migration tool (which really needs a better name) is a community project. For it to be as useful as absolutely possible, we’d love to hear your feedback and we’d especially love your own contributions.