# Mautic email with Groundmail

Send Mautic's email through Groundmail with the official plugin for Mautic 6 and 7. User and system email, form notifications and transactional email go out on the transactional stream, and segment and marketing campaign email on its own stream, so a newsletter can never slow down a password reset. Hard bounces, spam complaints and unsubscribes come back into Mautic as Do Not Contact.

**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](https://groundmail.dev/legal/aup/) doesn't allow it.

---

## Prerequisites

- A Groundmail account with a [verified sending domain](https://docs.groundmail.dev/domains).
- 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](#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](#streams).

---

## Install the plugin

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

```bash
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:

| Mautic field | Value |
|--------------|-------|
| Scheme | `groundmail+api` |
| Host | `default` |
| Port | Leave empty |
| User | Leave empty |
| Password | Your API key (`gm_…`) |

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:

```php
'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](https://docs.groundmail.dev/testing#simulator-addresses).

---

## Which stream each email uses {#streams}

Groundmail sends [transactional, product and newsletter email from separate IPs](https://docs.groundmail.dev/deliverability#transactional-and-product-streams). The plugin picks the `category` for each email from how Mautic sends it:

| Mautic email | Groundmail category |
|--------------|---------------------|
| User and system email (password resets, notifications), form notifications, emails sent to a contact through Mautic's API, campaign emails set to **Transactional** | `transactional` |
| Segment emails, and campaign emails set to **Marketing** | `newsletter` (default), or `product` |

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`:

| Option | Value |
|--------|-------|
| `marketing_category` | `newsletter` (default) or `product`: the stream for segment and marketing campaign email |
| `category` | `transactional`, `product` or `newsletter`: send every email on this one stream |
| `webhook_secret` | The signing secret of your Groundmail webhook. See [Bounces, complaints and unsubscribes](#webhooks) |

```php
'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](https://docs.groundmail.dev/emails) with `X-Groundmail-Tag: name=value`. Mautic lets you add custom headers to an email under its **Advanced** tab.

---

## Bounces, complaints and unsubscribes {#webhooks}

Groundmail adds addresses that hard-bounce or complain to your [suppression list](https://docs.groundmail.dev/suppressions) 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.

| Groundmail event | In Mautic |
|------------------|-----------|
| `email.bounced` with `bounce_type: hard` | Do Not Contact: bounced |
| `email.failed` with `bounce_type: hard` | Do Not Contact: bounced |
| `email.complained` | Do Not Contact: unsubscribed |
| `contact.unsubscribed` | Do Not Contact: unsubscribed |

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`](https://docs.groundmail.dev/webhooks#signature-verification) 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 {#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](https://docs.groundmail.dev/smtp) instead, with an SMTP credential (`gmsmtp_…`) from **SMTP** in the dashboard:

| Mautic field | Value |
|--------------|-------|
| Scheme | `smtp` |
| Host | `smtp.groundmail.dev` |
| Port | `587` |
| User | `groundmail` |
| Password | Your SMTP credential (`gmsmtp_…`) |

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](https://docs.groundmail.dev/domains). 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](#streams).

**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](https://docs.groundmail.dev/suppressions).

**Sends are deferred.** New accounts have a daily ramp-up limit, counted separately for product and newsletter email. See [Sending limits](https://docs.groundmail.dev/sending-limits).

---

## Related

- [Symfony Mailer transport](https://docs.groundmail.dev/frameworks/symfony)
- [Webhooks](https://docs.groundmail.dev/webhooks)
- [Testing](https://docs.groundmail.dev/testing)
- [Suppressions](https://docs.groundmail.dev/suppressions)
- [Errors](https://docs.groundmail.dev/errors)
