A few months ago, I wrote about our adventures building a brand new project using React. Our existing SparkPost app was built many moons ago in the ancient framework known as AngularJS. In that earlier post, I said (and I quote), “So what about that 50,000-line Angular app? We won’t be migrating it to React, at least not directly.” Well, we’re migrating it to React. Directly.

It wasn’t that I lied, but let’s say I was a victim of my own lofty idealism. Shortly after that article was published, I started in on my plan to improve the Angular app. After almost two weeks of struggling to get Bower out of the project, I was immediately rethinking all of my ideals and life choices. I’d tried one thing and it was hard. It was time to leave ideals behind.

The Pivot

In all seriousness, we considered a couple of other wild ideas like writing React inside of Angular or migrating everything one page at a time. Ultimately we realized that the fastest and safest way to rebuild our entire app in a brand new framework was to do exactly what I’d publicly ridiculed: direct migration, i.e. a parallel rebuild. The big question was would SparkPost get behind this big idea?

The Pitch

Before I go on, I should explain something very clearly. The chance to completely rewrite your existing app from scratch is a rare occurrence in the world of engineering. If you come away from this article thinking, “I want to totally rewrite OUR app!”, you should know that you’re going to need a Very Good Pitch (and some flexible decision makers willing to carve you a good chunk of time).

That said, there’s tremendous value in the chance to rethink and rebuild your entire user interface as a singular, consistent unit instead of continuing to stack more cards on top of a shakier and shakier house. SparkPost got on board with the rebuild and we started in on a plan.

The Plan

So how do you rebuild an entire web application?

Step 1: Catalog and build a solid foundation of reusable components, design tools, and critical features like authentication.

Step 2: Draw the rest of the [censored] owl.

To be honest, our original plan was only slightly more fleshed out than that, and we’ve shifted and adapted it a lot along the way. Here are a few of the pieces we’ve been most happy about and that have helped us prepare for maximum owl-drawing.

  1. Focus: Our entire application team has always been “full-stack”, bouncing from back end to front end and back. As we’ve grown we’ve recognized a need for a core group of folks who can completely focus on a project like this front-end rebuild. That kind of focus helps us maximize efficiency and create the best foundation possible. It also allows us to be a  bridge to the rest of the team about how this new app is built and, eventually, how they can contribute.
  2. Modular design: Jon Ambas, our front-end engineer and design lead (and my main partner in the early days of dreaming up this plan), has been all-in on creating a fully-featured component library to make our work in React a lot simpler and more visually consistent. We now use Matchbox throughout the app and rarely have to think about CSS for anything except custom corner cases.
  3. Openness: Client-side code is already public when it runs in your browser. Therefore, I saw no reason to keep the code private in a repository.  We don’t expect anyone will use this code but us (please don’t). It’s already been nice to be able to point to examples of things we’re doing and link directly to the code in GitHub.
  4. Testing and Monitoring: This has been a big goal of the rebuild work we’re doing. Our Selenium-driven functional tests in Angular were taking hours to run and constantly failing until we finally turned them off completely. In the new app, we’re writing lots of tests (👋 snapshots) but we decided early on that we’ll never be able to predict every bug with test cases. For that reason, we’re also investing in real-time error logging and monitoring. No more waiting for a customer to report an error introduced in a deploy that went out 8 hours ago. Fast stable tests supplemented by error monitoring is our new way forward.
  5. “Preserve and improve” as a redesign strategy: In other words, we’ve preserved the architecture of the app. Leaving most things generally in the places you’d expect to find them. Avoid incredibly drastic changes that would require lots of approvals, user testing, etc. We’ve also taken every opportunity we’ve had to make easy, obvious improvements as we rebuild each part of the app. The result so far feels like an incredibly fresh coat of paint on a familiar base. Which will hopefully help us when we roll the new app out to our existing customers.
  6. Rollout: Incremental rollout, to be specific, is the last big part of our very big plan and probably the least-well-defined at the moment. We know we want to incrementally roll the app out to users (randomly and/or by allowing users to opt-in) so we can test out how it works for real use-cases before we unleash it on everyone. We’re still looking at options for this, but getting the rollout right will be one of the most important parts of our plan overall.

The Point

The takeaway here is that you should be skeptical of anything I say, especially if it sounds good or idealistic. When it comes to something like application development, being practical is almost always better than being pure.

Happy owl-drawing!

Jason Rhodes

sendgrid migration guide

This guide is here to help make your move from SendGrid to SparkPost as smooth as possible. We’ll walk through the key setup steps and highlight the differences in technology and terminology along the way.

Migrating from SendGrid to SparkPost

Email services vary widely, with their own nomenclatures, features and target markets. All of this makes the task of moving your business between email services more complex. To lighten the load on our new and prospective users, we have published our SendGrid migration guide.  Whether you are evaluating alternatives, estimating level of effort or planning a move to SparkPost, the migration guide provides quick answers and guidance on migrating to SparkPost.

To ensure a smooth transition, it’s a good idea to check out the SparkPost features matching those you already use with SendGrid. The guide’s terminology section provides common terms across both services so the reader can google with ease. That way, you can search through SparkPost support articles and dig into the API reference docs for deep detail. You can also use it to sound informed on our community Slack channels.

With the language barrier out of the way, our guide walks through the basic onboarding steps using SparkPost’s built-in progress checklist and covers a few key tips along the way. We cover how to migrate your suppression list from SendGrid along with details on translating between the two APIs. Finally, we finish up with a review of tracking email recipient activity and how to handle inbound email.

…and that’s about it. This has been our guide to the SendGrid to SparkPost Migration Guide. When writing these guides, we try to walk an onboarding path through our own service with one eye always on questions and concerns our users may have.

— Ewan

Did we miss something? If you have a question or topic not answered in our guide, please let us know!

You can find us on Slack or Twitter to chat about migration, email APIs or just to shoot the breeze with like-minded developers.

Mandrill Template Migration

In the weeks since MailChimp announced that they have eliminated Mandrill as a stand-alone offering, our team has heard from lots of developers looking for a Mandrill alternative. And, as our lead product manager Amie Durr wrote about subaccounts and other enhanced SparkPost features, it’s been epic feedback that’s really helped us focus on what developers need to be productive.

And near the top of the list is making it easy to import Mandrill templates into SparkPost. That’s something we’ve heard, loud and clear. I sometimes think about email templates like Gollum thought about his ring: precious and powerful, and messing with them can have tricky side effects. Along with branding and structural layout, templates also are shot through with personalization markers—we call them substitution variables, Mandrill says merge tags—that are designed to tailor each recipient’s message with content meant just for them. When you couple that intrinsic complexity with the fact that our respective platforms work differently, you might fear you’ll have a potentially challenging migration task ahead, especially if you have lots of templates.

So, that’s why I’m really happy to announce our newest community project: an open source Mandrill template migration tool that makes it really easy to import Mandrill templates into SparkPost. (Or, as I like to call it, the Mandrill-to-SparkPost Templatizer 3000. That’s MST3K for short ;-).

For the impatient and technically minded, you can just grab the code from GitHub and follow the README. For the more prudent, read on for details about how it works, how to use it, where to get help—and also how you can help out with this project.

Deployment: Where Can I Get MST3K?

First things first: where can you get your hands on the tool?

The Easy Way: Heroku

If you’re developing with Heroku, you can just click this button to deploy MST3K into your Heroku account. Done.

Deploy to Heroku

Once the Heroku deployment completes, you’ll be presented with the web UI.

The Other Way: Run Locally

If you would rather deploy the tool into your own environment, here are the minimal steps. Note: you’ll need to have git  and Node.js 0.12+  installed.


Once the install is complete, you can access the web UI at http://localhost:3000/ .

Whether you deployed in Heroku or locally, the UI will look the same:

 

Mandrill-to-SparkPost Template Tool MST3K UI

How-To: How Do I Use MST3K?

Translating Mandrill Template Content

Once deployed, the simplest way to use the tool is interactively. Choose the “Translate Template Text” option. Paste your Mandrill template code into the left pane of the UI and hit “Translate!” Your translated output will be presented in the right-hand pane, ready to copy-and-paste into SparkPost.

 

Mandrill-to-SparkPost Template Tool MST3K Translation UI

Automating Mandrill Template Migration

Now, one-off, interactive conversions are all well and good, but you might prefer to automatically pull a template from Mandrill, translate it, and upload it directly into your SparkPost account. You probably want the migration to take both the plaintext and HTML template code into account, as well. I got you. Choose the “Migrate a Template” button on the main menu to begin. Here’s how it works:

 

Mandrill-to-SparkPost Template Tool MST3K Migration UI

Mass Mandrill Template Migration

OK, but what if you have lots of templates to migrate all at once? Because the UI is just a presentation layer on top of an API, it can be automated to fit your needs. Here’s an example which uses curl to call the migrate API endpoint directly:


You also can call the /api/translate  endpoint in a similar manner. For much more detail on the API, checkout the README and the code on GitHub.

Capabilities: What Can and Can’t MST3K Do?

So, what template capabilities translate from Mandrill to SparkPost?

If you are unsure of whether your template is migratable, the simplest option might be just to try it: the tool attempts to present useful error messages.

MST3K is designed to translate a Mandrill template that uses Handlebars-style syntax into equivalent SparkPost templates. Here, “Handlebars syntax” means templates that use curly brackets around their variables like this {{firstName}}.

To learn more, or for reference as you read on, it might be helpful to bookmark Mandrill’s Handlebars documentation and SparkPost’s substitutions variables docs. And, the official Handlebars documentation as well. Note that Mandrill has made a few syntax additions which are marked below as “Mandrillisms.”

The rest of the section gives samples of supported Mandrill syntax along with some equivalent SparkPost terminology for reference.

Basic Template Handlebars Syntax

Our MST3K migration tool can translate the basics like this:

Syntax
Mandrill
SparkPost
Variable substitution
Conditional logic
Iteration

Mandrillisms

Mandrill made a few additions to vanilla Handlebars which we can also translate:

Syntax
Mandrill
SparkPost
elseif
Conditional expressions

Inline Helpers

Mandrill has a set of “content formatting helpers” which our migration tool understands but ignores, because there is no equivalent in SparkPost. The helpers currently accepted are the text case conversions: upper , lower , and title . The result post-translation is that those helpers are removed. Here’s an example:

Mandrill
Translated result
{{upper firstName}} {{firstName}}

Unsupported Elements

Finally, there are couple differences between a Mandrill template and a SparkPost template to be aware of when migrating:

  • Inline helpers: the url, date, and striptags helpers have no equivalent in SparkPost.
  • Block helpers: the unless and with block helpers have no equivalent in SparkPost.

MailChimp Template Syntax

By the way, what about MailChimp syntax? Although our support for MailChimp syntax is more limited, we do have early support for MailChimp syntax, thanks to a community contributor. Woot! Our community is pretty epic. Not sure if you’re using Mandrill or MailChimp syntax? Here’s the test: if your templates have {{curly brackets around substitution variables}}, you’re using Mandrill syntax. On the other hand, if you have variables in your template like this:  *|firstName|*, you’re using MailChimp syntax.

Help: Where Can I Learn More about MST3K?

As always, if you run into an issue, you have a how-to question, or you’d like to talk your situation through, come speak to us on SparkPost’s community Slack channel. For template and other code samples, integrations, and more, be sure to check out the SparkPost Developer Hub.

Contributions: How Can I Help Improve MST3K?

As with all community projects, MST3K stands on the shoulders of giants. To help make the tool as awesome as possible, we welcome all contributions from Mandrill and SparkPost users alike. Whether you open an issue, submit a pull request, or come share your experience with the community, we’d love to hear from you.

Let’s Build Something Awesome!

So, there it is: the Mandrill-to-SparkPost Templatizer 3000 is ready to help folks in need of a Mandrill alternative to make it easy to migrate Mandrill templates to SparkPost. I hope this addition to your toolbox serves you well!

—Ewan

Biz Eval Guide Blog Footer