Mautic and SparkPost Email Setup Guide

You’ve installed Mautic, and now it’s time to set up an email delivery service. Not sure exactly what to do next? This post will walk you through the basic setup for Mautic and SparkPost. You will learn how to:

If you’re already comfortable working with email delivery services, setting up your own mail servers, etc. then this post is not for you.

But if you’re just getting started with email delivery or would like a straightforward, step-by-step guide, then keep reading! You don’t need advanced technical skills to set up Mautic and SparkPost, but you should be able to follow instructions and create/edit DNS records.

1. Sending emails with Mautic and SparkPost

Before you dive into Mautic’s settings, you need to get things ready in your SparkPost account.

Set up your sending domain in SparkPost
Follow these instructions to set up your account: Getting Started with SparkPost. You will add and verify a sending domain, and then wait for SparkPost’s “compliance check” to approve your domain. To receive approval from SparkPost, you must have a live website with actual content on it. You cannot have a placeholder or “coming soon” page. Check out SparkPost’s website requirements for more info. You will not be able to send any email until your domain is approved.

Create an API key
In your SparkPost account, go to Account > API Keys, and create a new API key. Give it a name (can be changed later), and select all permissions. Click the “Add API Key” button, and make sure you copy and save the key that displays. This full key will only be visible one time.

Add your sending from name and addressMake sure you use a “send from” email address that uses the domain you verified with SparkPost! If you try to use an email with a non-verified domain, you will have trouble sending.

You’re (almost) ready to sendOkay, great job – you’re now ready to send emails with Mautic. But before you do, it’s important to set up a way to manage any bounced emails. Otherwise you might unknowingly send email to addresses that have bounced – very bad for your sending reputation!

2. Keeping track of bounced emails in Mautic

When you send email with Mautic and SparkPost, you can actually log into SparkPost to see which emails bounced, were delayed, etc. That’s great, but what you really need is to have Mautic mark bounces as do-not-contact.

Note: this approach uses webhooks – so you do not need to set up a monitored inbox. But you should already have Mautic and SparkPost configured using your API key from Part 1 of this guide.

Credit for this information goes to Luiz Eduardo. His original post is in Portuguese, so I thought I’d include the same details here, but in English.

Let’s get started:

CORS – either disable, or add SparkPost domains
If you are not using CORS, you make sure it is disabled: Settings > System Settings, look for “CORS Settings” and set “Restrict Domains” to “No”. If you are using CORS, you probably know what it’s for. In that case, you should add these domains as trusted:

sparkpost.com

app.sparkpost.com

api.sparkpost.com

developers.sparkpost.com

Create and configure webhook in SparkPostIn your SparkPost account, go to Account > Webhooks, and click the “New Webhook” button. Give your webhook a name, such as “Bounces”. The target URL should be:

http://your-mautic.com/mailer/sparkpost/callback

Replace http://your-mautic.com with the URL for your Mautic install.
For the webhook Events, select the events shown in the image below:

When you’re done, click the “Add Webhook” button. You should see a success message like this:

Set up your “Bounces” segment(optional, but recommended)
With your webhook set up, Mautic will begin marking any bounced emails as “Do not contact”. To make it easier to see which emails have bounced, you can set up a “Bounces” segment in Mautic. From your Mautic dashboard, go to your Segments and click the “+New” button to create a new segment. Name the segment “Bounces” or something similar. For the filter, choose “Bounced – Email” equals Yes.
Save your new segment, and you’re done!

Now what?Going forward, Mautic will automatically mark contacts with bounced email as “Do not contact”. Your mautic:segments:update cron job will then add those contacts to the new “Bounces” segment you just created. Now that you’re all set up, what about starting with a basic newsletter? Check out my guide to sending newsletters with Mautic.

Troubleshooting and Errors

If you run into trouble, double check that your SparkPost sending domain is set up correctly. Also make sure that your webhook settings in SparkPost are set to process immediately (in Mautic: Settings > Configuration > Webhook Settings). If they are set to “Queue Events Only”, you will need to add the mautic:webhooks:process cron job to process your bounces.