So, you've got a "cold" email list? An email list that you didn't reach out to in a while?

Well, this happens to the best of us—it sure did to me. But no biggie! You can fix that.

With a well-crafted reengagement email, you can warm your audience up again. Let's dive into how to create an email that'll make your subscribers sit up and take notice.

Here's an easy-to-follow structure you can use to create your reengagement email:

1. Address the elephant in the room: How long you've been away.
2. Come clean: Why you left your email list hanging.
3. Reintroduce yourself and your business (because, hey, they might have forgotten).
4. Remind your audience how/when/why they signed up.
5. Offer some value (because who doesn't love free stuff?).
6. Make it easy to say goodbye (if they really want to).

Let's break it down, shall we?

How long you've been away

The hardest part is always the beginning.

It's like dialing the number of a friend you haven't called in months (sorry, Michael😕!), hearing the ringing tone, them saying “Hello”, and, finally, having to say something.

But I know you got this! Just state the obvious:

Acknowledge that time has passed. It could be something like:

Hey there!

It's been a while since I've been in touch… about 6 months, give or take a few days of procrastination. 😅

And it's totally on me!

This shows you're aware of the silence and aren't trying to sweep it under the rug.

But now what?

Why you left your email list

Next, give them the lowdown on why you've been MIA. Be honest, be human. Maybe you were:

• Overhauling your entire product line.
• Moving across the country.
• In need for some personal/family time.
• Taking a sabbatical to recharge your creative batteries.
• Battling a severe case of writer's block.

Whatever the reason, let them know. Transparency goes a long way in rebuilding trust.

Let me be totally honest:

I needed some time to [(re)create my products/website; rethink my business direction; move; spend time with my family; recharge].

Reintroduce yourself and your business

Let's face it: After a few months most of your readers will have forgotten about you and what you do.

Yup, this stings. But be honest:

How many newsletters did you subscribe to and forgot about it (many, anyone)? Did you ever notice if one went dark? Yeah, neither did I.

So, give your reader a quick refresher on who you are and what your newsletter/business is all about. Keep it short and sweet, like:

In case you've forgotten (and I wouldn't blame you if you had), I'm Toby, the guy behind Audienture. I'm all about helping folks like you make the most of Mautic's awesome marketing capabilities.

Maybe link to your about page.

In addition to this, there's another thing your readers might have a hard time remembering that you should address.

Remind them how/when/why they signed up

I'm 100% certain that even in an active list less than 50% know why and less than 10% know when they initially signed up to your list.

You should remind them about when and why they joined your list in the first place.

Yes, this can be hard. Perhaps it's impossible because you don't have any records about this. Some ideas:

• Did they download a lead magnet?
• Sign up for a webinar?
• Received a free call?

If you have no records to personalize this, then you might talk about your best converting (or two) lead magnet(s). 80/20 rule at its best 😉

Whatever it was, remind them of the value they were expecting to get (and got) from you.

You (most likely) signed up for [incentive/lead magnet]. If you can't find it anymore, [I attached it to this email / you'll find it (here)].

Some people will remember; others won’t. Regardless, the next part is crucial for gaining goodwill at this new beginning with your audience.

Offer them something valuable

Now is the time to deliver value to your readers! I mean, that's why you reach out to them, right?

Offer them something new and exciting. It could be:

• An exclusive, unpublished lead magnet.
• A free mini-course.
• A special discount on your products or services.
• etc. you know the lead magnet drill...

You can say something along the lines:

I want to make it up to you. And I'd like to say thank you again for trusting me with your email. Please find this exclusive [freebie] on [topic]. You can expect to find A, B, C.

You said “Hi”, “Sorry”, and gave them something. Now what?

Try to make them reconnect with you

Just like with your welcome email: Use this email to (re)connect with your audience.

6 Essential Elements of an Excellent Welcome Email

You have probably heard this before: There is no second chance for your first impression. Your welcome email is your email marketing equivalent to a real-life handshake and introduction. The question is: How do you win at this kind of first impression? In my opinion there are two things to

AudientureTobias

Learn what's happened in your reader's life. What changed for them?

What have you been up to?

As a bonus I’m also giving away five thirty-minute one-on-one [your service] consultations. Hit reply, tell me about your challenge and I might cime in.

Now, the email is almost done. But there is still one crucial element missing.

Make it easy for them to unsubscribe

I know, I know. The last thing you want is for people to leave your list. But here's the thing:

There's a good chance they're not interested in it anymore.

Time didn't stop for you, nor for your readers. So, their interests might have shifted.

Thus, it's better for the both of you if they unsubscribe.

Include a clear, easy-to-find unsubscribe link. You might even say something like:

If you're no longer interested in [your topic], no hard feelings! You can unsubscribe (here). I'll shed a tear, but I'll understand.

That's it!

This is my blueprint for creating a reengagement email. You can use it to wake up even the coldest of email lists 😉

Be Genuine and Offer Value

Remember, the key is to be genuine, and offer some value.

Have you tried sending reengagement emails before? What worked for you? What didn't? I'd love to hear about your experiences!

Happy marketing, and may your open rates be ever in your favor!

In my opinion there are two things to consider:

1. A welcome email must strike a balance.
2. There are certain elements a good welcome should have.

Let's start by looking at the balance that you should seek:

What Makes a Good Welcome Email?

Your welcome email is like a first date:

You want the other person to get to know and like you (and, eventually, trust you). But at the same time you yourself want to get to know this other person, too.

You won't learn anything about them if you just talk about yourself.

What's worse:

You will come off as some unlikeable self-centered person if you make it all about you.

The outcome for your business?

You won't learn anything about your audience.

How can you strike a good balance in your welcome email?

I'd say: If you include the following 6 elements of a good welcome email you'll automatically make your best effort to strike that balance.

6 Key Elements of a Good Welcome Email

Let's explore those six key elements.

1. Introduce Yourself

First things first—let your new subscriber know who's behind the emails they'll be receiving. This is your chance to make a personal connection!

I know, it's kind of a “Duh!” thing to say. But more often than not a welcome email is just about the business.

Or worse: A simple "Hi there, welcome! [the end]"...

How to nail it:

• Don't just say “Hi!”. Share a bit about your background. Share a personal story. You'll probably talk enough business in the emails to come.
• Add a personal touch—maybe a fun fact or a quirky detail about yourself [or your company].
• Consider including a photo to put a face to the name.

Remember, you're not just a marketer—you're a real person with interests and experiences. Let that shine through!

2. Explain Your Why

Next up, share your mission.

What drives you? Why did you start your business? More importantly:

What are you trying to achieve? What impact do you want to make for your readers?

How to nail it:

• Clearly state the purpose behind your email list or business.
• Share what inspired you to start this journey.
• Connect your 'why' with your subscribers' needs or goals.

3. Showcase Your Expertise

You don't need to shy away in your first email. You already made them trust you enough to give you their email address.

And, you already told your readers what's driving you.

Now tell them what you achieved. Shine a light on why you're the go-to person in your field.

This isn't to show of. It is about reassuring your reader they made the right choice signing up to your newsletter/email list.

How to nail it:

• Include some sort of social proof in your welcome email. Like:
  • Share a few key achievements or experiences that qualify you as an expert.
  • Mention any notable publications or speaking engagements.
• Highlight unique insights or approaches you bring to the table. E.g., by linking key content that you created.

Okay, by now people know a lot about you. That's good.

But now it is time to make it about them!

4. Encourage Interaction

Make your welcome email the start of a two-way conversation.

Your goal should be that people reply to your welcome email.

So, make your readers hit reply! Entice them to write you.

How to nail it:

• Ask a simple, specific question related to your niche.
• Invite readers to tell you their biggest challenge. Offer to share some thoughts on what they write you.
• Let your readers brag. Ask them about their biggest success story.

Bonus: Besides forming a connection to your reader, a reply tells your reader's email program that they are interested in your emails. Gmail, for example, will make your future emails go straight to the inbox.

5. Provide Immediate (Additional) Value

This is—probably—a no-brainer. Simply because you offered a lead magnet or content upgrade in return for subscribing.

But, if there is a possibility to subscribe to your list without getting some sort of freebie:

Include something of value to your readers.

And even they already got (or will get) a freebie from you: You can “surprise” them with an additional freebie or something else that is of value for them.

How to nail it:

• Share a useful tip or strategy they can implement right away.
• Offer a free resource (e-book, template, checklist) related to your niche.
• Provide exclusive access to a helpful tool or community.

This can even be as simple as sharing a link to some content that you think is highly valuable to them.

You covered a lot by now (which doesn't mean you email is 5 pages long, keep it short, please).

Now, let's look at the final part.

6. Create Anticipation

Your reader got to know you. You showed them why you're doing what you're doing and why you're good at it. You provided them with value. What's next?

Create anticipation! Make the reader eager to receive your next email.

How?

End your welcome email with a teaser of what's to come.

How to nail it:

• Hint at an exciting topic you'll cover in your next email.
• Tease an upcoming series or special content.
• Create a curiosity gap by posing an intriguing question you'll answer later.

Aaand, you're done.

Keep It Short

It may sound like a welcome email like this would be thousands words long. And if you write your first draft, it probably will be.

I'd like to encourage you to edit your welcome email a couple of times. In the end your welcome email should be short.

Your welcome email would, ideally, a 2-3 minute read.

Your subscribers won't know you when opening this email. Chances are that a very long welcome email will not get read.

So, keep it short. Each of the sections should be one paragraph, two at most.

Time to Craft Your Perfect Welcome!

What about your welcome email? Does it check all the boxes?

Let's recap:

• Your welcome email should be about introducing yourself but also about getting to know the reader.
  • Get them to know, like and trust you.
  • Gain insights about your audience.
• Make it about you:
  • Introduce yourself.
  • Tell your reader something personal. Make yourself relatable and likeable.
  • Share your Why. What drives you?
  • Tell them why they should trust you. Include some social proof.
• Make it about them:
  • Ask them to introduce themselves to you.
  • Try to get them to share a pain point or big win. Both of these hold information about your audience.
  • Give them a bonus for signing up (besides that freebie!).
  • Make them curious and excited about what's to come.

By sticking to these elements you'll create a welcome email that'll knock your new subscribers' socks off. Remember, your welcome email is your first impression, so make it count!

Happy marketing!

This is where bounce management comes into play. This flag leads that reject your emails (e.g., because of a full inbox, invalid email address, or even a spam report 😱) as Do Not Contact.

How do you know that this really happens? If you want to make sure it does, you can test it easily, if you use Amazon SES/SNS.

Why Bounce Management Matters

First off, why should you even care?

Bounce management helps you maintain a healthy email list by removing addresses that caused an issue after emailing them.

Those issues could be:

1. Hard bounce: This is permanent issues like a non-existent email (e.g. a lead misspelling their email address).
2. Soft bounce: These are temporary issues like a full inbox, an email that is too big, or a server issue at email provider's server.
3. Complaint: The email was delivered correctly but flagged as spam by the recipient (or automatically by the email provider).

If you don't react to bounces you will harm your deliverability and sender reputation.

Too many bounces? You might just find yourself blacklisted.

Additionally, if you're using Amazon SES to send your emails, and you get too many bounces/complaints, then Amazon will suspend your account.

Luckily, it's quite easy to test proper bounce management.

How to Test Your Bounce Management Set-Up

Amazon SES provides two dedicated test email addresses to test your bounce management.

This means you can send emails to those email addresses and test how well your Mautic installation handles failures without the risk of damaging your reputation.

Email Addresses for Bounce Management Tests

The two email addresses that Amazon SES provides are:

• bounce@simulator.amazonses.com for bounces – it simulates an SMTP 550 5.1.1 "Unknown User" response. This is like a misspelled or non-existent email address.
• complaint@simulator.amazonses.com for complaints – it simulates a recipient marking your email as spam.

How to Test Mautic's Bounce Handling

Testing the bounce management is quite easy using those two email addresses. It's three simple steps:

1. Create a new contact in Mautic with one of the simulator emails.
2. Send a test email to this new contact.
3. Check the Result: If your bounce or complaint management setup is correct, Mautic should automatically flag this contact with a “Do Not Contact: Email” status. Give this process a couple of minutes.

If you want or have to run multiple tests without resetting everything, just append +label to the simulator email (e.g., bounce+test1@simulator.amazonses.com).

This lets you simulate different scenarios or tests without overlap.

You can find more information about this on the Amazon docs:

Sending test emails in Amazon SES with the simulator - Amazon Simple Email Service

Send an email to yourself from the Amazon SES console for the easiest way to experiment with sending emails using Amazon SES.

Amazon Simple Email Service

Happy Marketing!

Discover how to integrate external contributors safely into your or limit employee access to their core tasks within Mautic.

What are Roles?

Roles define what your Mautic dashboard users can and can not do. They are essentially predefined sets of permissions.

A proper role management allows you give people access to the dashboard without having to worry about security issues.

But what are roles and permissions exactly?

How are Roles and Permissions Related?

Permissions are specific actions that users are allowed to perform in Mautic. Examples are viewing or editing contacts, emails or campaigns.

Roles bundle these permissions into a package that is then assigned to users. This makes managing access to certain functionalities easy and scalable.

Now that we know that difference, let's differentiate roles and users.

Differences Between Roles and Users

The main difference is that a user is an individual with login credentials. A role is a set of permissions that can be applied to multiple users.

This means roles are about what users/persons can do, whereas the user is about who the person is that is interacting with Mautic.

Restricting access to certain functionalities of Mautic sounds great. How can you do that?

Before we dive into that, let's look at two best practices when it comes to creating access roles.

Best Practices for Your Role and Permission Management

There are two principles you might want to consider when creating your own role system in Mautic:

1. Principle of least privilege
2. Segregation of duties

Principle of Least Privilege

This principle suggests that users should be granted only the permissions they need to perform their tasks.

For example, someone who edits emails doesn’t need access to manage contacts. They have no business at looking at the contact database.

Implementing the principle of least privilege minimizes the risk of accidental or malicious misuse of sensitive information. If you have to comply with the GDPR or other data protection regulations following this principle is a must.

Segregation of Duties

This strategy involves splitting responsibilities and permissions among different roles to prevent any single user from having too much control.

This principle is more often than not about your business processes.

Let's say you have a couple of editors. They can create, view, and update emails, landing pages, and campaigns. But they cannot publish them.

In more general terms: The person who requests a transaction—publishing and sending an email—should not be the same person who approves it.

This ensures checks and balances in the workflow. This also makes sure people stick to pre-sending checklists or definitions of done or some other quality assurance mechanisms.

Roles for Mautic

If you have no role management at the moment, then here are some suggestions for roles you could implement:

• Content Creators: Can create and edit their own drafts of emails and landing pages but cannot publish. This role is great if you hire freelancers. They can work in Mautic directly, so you don't need to import their work manually.
• Content Collaborators: Those users can create and edit drafts of emails and landing pages regardless who owns the piece but cannot publish. This might be useful for proofreaders.
• Marketing Collaborators: Can create and edit drafts of campaigns, dynamic web content, focus items, and forms.
• Marketing Managers: Can review content, and campaigns, and have the ability to publish. They also can manage dynamic web content, focus items, and forms.
• Lead Owner: Can manage leads they own.
• Lead Managers: Can manage all leads and their segments, stages, and points.
• Administrators: Have full access across the platform, including user management and system settings.

You don't need to implement every role. Mix and match, pick and choose.

How to Configure Roles in Mautic

Setting up roles in Mautic is straightforward:

1. Navigate to the ‘Roles’ section in the Mautic settings.
2. Create a new role by clicking on ‘New’ and give your role a name that clearly describes its purpose.
3. Select and assign permissions to this role. Mautic will present you with a list of permissions divided into categories such as Contacts, Emails, and Reports. Tick the boxes next to the actions you wish this role to perform.
4. Once you fully configured the permissions of your new role, save it. Then assign it to users from their profile settings.

Gotchas of Mautic's Role Management

You might come across a few limitations that could impact how you structure your team's permissions. I'll show the limitations I could identify to help you better plan your roles and maybe find creative workarounds to fit your needs.

Single Role Per User / No Role Composition

What It Means: Mautic does not support role composition. This is a feature in some systems. You would create a role that is basically a superset of already defined roles. Alternatively you would assign multiple to a single user.

Drawbacks: Without this, you must manually set up each role with all necessary permissions, even if many roles share common permissions. This limits your ability to create layered permission structures easily. It also increases the potential for errors.

Workaround: You might consider restructuring tasks among team members to fit the permissions available within a single role. Although I'll admit that this may not always be practical.

Too Narrow or Broad Access Permissions

What It Means: In Mautic, the permission settings for viewing or editing items (leads, emails, pages, etc.) are generally limited to [create|view|edit|delete] own and [create|view|edit|delete] other. This means users can either see only the items they've created or all items, regardless of who created them. Unfortunately, there is no middle ground.

Drawbacks: This limitation makes it challenging to restrict access based on more granular criteria. You can't, for example, give users access to all emails of a certain category. Users might end up seeing more information than they need. This can increase the risk of someone editing the wrong thing or (worst case) of information leakage.

Workaround: You can temporarily set an editor as the owner for a specific email, page, etc., if they need to edit it. This is cumbersome but upholds the principle of least privilege.

Effective role management not only optimizes your team's workflow but also secures your data.

Implement some of the suggestions I made, but feel free to tweak everything that I said. Remember to review and refine your roles periodically.

Happy marketing!

But how do you get report data into a spreadsheet?

I'm excited to share how to pull any report data directly into Google Sheets using Mautic's API and Google's App Scripts.

What's that good for?

You'll get the full capabilities of spreadsheets to analyze your data. Here's an example:

Drip Campaign Drop-Off

I created a new drip campaign. I tested it with a bunch of new subscribers. Now, I wanted to know if there are points, i.e., emails where people click unsubscribe a lot. Spoiler: There is 😔

1. At first, I created a report with data source Emails Sent
2. For the data I added the email ID, their internal name, category ID and sent count as data columns.
3. I filtered the emails for this specific campaign that triggered people to click unsubscribed.
4. I grouped the emails by the ID field and added a calculated column COUNT Unsubscribed.
5. Then, I imported the data into my spreadsheet using the script below.
6. Finally, I created a line chart.

Here's the report set-up:

This is the result:

This made it obvious to me that two welcome emails are too much. An almost 10% unsubscribe rate is absurdly high.

Thus, I merged those two emails and shortened it. We'll see how this change will perform in the future.

So, how can you make this, too?

Just copy the spreadsheet I made into your workspace and start importing data. Plug and play! You don't have to code anything!

I developed a Google Apps Script that automates the process of pulling report data from Mautic into Google Sheets. This script is designed to fetch data from specific Mautic reports based on parameters you define, such as report IDs, and date ranges.

This allows you to do some complex data analysis—even if you dislike spreadsheets 😉.

But first things first:

Enable Mautic's API

First, you need to enable Mautic's API. I explained how to do that in this article:

How to Use the Mautic API

Are you looking to automate repetitive tasks or integrate Mautic with other platforms? Do you need to create, modify or delete a lot of data and want to use a script you wrote? The Mautic API offers a robust solution to fulfill your needs. 💡In this article: Learn how to

AudientureTobias

You need to enable HTTP Basic Auth for the script to work. It doesn't support OAuth.

Copy the Spreadsheet and Script

Mautic's REST API

Mautic comes with a complete RESTful API that lets you interact with almost any part of Mautic.

Just in case you're wondering:

What is an API?

An API, or Application Programming Interface, is essentially a gateway that allows one software program to interact with another.

So, in our case a CRM with Mautic or your script with Mautic.

If you're new to API's the question is: What's it good for? What's in for me?

Let me show you 3 benefits:

Benefits of Using Mautic API

With Mautic's API you can automate your marketing tasks. Here are some examples:

• Automation of Repetitive Tasks: Automate tasks like importing emails from another source, import, update, or edit contacts or contact lists, manipulate contact points or stages based on external triggers or calculations.
• Integration with Other Tools: Connect Mautic seamlessly with CRM platforms, e-commerce systems, or other marketing tools you use.
• Customization Possibilities: Tailor Mautic to your specific marketing needs by building custom integrations or functionality that’s unique to your business.

Use Cases

How to Load Mautic Report Data Into Google Sheets

Mautic’s reports are great. Having this data in a spreadsheet is even better. It allows you to analyze it, make custom charts and dashboards and even do some data analysis with your data. But how do you get report data into a spreadsheet? I’m excited to share how to pull

AudientureTobias

Enable the API

Before you can start making API calls, you'll need to activate the API in your Mautic dashboard. It’s a straightforward process:

(I'll explain further below on how to make your API access more robust and secure.)

Enable the API

First open the API configuration view: Go to Settings > Configuration > API Settings in your Mautic dashboard.

Then find the API Enabled? option and set it to Yes. This turns on the API functionality. It enables the API for use via OAuth. (more on that below).

Do you plan to use your own scripts? Then you want to enable HTTP Basic Authentication (more on this below, too).

Set Enable HTTP basic auth? to Yes. In a nutshell: This allows you use the API with your username and password.

Primer on Authentication Methods

Mautic gives you two options when it comes to API authentication:

• HTTP Basic Authentication
• OAuth Authentication

I'll give you a brief overview over those to. This should allow you to decide which method you use.

HTTP Basic Authentication

HTTP Basic Auth is a straightforward method where you send a username and password with each request. This method is like logging into your dashboard every time you want to change something.

To use the API with HTTP Basic Auth, you'd simply log into the API with your username and password.

This method is great for internal applications but less secure because it transmits your credentials in each call.

I use HTTP Basic Auth for my own scripts, because it's simple to use.

OAuth Authentication

OAuth is more secure, but also more complex. It uses tokens instead of sending credentials repeatedly.

This method is preferred for applications exposed to the public or where security is a bigger concern.

I use this method when I try to connect a web service, like Zappier, to Mautic. The app handles the OAuth logic and I get more security.

But before we talk security, let's learn how to use the API.

Making Your First Requests

Now that you've enabled the API, let’s get down to business. Making your first API is easy. I’ll break it down into simple steps using cURL.

Open your Linux or Windows terminal/powershell.

For this to work I assume two things:

1. You enabled HTTP Basic Auth.
2. You're using your admin user for full system and API access.

If you see something like this, then your user doesn't have the roles/privileges to make this particular API call:

{"errors":[{"code":403,"message":"You do not have access to the requested area/action.","details":[]}]}

Fetching data via the API

In our first interaction with the API we'll fetch some data from Mautic. We'll make a GET request for that. The basic structure looks like this:

curl -u 'api_user:api_user_password' 'https://mautic.yoursite.com/api/${endpoint}/${identifier}?${queryParams}$'

Breakdown of the command

1. curl: This is the command itself, used to transfer data to or from a server using various protocols, with HTTP being one of the most common.
2. -u 'api_user:api_user_password': This option stands for "user". It is used to pass the username (api_user) and password (api_user_password) for HTTP Basic Authentication.
3. What follows is the API URL: https://mautic.yoursite.com/api/${endpoint}/${identifier} It has three components:
   • Base URL: https://mautic.yoursite.com/api/ This is the (base) URL of your API.
   • Endpoint ${endpoint}: The endpoint gives you access to an API functionality. contacts for example lets you access your contact data.
   • Query Parameters: Query parameters let you filter data if you fetch data. They are optional.

What Happens When You Run the Command?

When you execute this command, curl makes a request to the specified URL. It includes the user credentials for authentication. The server at mautic.yoursite.com will:

• process your request,
• authenticate using the provided credentials, and if successful,
• return the (filtered, if applicable) data from the endpoint.

Fetch real data.

Let's try to fetch real data—the very first user; the user with the ID 1. This should be your admin user that you created during the installation of Mautic.

curl -u 'api_user:api_user_password' 'https://mautic.yoursite.com/api/contacts/1'

If successful, the (really long) response will look similar to this (I shortened it):

{
	"contact": {
		"isPublished": true,
		"createdBy": 1,
		"createdByUser": "Tobias from Audienture",
		"id": 1,
		"fields": {
			// very long and detailed list of all contact fields
			"all": {
				"id": "1",
				"firstname": "Tobias",
				"lastname": "from Audienture",
				"email": "info@audienture.com",
				// all contact fields in key: value format
			}
		},
		"owner": null,
		"ipAddresses": [
			// ..
		],
		"tags": [
			// ..
		],
		"utmtags": [
			// ..
		],
		"stage": null,
		"doNotContact": [],
		"frequencyRules": [
			// ..
		]
	}
}

If you get an error, you either don't have the right permissions or deleted the contact. Try another ID.

Let's try to add or change some data:

Use the API to create data

To create data you need to make a POST request to your API. You need to send a JSON body along with your cULR request. This body (also known as payload) contains the data you want to create.

curl -X POST -H "Content-Type: application/json" -u 'api:test123' 'https://mautic.mysit.com/api/contacts/new'  -d '{"firstname": "John", "lastname": "Doe", "email": "john.doe@example.com"}'

• -X POST: This option specifies the HTTP method to use. In this case, -X stands for "request method," and POST is the method used when you want to send data to the server. A POST request is often used for creating new resources or submitting form data.
• -H "Content-Type: application/json": This option adds a header to the HTTP request (-H). The header "Content-Type: application/json" tells the server that the body of the request is formatted as JSON. This is crucial as the API expects the data to be in JSON format.
• -d '{"firstname": "John", "lastname": "Doe", "email": "john.doe@example.com"}': The -d flag stands for "data" and is used to include data to be sent with the request. Here, '{"key":"value"}' represents the JSON-formatted data being sent to the server. This could be any JSON object, and in this example, it creates the contact with first name John, last name Doe and email john.doe@example.com.

Mautic's response to this request will be the newly created contact. I'll omit that.

What happens if john.doe@example.com is already a contact?

The email field is a unique identifier. This means that there can only be one contact in your database that has the email address john.doe@example.com.

Mautic will update the existing contact using the data you'll send in your POST request.

This means:

• Say, {"firstname": "John", "lastname": "Doe", "email": "john.doe@example.com"} exists in your database.
• And you'll make a POST request to /api/contacts/new with the payload {"firstname": "Peter", "company": "ACME", "email": "john.doe@example.com"}
• Then Mautic will update the contact's first name from John to Peter and add the company name ACME. So, your contact's data will look like this: {"firstname": "Peter", "lastname": "Doe", "company": "ACME", "email": "john.doe@example.com"}.

What happens if an error occurs?

If your data is malformed an error 400 occurs:

{
  "errors": [
    {
      "message": "Looks like I encountered an error (error #400). If I do it again, please report me to the system administrator!",
      "code": 400,
      "type": null
    }
  ]
}

Use the API to change data

If you want to change data, then your curl command stays almost the same. The "only" difference is the HTTP method used (and the data you sent with your API call, of course).

The HTTP method you'll use is either PATCH or PUT. Which you use depends on the behavior you expect from Mautic.

curl -X PATCH|PUT -u 'username:password' -H "Content-Type: application/json" -d '{"first_name": "Jane"}' "https://yourmauticinstance.com/api/contacts/123/edit"

Explanation of PATCH vs. PUT

This means PATCH doesn't create a new entity (e.g., a contact), PUT does. PATCH doesn't change data you haven't included in your API call, PUT does.

In the curl example above, PATCH would change the first name to Jane, leaving the remaining fields of contact 123 untouched. PUT on the other hand would empty all fields of contact 123 and only set first name to Jane, leaving you with an almost empty contact.

In more detail:

Choosing between PATCH and PUT depends on whether you expect the resource to exist and whether you intend to provide complete or partial data for updates.

Manage Security

Properly managing roles and permissions is important to make your Mautic API secure. You can use Mautic's role management system to achieve that:

When you access the Mautic API, the authenticated user's API access mirrors their user interface permissions.

How It Works

This means they can interact with the API endpoints exactly as they would within the Mautic UI, limited by their user role.

Let's assume you created a role called "Editor". This role is only permitted to create and edit their own emails.

A user with this role will only be able to access email-related endpoints in the API.

Simple, yet effective.

They won't be able to interact with emails someone else created. And they certainly couldn't modify your contact database, campaigns, or other elements outside their scope.

Basic Set-Up and Example

To minimize risks and ensure each API user can only access relevant data and functionalities, follow these steps to create narrowly scoped API roles:

• Navigate to the Roles section in your Mautic settings.
• Create a new role specifically for API access. For instance, you might have a role named "API Access - Contacts Script" for a script that only needs to manage contact data.
• Carefully select the permissions for this role. Only grant access to the necessary features that the API needs to interact with.
• Once your role is configured, create a user assigned exclusively for API interactions.
• Go to the Users section and create a new user. Assign the user the role you just created, ensuring they are configured to use API access only.
• Use strong, complex passwords for this user account, and consider changing passwords regularly to maintain security.

Let's assume you want to create/import users via a script. You create the "API Access - Contacts Script" role.

The most secure permission design for this is giving the API Access - Contacts Script role just the permission to create new contacts.

Now, even if your credentials leak, an attacker could "just" create new contacts. This might be a PITA, but your data is still secure. They could not read or modify or delete your contact database, campaigns or emails.

Handling Responses and Errors

Mautic will respond to your requests with JSON data. If your request is successful, you’ll get data related to your request, along with status codes like 200 OK.

If something goes wrong, you might see 404 Not Found or 500 Internal Server Error.

Familiarize yourself with common error codes. If you see 400 Bad Request, check your data formatting; 401 Unauthorized means there’s an issue with your credentials or user's role permissions.

Libraries

Mautic provides a PHP library to make interacting with your API easier: GitHub - mautic/api-library: Mautic API Library.

We went through setting up and the ins and outs of using the Mautic API. You're well-equipped to get started with using the API.

You will have to experiment with different API functionalities to get a grasp of what is possible, but I am sure, you'll find something that makes your marketing life easier.

After all, using the API gives you a powerful way to access your data and automate scripts.

If you have any questions, please shoot me a message.

Happy marketing!

Well, I can understand if you might be hesitant to jump straight into a third-party email service provider.

But what if I told you that you can (within limitations) use your good old Gmail account?

Using Gmail as your mail transport in Mautic can be a choice for testing and sending your first few emails in production.

Let's get you started.

Setting Up Sending Emails via Gmail with Mautic: A Step-by-Step Guide

To set everything up for your first email, you need to do 3 things:

1. (Enable 2-step verification and) create an app password in your Google account.
2. Install the symfony/google-mailer package.
3. Configure your mailer DSN in Mautic.

Prerequisite: 2-FA and App Password

Before you can use Gmail for sending your emails with Mautic you have to make sure your Gmail account is ready to handle third-party applications like Mautic:

1. Enable 2-Step verification (if you haven't, already). You can enable it in your Google account settings: https://myaccount.google.com/security
2. Generate an app password for Mautic to connect with your Google account. Do it here: https://myaccount.google.com/apppasswords

Here's the relevant Google help page: https://support.google.com/accounts/answer/185839.

After you've set that up, you can install Symfony's Gmail mailer.

Install Symfony's Gmail mailer transport

Installing the transport is easy if you installed Mautic via composer. It's a 3-step process:

1. Install Symfony's Gmail mailer transport via composer.
2. Clear your Mautic cache.
3. Reload your Mautic plugins (probably not necessary).

composer require symfony/google-mailer
php bin/console cache:clear
php bin/console mautic:plugins:reload

The last step is to configure the mailer DSN in Mautic:

Configure Your Mailer DSN in Mautic

To configure your mailer DSN in Mautic follow these steps:

1. Go to Settings > Configure > Email Settings > Mailer DSN.
2. Set Scheme to gmail (or gmail+smtp; it doesn't matter which one you use).
3. Enter your email address into the User field: your.email.address@gmail.com.
4. Use the 16-digit app password you generated earlier for the Password field.
5. Set Host to default and leave the fields for Port and Path empty.
6. Save your settings
7. Try to send a test email to confirm everything is working.

Behind the scenes, Symfony’s google-mailer connects to Gmail’s SMTP server (smtp.gmail.com) on port 465 using secure TLS encryption.

Troubleshooting Tips

If you encounter issues:

• Verify that you’re not attempting to use TLS with port 587. This seems to cause issues with PHPMailer: Source.
• You might be able to enforce a certain encryption type by adding an option to your mailer DSN: encryption=(tls|ssl). I did not test this.

Limitations and Considerations

While Gmail seems perfect for testing and small-scale use, remember it’s not designed for this.

Here are some limitations and considerations to think of when trying to use Gmail:

Sending Limits

Gmail allows you to send a maximum of 500 emails per day. See Gmail's help page Limits for sending & getting mail.

Also, Gmail might temporarily or maybe even permanently suspend your account for some reason.

Professionalism

Using a Gmail address for business communications might seem unprofessional.

It certainly does to me.

A free email provider address simply doesn't project as professional an image as a branded email addresses do.

Compliance Issues

Ensure compliance with data protection regulations when using Gmail, especially in a business context. Consult a data protection officer or an attorney if you're uncertain.

Sender Reputation

If you use Gmail you won't build sender reputation with your sending email address. This might hurt you later.

If you switch to a professional email service provider you might have strict sending limits until they trust you.

Also: Switching from xyz@gmail.com to newsletter@myprofessionalsite.com changes (obviously) your sending address. This sudden change can put your emails in spam or promotional folders.

But is this really the best strategy?

Can a little bit of friction help to get rid of low-quality leads in your email list?

Believe it or not, a little friction in your sign-up process might be just what you need.

Yes, this goes against conventional marketing wisdom, but stick with me.

Understanding the Value of Friction

Adding an extra step or question to your sign-up form might seem counterintuitive.

After all, the generally accepted marketing advice is to make things as easy as possible for potential customers. This includes the sign-up process.

Why?

Every action you demand from a lead (=friction) during a conversion bears the possibility that you confuse them. Or make them doubt if continuing really is the best use of their time. Or ...

One of these thoughts aaand: the lead is gone. Bummer!

But there's actually value in that for you. At least for the sign-up:

A bit of friction can actually help filter out leads who aren't truly interested or relevant to your business.

I'll tell you why I believe that:

How Friction Enhances Lead Quality

A client of mine does nutrition counseling. This is a huge field. She specializes on nutrition for athletes (especially female athletes).

Now, she can help men, or obese people, too. These are just not her ideal customers. Her funnel probably won't match their needs or interests.

We added a simple dropdown question to her sign-up form for athletes:

“What do you want to achieve by changing your diet?”
- Shorter recovery time
- Faster muscle growth
- Less injuries
- Better competition performance

This simple question helps her—and a bespoke one can help you for two reasons. And the second is the more powerful one.

Self-segmentation

By answering this filtering question during sign-up leads self-segment themselves for you. You instantly know better who's joining your list.

What's this good for?

This allows you to tailor your emails and offers to meet your leads specific needs.

While this in itself is helpful, here's the real benefit:

Deterring Subscribers

There is a high chance that a lead won't have a good quality, if they don’t find themselves in the categories you provided.

Take the example from above:

If a lead wants to lose weight or the best diet during pregnancy my client could help them. But her funnel isn't targeted for that.

The result?

The lead probably won't buy from her, eventually.

So, why have them in the email list in the first place?

If a lead struggles to answer this one filtering question they might decide this isn’t the right list to join—and they probably are right.

This naturally filters out leads who aren't interested in what you'll offer them.

How to Implement “Good” Friction

I hope, I could make it clear that friction can be beneficial.

But it is also relevant, how you introduce it to your forms. Here are some tips:

Make it relevant

The question should give you meaningful insight into your subscriber. This also means:

Your ideal customer (and then some) has to recognize themselves in the question and the answers you provide.

This demands some balance.

Anything too generic won't help you. Too detailed and you'll add too much friction.

KISS—Keep it simple

Yes, we're introducing deliberate friction. We have to keep it as low as possible, though.

Just ask for one extra piece of information besides, of course, the email address (and maybe the first name).

Decide if checkboxes, radio buttons, a dropdown, or even a free text input is the best approach. They all have pros and cons. Maybe A/B test them.

Test and learn

A/B test your new friction element. You want to know if this change is worth it, right?

What to test? In my opinion two things:

Visitor/Conversion Rate

How many visitors signed up with/without the friction element?

• Keep the friction element if you maintain a good conversion rate.
• If the friction elements caused a severe drop, change it and test again. Or drop it.

This can be done easily with Mautic's built-in A/B testing feature for landing pages.

Lead quality

You should also keep taps on your new leads during your test. Tag them (#friction) or add them to dedicated segments.

You need to measure if the friction element really improves the lead quality of this group of contacts.

A significant drop in the conversion rate is justified if the rise in lead quality makes up for that. Quantity ≠ quality.

Bonus test: friction elements

Over time, test different questions/approaches for your friction element. Measure how they affect your sign-up rates and lead quality.

Adding a question to your sign-up form isn’t about making it harder to join your list—it’s about making sure that those who join are exactly the right fit for your business.

It’s a strategic choice that can lead to a more engaged (and profitable) email list.

What are your thoughts on that?

Happy marketing

Mautic already offers some form of event tracking. But if you want to truly understand your data, you have to integrate Mautic's data with Google Analytics, Matomo or whatever website analytics software you're using.

This article shows you how to send tracking event data to Google Analytics or Matomo whenever someone interacts with your forms.

Why should you even bother?

Well, this data allows you to make optimizations to your content, your marketing and eventually improve your conversion (strategies).

You can gain valuable insights on what makes your leads or audience tick.

But let's start with how to implement the tracking.

A Form Submit Listener Doesn't Do the Trick

Just in case, you're wondering: A simple form submit event listener won't do the trick:

myForm.addEventListener('submit', function (event) {
	//trackEvent('Form submission'));
});

To make it short: This will give you total useless data. I'll explain why at the end of this article.

How to Read This Article

To make this guide available to people with different levels of Mautic/JS knowledge, I wrote it in three parts:

• If you're familiar with Mautic and/or JS, then the first section, which contains a brief explanation, will probably be enough for you.
• The second section explains adding form event tracking more in depth.
• The third section explains in detail how to add automatic and future-proof tracking to all your forms.

But first, let's look at why collecting this data is relevant for you.

Why Is Tracking Mautic Form Events Relevant to Me?

By tracking Mautic form events you can better understand how your audience interacts with your website and—especially—with your forms.

Most of the time, when a user (successfully!) submits a Mautic form, it means you have converted them. This could be for a newsletter sign-up, registering for a webinar, or booking a call.

Tracking these events along with page view (which Mautic kind of gives you) and page flow data (which Mautic can't give you) gives you two major advantages:

Data-driven decisions

By collecting this information you can base your marketing strategies on solid data, not guesswork.

You will know:

• Which landing pages do work?
• Which forms convert best? Which lead magnets?
• How many times or pages (and which?) do people visit before they convert?

For Matomo one of the reports might look like this:

This chart shows the number of people how signed up over time for a newsletter I run.

Optimize your conversion rate

You will learn, what works and what not. This allows you to:

• Use your new insight to try to replicate successes.
• Tweak underperforming forms.
• Promote your best performing forms on more or other places.

With some spreadsheet magic you can identify levers to improve your conversion rate:

In the example above I could identify

• one pages that has high traffic, but a bad conversion rate and
• one page that has low traffic but a high conversion rate.

Besides that you can use this data to create KPI dashboards and benchmark your success over time.

Eventually, all this leads to your content and marketing attracting higher-quality leads.

Tracking Mautic Form Events—Quick Explainer

Whenever you add a form automatically using <script type="text/javascript" src="//mautic.yoursite.com/form/generate.js?id=1"></script>, Mautic also adds the MauticSDK to your page.

The MauticSDK looks for the global MauticFormCallback object. This object is where you can define callbacks for various form events.

Whenever a form event happens, MauticSDK will look for an MauticFormCallback property named after your form.

If you add one of the several Mautic callbacks to this object, then the MauticSDK will execute it.

MauticFormCallback['replaceWithFormName'] = {
    onResponse: function (response) {
         // Insert your tracking code here
    },
};

Short, and simple, right?

If you want or need a little more in depth explanation, how this works:

Here it comes...

Tracking Mautic Form Events—High-Level Overview

As you probably know, adding a Mautic form to your site is as simple as dropping in a line of code:

<script type="text/javascript" src="//mautic.yoursite.com/form/generate.js?id=1"></script>

The JavaScript will load your form. And it sets the MauticSDK JS object up.

So, what's the deal with MauticSDK?

The MauticSDK allows you to hook into and respond to everything that happens at or with your forms.

Want to know when someone submits a form? And react to it?

There's a callback for that.

And these callbacks give you the ability to track all form events.

When someone interacts with your form, then:

1. MauticSDK checks for a specially named global JavaScript variable or object: MauticFormCallback.
2. It searches for a property within this object that matches your form's name: MauticFormCallback['yourFormsName']
3. Finally, it checks if you've defined any of the several Mautic callbacks: E.g., MauticFormCallback['yourFormsName'].onResponse

To track the result of a user's form submissions, you'd add an onResponse function to the MauticFormCallback object.

The MauticSDK triggers this function after a lead submitted a form and Mautic processed the data:

// window.MauticFormCallback['replaceWithFormName'] or just
MauticFormCallback['replaceWithFormName'] = {
    onResponse: function (response) {
         // Insert your tracking code here
    },
};

But how do I ensure this works with my forms?

All you have to do is to use the right formName. But this is a bit tricky.

Mautic names Forms automatically, based on whatever you called them in the dashboard. Therefore, these names can and will change.

And if you've hard-coded these names into your tracking setup, you would break your tracking by changing those names.

So, how do you avoid that “mess”?

By adding the callbacks automatically.

This way we don't hard-code the form names, but fetch them from Mautic. Nothing will ever break.

Let's dive into the details of setting up form hooks in a way that's not just effective but also future-proof.

Plus, we'll cover how to track everything (form submissions, successful conversions, failed conversions and errors) seamlessly.

The Strategy for Dynamic and Future-proof Tracking

To add tracking or any other form callback dynamically and future-proof, you need to:

1. Iterate over your forms.
2. Add callbacks to them.

Iterate over your forms

I read many forum posts and distilled my learnings into this article.

This guide walks you through the steps on how to do that. It also lists the errors you might bump into—along with solutions known to me.

Before You Begin: Backup!

Update Mautic Using Composer

Updating Mautic with composer is a bit tricky, because you need to manually change your composer.json.

I'll walk you through the update process step by step. It's a five main steps process. Let's dive in!

Step 1: Add Missing Repositories

First things first, you need to make sure your composer.json is ready. It has to have all the repositories it needs. Run these commands to add them:

composer config repositories.0 git https://github.com/mautic/FOSOAuthServerBundle.git
composer config repositories.1 git https://github.com/mautic/SpBundle.git
composer config repositories.2 git https://github.com/mautic/SymfonyBridgeBundle.git
# Update minimum required PHP version
composer config platform.php 8.0.2

This adds three new Mautic repositories to your composer.json. It also changes the minimum required PHP version to run Mautic to PHP v8.0.2

Additionally, you need to manually edit the composer.json. Composer needs to run some post-update scripts every time you'll update Mautic in the future.

Let's add them. Open your composer.json and overwrite to the "scripts" part with this:

  "scripts": {
    "githooks": [
      "php -r \"if(file_exists('./.git')&&file_exists('./build/hooks/pre-commit'.(PHP_OS=='WINNT'?'.win':''))){copy('./build/hooks/pre-commit'.(PHP_OS=='WINNT'?'.win':''),'./.git/hooks/pre-commit');} if(file_exists('./.git')&&file_exists('./build/hooks/post-checkout')){copy('./build/hooks/post-checkout','./.git/hooks/post-checkout');}\"",
      "php -r \"if(file_exists('./.git/hooks/pre-commit')&&(PHP_OS!='WINNT')){chmod('./.git/hooks/pre-commit',0755);} if(file_exists('./.git/hooks/post-checkout')&&(PHP_OS!='WINNT')){chmod('./.git/hooks/post-checkout',0755);}\""
    ],
    "post-install-cmd": [
      "@githooks",
      "@npm-ci",
      "@npx-patch-package",
      "@generate-assets"
    ],
    "post-update-cmd": [
      "@githooks",
      "@npm-ci",
      "@npx-patch-package",
      "@generate-assets"
    ],
    "test": "bin/phpunit -d memory_limit=1G --bootstrap vendor/autoload.php --configuration app/phpunit.xml.dist",
    "phpstan": "[ ! -f var/cache/test/AppKernelTestDebugContainer.xml ] && (echo 'Building test cache ...'; APP_ENV=test APP_DEBUG=1 bin/console > /dev/null 2>&1);  php -d memory_limit=4G bin/phpstan analyse --ansi",
    "cs": "bin/php-cs-fixer fix --config=.php-cs-fixer.php -v --dry-run --diff",
    "fixcs": "bin/php-cs-fixer fix -v",
    "rector": "bin/rector process --ansi",
    "npm-ci": "npm ci --prefer-offline --no-audit",
    "npx-patch-package": "npx patch-package",
    "generate-assets": "bin/console mautic:assets:generate"
  },

Step 2: Remove Old Packages

Before we bring in the new, let's clear out the old.

This step removes any plugins or themes that are obsolete in Mautic 5.

composer remove mautic/plugin-citrix mautic/theme-nature mautic/theme-mauve mautic/theme-coffee

Step 3: Update Dependencies

Next, update the package dependencies for Mautic 5. This step ensures that all the required packages are set to their correct versions.

# Core and essential plugin bundles
composer require --no-update "mautic/core-lib":"^5.0"
composer require --no-update "mautic/grapes-js-builder-bundle":"^5.0" "mautic/plugin-clearbit":"^5.0" "mautic/plugin-cloudstorage":"^5.0" "mautic/plugin-crm":"^5.0" "mautic/plugin-emailmarketing":"^5.0" "mautic/plugin-focus":"^5.0" "mautic/plugin-fullcontact":"^5.0" "mautic/plugin-gmail":"^5.0" "mautic/plugin-tagmanager":"^5.0" "mautic/plugin-outlook":"^5.0" "mautic/plugin-social":"^5.0" "mautic/plugin-zapier":"^5.0"
# Themes
composer require --no-update "mautic/theme-aurora":"^5.0" "mautic/theme-blank":"^5.0" "mautic/theme-brienz":"^5.0" "mautic/theme-cards":"^5.0" "mautic/theme-confirmme":"^5.0" "mautic/theme-fresh-center":"^5.0" "mautic/theme-fresh-fixed":"^5.0" "mautic/theme-fresh-left":"^5.0" "mautic/theme-fresh-wide":"^5.0" "mautic/theme-goldstar":"^5.0" "mautic/theme-neopolitan":"^5.0" "mautic/theme-oxygen":"^5.0" "mautic/theme-paprika":"^5.0" "mautic/theme-skyline":"^5.0" "mautic/theme-sparse":"^5.0" "mautic/theme-sunday":"^5.0" "mautic/theme-vibrant":"^5.0" "mautic/theme-trulypersonal":"^5.0"

Step 4: Run the Update

With everything set up, it's time to run the update.

This command updates all dependencies, ensuring that your Mautic installation moves smoothly to version 5.

composer update --with-all-dependencies
php bin/console cache:clear

Step 5: Run Post-Install Scripts

After updating everything you need to execute some maintenance post-install scripts.

These commands will apply any changes made to the core, migrate the database, and generate the new JavaScript and other assets for your dashboard.

php bin/console mautic:update:apply --finish
php bin/console doctrine:migration:migrate --no-interaction
php bin/console mautic:assets:generate
php bin/console cache:clear

Known Errors while Updating to Mautic 5 Using Composer

While updating you might bump into some errors. Here are a few issues that I know that you might encounter. Along with straightforward solutions to get you back on track.

Class XYZ Not Found Error

• Problem: You might see a fatal PHP error message about a missing class. The messages comes from ParameterLoader.php and looks, similar to this:

PHP Fatal error: Uncaught Error: Class "Symfony\Component\Filesystem\Path" not found in .../mautic/docroot/app/bundles/CoreBundle/Loader/ParameterLoader.php:198

• Underlying Issue: This usually means that some Composer dependencies haven't been installed correctly.
• Solution: Run composer update or composer install again to install any missing dependencies. If the problem persists, the Mautic forum is a great place to seek further assistance.

Warning About Unregistered Commands—The parameter "XYZ" must be defined

• Problem: When attempting to run Mautic, you encounter a warning about commands not being registered due to an undefined parameter:

[WARNING] Some commands could not be registered: In AppKernelProdContainer.php line 11207: The parameter "2F" must be defined.

• Underlying Issue: This usually happens if your email transport (i.e., SMTP, Amazon SES, etc.) password includes special characters. This occurs, because mailer_dsn is not properly configured, as the update process struggles with special character handling for some reason.
• Solution:
  • Open your config/local.php file.
  • Find the mailer_dsn line.
  • Comment it out by adding a # at the beginning of the line.
  • Then, clear the cache. Mautic should now run.
  • Afterwards, you'll need to reconfigure your mailer_dsn from your dashboard

For more details on this issue, check the discussion on GitHub.

npm ERR! code 137 During Installation/Update

• Problem: The NPM build process might unexpectedly terminate, showing an error like this

sh: line 1: 1563 Killed npm run build
npm ERR! code 137
npm ERR! path /var/www/mautic
npm ERR! command failed

• Underlying Issue: This error typically means the NPM build process is consuming too much RAM. As a result the web server kills the process to ensure it won't crash.
• My Current Workaround: Sync your Mautic instance to your local machine, run the NPM build locally, and then sync it back. Here's how you can do it on a Linux system:

cd /tmp
mkdir mtc
cd mtc
rsync -avz -e 'ssh -i ~/.ssh/id_rsa' user@domain.com:/var/www/mautic/ .
npm install
npm ci --prefer-offline --no-audit
npx patch-package
rsync -avz -e 'ssh -i ~/.ssh/id_rsa' . user@domain.com:/var/www/mautic

Tip: Make sure NPM is installed on your local machine for this workaround 😉.

Dashboard Usability Issues

• Problem: You might find that parts of the dashboard aren't working as expected. This can affect buttons or the campaign, email or page builders.
• Underlying Issue: This is likely due to missing JavaScript assets. Most likely because parts of the update process were skipped.
• Solution: Run the following commands to install the necessary assets and regenerate them

npm install
npm ci --prefer-offline --no-audit
npx patch-package
php bin/console mautic:assets:generate

That's a wrap.

I hope this steps helped you upgrade to the newest (and most promising) version of Mautic.

I am eager to use it.

PS If you run into errors go to the forum. You'll find help there.

Mautic 5 comes with some significant changes. Because of at least one you might want to wait for a bit before you update—as you could, for example, accidentally destroy your sender reputation.

With great changes come great challenges—or something like that...

Here's a list of things you need to be aware of before updating.

• How the switch to Symfony mailer transports slows your emails sending down and might even accidentally hurt your sender reputation.
• The need to have and run NPM (Node.js package manager).
• Removed Mautic core plugins.
• Changes to transactional email sending.
• Removing mautic:emails:send.
• The final death of the froala editor.
• Special character issues with mailer_dsn.
• List of known bugs in Mautic 5.

Switch to Mailer Transports

Mautic's shift towards using Symfony email transports and third-party plugins for email delivery means the built-in email transports are gone.

Personally, I find that problematic. From a user perspective this means a temporary regression. This is for two reasons:

1. Symfony's transports don’t support batch sending, even via API. As a result, you can only send one email per request, as opposed to a thousand emails per request as was the case with some Mautic 4 transports.
2. Symfony's transports don’t support transport callback handling. This was used for bounce management. The result: you lose the built-in bounce management.

(You can set it up another way, but you need to know that!)

I guess, this decision will turn out to be a very good step in the future. That is, because Mautic devs do not need to care about the mailer transports anymore.

They can focus more on the core.

But currently, post-installation, SMTP remains the sole transport supported out-of-the-box.

What this means for you:

1. You'll need to manually install your preferred mailer transport plugin.
2. You will (at least temporarily) lose Mautic's bounce management functionality if you do nothing.

Especially the second point can hurt your sender's reputation if you are not aware of this. Without bounce management you might be considered a spammer at some point.

3rd party plugins are meant to bring back the bounce management. There are two plugins already ready for productive use:

• Sparkpost
• Omnivery
• For Amazon SES a plugin is in development, but it will take a couple of weeks if not months until it's ready.

How to Install Mailer Transports

• Look for Symfony's mailer transport plugins that support your email service provider.
• They are listed in the Sending Emails with Mailer in Symfony Docs.
• Install these via composer.
• Configuring the Mailer DSN:
  • DSN is short for Data Source Name.
  • This essentially tells Mautic how to connect to your email service, including the type of service, credentials, and other necessary parameters.
  • You can set it up in the configuration dashboard.
  • The documentation page above tells you how to do that.

Configure Bounce Management

If you relied on Mautic 4's built-in callbacks that processed bounce management, you'll need to manually configure a Monitored inbox. Check the docs:

Emails — Mautic Documentation 0.1 documentation

Without it, email addresses that bounce an email won't get flagged DNC.

NPM as an Installation Requirement

The inclusion of NPM in the setup process marks a significant technical shift for

Mautic 5 means to enhance the installation and build process and asset management.

This led to the inclusion of NPM in the setup and update process.

I see main problems:

1. The NPM build process is resource hungry.
2. Some shared servers don't come with NPM.

If you encounter one of these two problems, try building the JS assets locally and sync them to your production environment.

• My Current Workaround: Sync your Mautic instance to your local machine, run the NPM build locally, and then sync it back. Here's how you can do it on a Linux system:

cd /tmp
mkdir mtc
cd mtc
rsync -avz -e 'ssh -i ~/.ssh/id_rsa' user@domain.com:/var/www/mautic/ .
npm install
npm ci --prefer-offline --no-audit
npx patch-package
rsync -avz -e 'ssh -i ~/.ssh/id_rsa' . user@domain.com:/var/www/mautic

Tip: Make sure NPM is installed on your local machine for this workaround 😉.

Special Characters in mailer_dsn

Mautic 5 doesn't play well with special characters in the mailer_dsn, particularly in passwords.

The reason is unknown to me.

If you encounter issues, try changing the password. Creating and using passwords without special characters is the workaround for now.

For more, see the relevant GitHub issue and this issue.

mautic:emails:send Removed

Mautic 5 uses the Symfony Messenger. This comes with a transition from mautic:emails:send to mautic:messages:send.

You need to adjust crons and other scripts.

Legacy Froala Builder Disabled

For those still using the legacy email or page builder, the Froala editor is disabled by default in Mautic 5.

Reactivating it is possible but requires manual intervention. Refer to PR #12416 for details.

Transactional Emails Override DNC

A significant update is the handling of transactional emails:

Mautic sends transactional emails now regardless of a contact's 'do not contact' status.

This makes sure that crucial (account-related) communications reach your contacts.

If you (for some reason) marked marketing emails as transactional (e.g., to send them multiple times or in different campaigns) you need to change that.

Also: Transactional emails don't come with an unsubscribe header anymore.

Removed Mautic Core Plugins

In Mautic 5 several core plugins were removed. This includes the

• Citrix (alternative/replacement),
• Pipedrive (alternative/replacement), and
• LinkedIn (gone for good) plugins.

While these are no longer part of the core, third-party solutions are available and linked above.

List of Known Bugs

Here can you see the list of known bugs on GitHub.

That's a wrap. Hope this helps you make an informed decision whether to update right away or wait for a bit.

Happy marketing!

There are three spam protection features that an email sever can and should implement:

• SPF (Sender Policy Framework)
• DKIM (DomainKeys Identified Mail)
• DMARC (Domain-based Message Authentication, Reporting & Conformance)

SPF, DKIM and DMARC each fulfill a specific role for fighting spam:

• SPF checks if the email sending server is allowed to send emails for your domain.
• DKIM verifies the integrity of the email content.
• DMARC uses SPF and DKIM to a) enforce rules and b) report back to you on email authenticity.

Together, they improve email security, combat spam, and enhance the deliverability of legitimate emails, including your marketing campaigns.

This is a two layered process:

• Emails have to originate from servers you authenticate via SPF.
• DKIM ensures that emails are untampered.

How does this work in detail, and how do you set it up?

SPF (Sender Policy Framework)

SPF is a DNS TEXT entry that specifies which mail servers are permitted to send emails on behalf of your domain.

SPF is basically like a whitelist list for your domain. When an email is sent, the receiving email server checks this list to see if the sender's server is on it. If it's on the list, the email is more likely to be genuine.

How it works

1. You publish a SPF whitelist in your DNS settings.
2. Every email that is sent comes from a server this server has an IP address.
3. The receiving server retrieves the SPF record from the sender's DNS and checks it against the IP address the email was sent from.
4. If the IP addresses match, the email is likely to be authentic. If not it is most likely spam.

How to set it up

Setting SPF up is easy: You as domain owner publish an SPF record in the DNS.

1. Add a TXT entry to your DNS
2. Lists the IP addresses or domains that are authorized to send emails on behalf of your domain.

How do I configure the SPF DNS TXT entry? An example might look like this:

v=spf1 ip4:123.456.789.123 include:amazonses.com ~all

Let's break this down.

• v=spf1⁣—the version of SPF used. There is just V1.
• ip:123.456.789.123⁣—emails originating from this IP are legitimate.
• include:amazonses.com⁣—means emails sent from Amazon's SES servers are allowed, too. You will most likely use this setting.
• ~all—defines the policy.
  • Use ~all (soft fail) to start with. Emails that don't match your SPF get delivered but will land in your recipient's spam folder.
  • -all (hard fail) can be used once you're confident in your SPF record. This tells email service providers to reject emails that don't match your SPF.
• You can add up to 10 ip or include lookups. (or a or mx—they basically say: Look up an A or AAA or MX DNS record)

DKIM (DomainKeys Identified Mail)

DKIM adds a digital signature to the headers of your emails. Email service provider like Gmail or Yahoo and email clients like Thunderbird can use this signature to verify it against a public cryptographic key in your domain's DNS records.

DKIM is like a secret handshake for your emails. When you send an email, it gets a unique digital signature. The receiving server can check this signature against a public key in your domain's DNS records to ensure the email hasn't been tampered with.

It's hard (i.e., impossible) for spammers to forge this signature, so it's a powerful tool against email spoofing.

How it works

1. You or your email transport provider (Amazon SES, Mailgun, etc.) create a pair of (most likely SHA/RSA 2048 bit) private and public encryption keys.
2. You publish the public key in a DNS TXT entry.
3. Your mail server signs outgoing emails by adding a DKIM-Signature email header. Your email contents and other headers are used to compute the signature.
4. The recipient's email service provider fetches the DKIM public key via your DNS entry. It uses this key, the email body and specified headers to compute a signature for the email.
5. If this signature matches the DKIM-Signature header then the email is authentic and was not tampered with.

How to set it up

Setting DKIM takes more steps than setting up SPF. But this is usually done through your email service provider.

1. You (or your ESP) creates the encryption keys.
2. You (or your ESP) configures the email server to use the private key to create the DKIM-Signature, and sign all emails.
3. You publish a TXT (or CNAME) record in your DNS. There are two options:
   1. A TXT record that includes the public key right away.
   2. A CNAME record that holds a lookup for the public key. This method is probably used by your email service provider.

How do I configure the DKIM DNS TXT entry? An example might look like this:

k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQD...

Let's break this down.

• k=rsa⁣—the encryption algorithm used.
• p=MIGf...⁣—the published public key.

And the CNAME DKIM DNS entry might look like this:

• Name: lookupdescriptor._domainkey.yourdomain.com
• Data: lookupdescriptor.dkim.emailserviceprovider.com

DMARC (Domain-based Message Authentication, Reporting & Conformance)

DMARC fulfills two jobs:

1. DMARC builds on SPF and DKIM. It uses SPF and DKIM to make a rule book for your emails. It tells email receivers what to do if an email doesn’t pass SPF or DKIM checks (like reject the email or put it in spam).
2. DMARC also asks receivers to report back on emails they get from your domain.

How it works

1. By itself DMARC doesn't do much.
2. Having a DMARC DNS record tells receivers that you use SPF and DKIM. Receivers know now to check for them.
3. DMARC tells the receivers how emails that SPF/DKIM checks are to be treated.
4. DMARC gives the receivers a way to report back to you.

How to set it up

Setting DMARC up is easy: You as domain owner publish an DMARC record in the DNS.

1. Create a TXT record with the name _dmarc.
2. Add the following as data into the record:

v=DMARC1; p=none; rua=mailto:info@mydomain.com

Let's break this down.

• v=DMARC1—the DMARC protocol version.
• p=none—the DMARC policy you want receivers to enforce.
  • none—start with this entry level policy. It tells recipients that no special treatment is required. But this enables you to receive deliverability feedback reports.
• quarantine—receivers should treat DMARC-failed emails as suspicious. This can be done by delivering them into the spam folder or flag them. Use with caution.
• reject—most strict. This tells receivers to outright reject messages that fail DMARC checks. Use with caution.
• rua=mailto:info@mydomain.com—an address to send aggregate reports to.
• By default aggregate reports are sent once a day. ri=time in seconds let you define another reporting interval.

There are more options. Consult the documentation.

Enforcing a quarantine or reject policy, should be done cautiously. You want to avoid legitimate emails being mistakenly blocked or marked as spam.

Therefore, you should do monitoring with a none policy over a period of time and adjust SPF/DKIM if need be.

To recap, SPF checks if the sender's server is allowed to send emails for your domain, DKIM verifies the integrity of an email's content, and DMARC controls policy enforcement rules and adds reporting on email authenticity. Together, they improve email security, combat spam, and enhance the deliverability of your legitimate emails.