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:

1. Send emails using the SparkPost API.
2. Keep track of bounced emails using webhooks.

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.

  1. 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.
  2. 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.
  3. Configure Mautic email settings
    From your Mautic dashboard, go to Settings > Configuration > Email Settings. Choose SparkPost as your “Service to send mail through”, and paste in your API key. Press “Test connection” to make sure things are working. Note that after testing, your API key may not be visible, but your test should still work.
  4. Add your sending from name and address
    Make 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.
  5. Send a test email
    Press the “Send test email” button, and Mautic will send a test email through SparkPost to your Mautic user account email address. When you’re done, hit “Save & Close” in Mautic to make sure your email configuration settings are applied.
  6. You’re (almost) ready to send
    Okay, 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:

  1. 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

    CORS settings for Mautic and SparkPost

  2. Create and configure webhook in SparkPost
    In 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:

    SparkPost webhook setup

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

  3. 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.
    Bounces segment filter in Mautic
    Save your new segment, and you’re done!
  4. 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.

Remember to take advantage of SparkPost Help, Mautic on Slack, and the community forums too.

If you find errors in this guide or want to suggest improvements, please contact me!