# Send emails with Mautic

> Set Mautic's mailer DSN to PostShiba SMTP.

## What you'll build

A Mautic install that sends its segment, campaign, and test emails through PostShiba over SMTP. Mautic keeps your contacts, segments, and unsubscribe links. PostShiba delivers the mail and suppresses addresses that hard bounce or report spam.

This page covers Mautic 5 and later, which configure mail with a Symfony Mailer DSN. Mautic 4 used different settings.

## Before you start

- A **Marketing** cluster. Newsletters belong on a bulk cluster, not a transactional one, and the type is locked after create. See [Clusters](/docs/dashboard/clusters/introduction).
- An SMTP username and password. Open your cluster in the dashboard, go to its SMTP credentials, and choose **Create SMTP credential**. Copy the password right away, because it is shown once. You can also use the [SMTP credentials API](/docs/api-reference/smtp-credentials).
- A verified sending domain. See [Add and verify a domain](/docs/add-a-domain). Mautic's from address, and the from address of every email you build, must be on it.
- A cluster that is ready to send (`sending_ready` is `true`).
- Mautic 5 or later. Pacing with `max_per_second` needs Mautic 6 or later.

## Install

Nothing to install. Mautic has SMTP support built in.

## Pick a plan for your largest list

PostShiba caps each cluster per hour and per rolling 24 hours. The 24-hour cap must cover your largest segment plus anything else the cluster sends that day.

| Plan | Emails per hour | Emails per 24 hours | Mautic `max_per_second` option |
| --- | --- | --- | --- |
| Nano | 100 | 600 | Test sends only |
| Micro | 4,000 | 24,000 | 1 |
| Small | 40,000 | 240,000 | 11 |
| Medium | 100,000 | 600,000 | 27 |
| Large | 200,000 | 1,200,000 | 55 |

When a cap is full, SMTP answers `451 4.7.0 hourly send limit reached` or `451 4.7.0 daily send limit reached` and does not keep the message. Select **Resize** on the cluster page before a send that would go over. See [What happens at your cap](/docs/dashboard/clusters/what-happens-at-your-cap).

## Send your first email

1. In Mautic, open **Settings** with the cog at the top right, then **Configuration** → **Email Settings**.
2. Under **Mail Send Settings**, set **E-mail address to send mail from** to an address on your verified domain.
3. Under **Email DSN**, enter these values. The user starts with `smtp_`. Add the option as a row in **Options**.

```text mautic-dsn.txt
E-mail address to send mail from:  hello@mail.example.com
Scheme:                            smtp
Host:                              smtp.postshiba.com
Port:                              587
User:                              smtp_9
Password:                          YOUR_PASSWORD
Options:                           ping_threshold = 20
```

4. On Mautic 6 or later, add a second row in **Options** with `max_per_second` set to the value for your plan in the table above. The hourly cap divided by 3,600 keeps a long send under the hourly cap.
5. Leave **Custom return path (bounce) address** empty. Mautic uses it as the envelope sender, and PostShiba refuses an envelope sender that is not on a verified domain.
6. Choose **Save**, then **Send test email**. Mautic sends it to the address on your Mautic user. The message shows under Events in the PostShiba dashboard.

The `smtp` scheme upgrades the connection with STARTTLS on port 587 and picks `AUTH PLAIN`, the only method PostShiba offers. `ping_threshold` makes Mautic check a connection that has been quiet for 20 seconds and reconnect if PostShiba closed it. Every SMTP setting is on [Send emails with SMTP](/docs/send-with-smtp).

If you write the DSN straight into `config/local.php` instead of using the form, URL-encode the password yourself. The form encodes it for you.

```php local.php
'mailer_dsn' => 'smtp://smtp_9:YOUR_PASSWORD@smtp.postshiba.com:587?ping_threshold=20',
```

## Send segment emails from cron

Segment emails sent from the browser need the window open until the send finishes. Send them from cron instead. Mautic sends only published emails this way. `--limit` caps how many contacts each run picks up, which also spreads a large segment across runs.

```sh broadcasts-cron.sh
php /path/to/mautic/bin/console mautic:broadcasts:send --channel=email --limit=1000
```

If you turned on Mautic's email queue, also run `messenger:consume email` from cron with `--time-limit`, `--limit`, or `--memory-limit`, so each run exits.

## Bounces, complaints, and unsubscribes

Bounce emails go to PostShiba, not to Mautic. Mautic's monitored inbox never sees them, so leave its **Bounces** folder unset. When it is set, Mautic rewrites the envelope sender to that mailbox. PostShiba stops the mail instead.

| Event | What happens |
| --- | --- |
| Hard bounce | PostShiba suppresses the address. Later sends to it are refused with `550 suppressed`. |
| Spam report | PostShiba suppresses the address the same way. |
| Soft bounce | PostShiba retries delivery. Nothing is suppressed. |
| Unsubscribe | When an email contains `{unsubscribe_url}`, or the monitored inbox has an **Unsubscribe Requests** folder, Mautic adds its own `List-Unsubscribe` and `List-Unsubscribe-Post` headers. PostShiba leaves them alone, and Mautic marks the contact Do Not Contact. Otherwise, or with **Disable unsubscribe link in header** turned on, PostShiba adds its own one-click header. |

Suppressed addresses still look reachable in Mautic. PostShiba refuses them, so they never reach a mailbox, but they stay in your segments. Copy them into Mautic as Do Not Contact now and then to keep your segments clean.

## Copy suppressions into Mautic

1. Export every suppressed address to `postshiba-suppressions.csv`. Follow [How do I export my suppression list?](/docs/knowledge-base/how-do-i-export-my-suppression-list). It takes a read-only Support key and one script.
2. Mautic's importer needs a header row, and the export has none. Add one, plus a column set to `1` for every address.

```sh add-dnc-column.sh
(echo "email,dnc"; sed 's/$/,1/' postshiba-suppressions.csv) > mautic-dnc.csv
```

3. In Mautic, open **Contacts** and choose **Import**. Upload `mautic-dnc.csv` and choose **Upload and match fields**.
4. Map `email` to the **Email** contact field and `dnc` to **Do not contact** under the special fields, then start the import. Mautic marks each contact Do Not Contact for email. Addresses that are not in Mautic yet are added as new contacts marked the same way.

Run it again after each large send. Importing an address that is already Do Not Contact does no harm.

## Troubleshooting

| What you see | What to do |
| --- | --- |
| Authentication fails | Check **User** and **Password**. Use scheme `smtp` on port `587`. Port 465 and the `smtps` scheme are not offered. PostShiba accepts `AUTH PLAIN` only. |
| **Send test email** is missing | Mautic shows it only for a saved DSN. Choose **Save** first. |
| `550 unverified domain` | The envelope sender is not on a verified domain. Clear **Custom return path (bounce) address** and the monitored inbox **Bounces** folder. |
| `550 from header not aligned with verified domain` | Set **E-mail address to send mail from**, and the from address on the email itself, to an address on your verified domain. |
| `550 kyc_required` | Your team is pending production approval. Until then, send only to team members, live inbox addresses, and inbox forward-to addresses. See [Does PostShiba require production approval?](/docs/knowledge-base/does-capsule-require-production-approval). |
| `550 suppressed` | The contact hard bounced or reported spam. Copy suppressions into Mautic as shown above. |
| `451 4.7.0 hourly send limit reached` or `451 4.7.0 daily send limit reached` | The cluster is at its cap and did not keep the message. Lower `max_per_second` or the cron `--limit`, or resize the cluster before the next send. |
| `451 4.4.5 too many sessions, slow down` | Too many Mautic processes opened SMTP connections on one username in 10 seconds. Run fewer `mautic:broadcasts:send` or `messenger:consume` processes at once. |
| `421 4.3.2 ... idle too long` | A connection sat idle for 30 seconds. Add `ping_threshold` with a value under `30` in **Options**. See [421 4.3.2 idle too long](/docs/knowledge-base/smtp-421-idle-too-long). |

## Next steps

- [What happens at your cap](/docs/dashboard/clusters/what-happens-at-your-cap)
- [How to manage suppressions](/docs/dashboard/emails/email-suppressions)
- [How do recipients unsubscribe?](/docs/knowledge-base/how-do-recipients-unsubscribe)
- [Send emails with SMTP](/docs/send-with-smtp) for every setting and reply.