Mautic email with Groundmail

Your lists must be opt-in. Groundmail sends email to people who asked for it: contacts who signed up, bought from you or opted in to your newsletter. Don't send cold email or email to purchased, rented or scraped lists; our acceptable use policy doesn't allow it.

Prerequisites

• A Groundmail account with a verified sending domain.
• An API key (gm_…): in the dashboard, open API keys and create one. A send-only key is enough.
• Mautic 6 or 7, installed with Composer, and shell access to run Composer. On Mautic 5, see Mautic 5.
• To send segment email on the newsletter stream: an account approved for newsletters. Email support@groundmail.dev to ask. See Which stream each email uses.

Install the plugin

In your Mautic project, add the plugin's repository and install it with Composer:

composer config repositories.groundmail-mautic vcs https://github.com/Groundmail/groundmail-mautic
composer require groundmail/mautic-plugin
php bin/console cache:clear
php bin/console mautic:plugins:reload

Composer installs it into plugins/GroundmailBundle. You can also go to Settings, then Plugins, and click Install/Upgrade Plugins instead of running mautic:plugins:reload.

Connect Mautic

1. In Mautic, go to Settings, then Configuration, and open Email Settings.
2. Set E-mail address to send mail from to an address on your verified domain, for example news@yourdomain.com.
3. Fill in the email DSN fields:

4. Click Save, then Send test email.

Mautic masks the password once it is saved. To keep the key out of the database, set it in config/local.php instead:

'mailer_dsn' => 'groundmail+api://:gm_your_key@default',

To test without emailing a real inbox, change your Mautic user's email address to delivered@simulator.groundmail.dev before you click Send test email. The email shows up under Emails in the Groundmail dashboard with the status delivered and "test": true. See Testing.

Which stream each email uses

Groundmail sends transactional, product and newsletter email from separate IPs. The plugin picks the category for each email from how Mautic sends it:

Mautic adds an unsubscribe header only to marketing email, and that is what the plugin goes by. Marketing email keeps Mautic's own unsubscribe link, so put {unsubscribe_url} in every segment email.

Until your account is approved for newsletters, Groundmail refuses newsletter sends with a 403 (newsletter_not_enabled) and nothing is sent. Mautic counts them as failed and tries them again on its next run; the plugin stops calling the API for newsletters for the rest of that run, and transactional email keeps sending. If your marketing email is about your product to its own users, such as onboarding tips and feature announcements, send it as product instead: product email has its own opt-out, separate from transactional email.

DSN options

Add these under Options in the DSN (a key and a value per row), or as query parameters in mailer_dsn:

'mailer_dsn' => 'groundmail+api://:gm_your_key@default?marketing_category=product',

One email can also set its own stream with an X-Groundmail-Category header (transactional, product or newsletter), and add tags with X-Groundmail-Tag: name=value. Mautic lets you add custom headers to an email under its Advanced tab.

Bounces, complaints and unsubscribes

Groundmail adds addresses that hard-bounce or complain to your suppression list and stops sending to them. To mark those contacts Do Not Contact in Mautic as well:

1. In the Groundmail dashboard, open Webhooks and create an endpoint:
   • URL: https://your-mautic.example.com/mailer/callback
   • Events: email.bounced, email.failed, email.complained and contact.unsubscribed
2. Copy the signing secret. It is shown once.
3. In Mautic's email DSN, add the option webhook_secret with the secret as its value, and save.

A block bounce means the receiving server refused the sender, not that the address is bad, so the contact is left alone. Every send carries the contact's Mautic hash id as the tag mautic_hash, which ties each event to the email it is about. Requests without a valid Groundmail-Signature are refused with a 401, and with no webhook_secret set the endpoint answers 403.

To try it, send a segment email to a contact whose address is bounce@simulator.groundmail.dev. The webhook arrives a few seconds later and the contact is marked bounced.

Mautic 5

The plugin needs Mautic 6 or later: Mautic 5 uses an older version of Symfony Mailer. On Mautic 5, connect over the SMTP relay instead, with an SMTP credential (gmsmtp_…) from SMTP in the dashboard:

Everything sent over the relay goes out as transactional email, so on Mautic 5 use it for system and transactional email only, and send newsletters after you upgrade.

Troubleshooting

"That is not a Groundmail API key". The Password field needs an API key (gm_…). SMTP credentials (gmsmtp_…) only work with the smtp scheme.

The test email is refused because of the From address. The from address must be on a verified domain. Until you verify one you can only send from the sandbox sender, to your own account email.

Segment emails fail with newsletter_not_enabled. Your account isn't approved for newsletters yet. Email support@groundmail.dev, or set marketing_category to product if the email is about your product. See Which stream each email uses.

A contact never receives email. The address may be suppressed after a hard bounce or complaint, or the contact may have opted out of that category. Sends to them return 422. See Suppressions.

Sends are deferred. New accounts have a daily ramp-up limit, counted separately for product and newsletter email. See Sending limits.

Related

• Symfony Mailer transport
• Webhooks
• Testing
• Suppressions
• Errors