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

Mailgun has announced some changes to their business, and our team has been helping Mailgun customers who are interested in other options.

If you’re a Mailgun customer who is considering moving to SparkPost, you’ll definitely want to use our new Mailgun to SparkPost migration guide to make the transition quick and painless. Here’s a quick overview of how to get started when you switch from Mailgun to SparkPost.

Terminology You Should Know When You Switch from Mailgun

Every email delivery service has its own vocabulary, and SparkPost is no different. To ease the transition from Mailgun, our migration guide leads off with a terminology section that helps you quickly understand what we’re talking about when we mention a sink server (“test mode,” in Mailgun’s parlance) or discuss relay webhooks (routes).

Getting up to speed on terminology will also help you better understand SparkPost’s support articles and API reference documents. And doing so will definitely help you sound informed when you chat with others on our community Slack channels.

How to Get Started When You Switch to SparkPost

After you’ve taken a crash course in how to speak SparkPost, and you’re ready to flip the switch on your migration, you’ll want to sign up for your free account. You can track the progress of your onboarding tasks in your dashboard, as detailed in the guide.

One of the onboarding steps involves sending a test email or two from your SparkPost sandbox, which lets you explore what you can do with your new email service. You’ll find it’s a little more robust than what Mailgun offers.

Migrating Sending Domains and Suppression Lists from Mailgun

When you’re ready, you can add your sending domain to your account and have SparkPost verify that you own it. Our guide explains how to do that. (If you send email on behalf of multiple customers through their sending domains, you can set up subaccounts in SparkPost, which are the same as Mailgun’s per-domain SMTP and API credentials.)

You’ll also want to migrate your suppression list of invalid addresses and recipients who have unsubscribed from your mailings or who have complained about your messages. This is key because if you start sending to those addresses again, you’ll likely incur very high bounce and complaint rates. Unusually high bounce rates trigger alarm bells at ISP inbox providers and erode your sending reputation. High bounces and complaints also can cause us to suspend your account from sending while you sort it out. That’s why it’s much better to get it right from the start!

You can manage your suppression list within the SparkPost web app or use an API endpoint for bulk uploading your current suppression list.

Sending Email with SparkPost’s API Transmissions Endpoint vs. Mailgun’s API Messages Endpoint

The rest of our migration guide covers key information you should know about using SparkPost compared to Mailgun, starting with migrating to our REST API. Our transmissions endpoint is broadly equivalent to Mailgun’s messages endpoint, although SparkPost uses top-level API endpoints in most cases. The guide gets into more detail, including an explanation of the tools you can use to call the SparkPost API directly.

You can also send email over traditional SMTP in SparkPost. We’ve added the ability to set metadata, tags, and configuration options with a custom X-MSYS-API header in your messages, which is similar to Mailgun’s X-Mailgun_ headers. You can learn more in the SparkPost SMTP API reference documentation.

Comparing Templates in Mailgun and SparkPost

If you’re familiar with Mailgun’s recipient and template variables, you’ll be at home with SparkPost’s templates, although there are some key differences covered in our migration guide.

Tracking Your Email Activity in SparkPost

You get two levels of tracking information with SparkPost, starting with aggregate metrics that are richer and more complete than Mailgun’s stats. The guide has all the details.

SparkPost also offers a message events API endpoint that’s functionally similar to Mailgun’s events capability. You can create as many webhooks as you’d like, compared to Mailgun’s limit of one webhook per domain and event type. The guide has a table that maps each Mailgun event to its SparkPost equivalent.

Inbound Email: Relay Webhooks and Mailgun Routes

Our migration guide concludes with an explanation of how SparkPost’s relay webhooks process and forward inbound email, which is similar to Mailgun’s routes mechanism and its forward() action.

Want More Info about Switching from Mailgun? Let Us Know!

Our Mailgun migration guide should cover everything you may have questions about when you switch from Mailgun to SparkPost. Of course, you can always chat with our team on Slack. And for more help with configuring and using your SparkPost account, you can peruse our support articles and contact our support team.


Biz Eval Guide Blog Footer

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.