# Send emails with Mastodon

> Point Mastodon's SMTP settings at PostShiba.

## What you'll build

A self-hosted Mastodon server that sends its sign-up confirmations, password resets, and notification emails through PostShiba over SMTP.

## Before you start

- A **Transactional** cluster. Server notification mail belongs on a transactional cluster, 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). `SMTP_FROM_ADDRESS` must be on it.
- A cluster that is ready to send (`sending_ready` is `true`).
- Shell access to the Mastodon server, so you can edit `.env.production`.

## Install

Nothing to install. Mastodon has SMTP support built in.

## Send your first email

1. Set these variables in `.env.production`. On a standard install it is `/home/mastodon/live/.env.production`. `SMTP_ENABLE_STARTTLS=auto` upgrades the connection with STARTTLS on port 587, and `SMTP_OPENSSL_VERIFY_MODE=peer` keeps certificate checks on. Leave `SMTP_TLS` and `SMTP_SSL` unset, because they are for port 465.

```bash .env.production
SMTP_SERVER=smtp.postshiba.com
SMTP_PORT=587
SMTP_LOGIN=smtp_9
SMTP_PASSWORD=YOUR_PASSWORD
SMTP_FROM_ADDRESS=hello@mail.example.com
SMTP_AUTH_METHOD=plain
SMTP_ENABLE_STARTTLS=auto
SMTP_OPENSSL_VERIFY_MODE=peer
```

2. Restart Mastodon so it reads the new settings. Sidekiq sends the mail, so restart it as well as the web process.

```sh restart.sh
sudo systemctl restart mastodon-web mastodon-sidekiq
```

With Docker Compose, run `docker compose up -d` from the directory with `docker-compose.yml`. It recreates the `web` and `sidekiq` containers with the new `.env.production`. `docker compose restart` does not reload it.

3. Mastodon has no test email button. Sign out, choose **Forgot your password?** on the sign-in page, and enter your own address. The reset email goes through PostShiba and shows under Events in the dashboard.

Every SMTP setting is on [Send emails with SMTP](/docs/send-with-smtp).

## Troubleshooting

Mastodon 4.4 and later can send server announcements and terms of service updates through a second set of `BULK_SMTP_*` variables. They reach every user at once. If you leave them unset, those emails use the settings above and count against the same cluster's caps. If they would go over, set `BULK_SMTP_*` to a credential from a second cluster sized for them. 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. See [What happens at your cap](/docs/dashboard/clusters/what-happens-at-your-cap).

| What you see in the Sidekiq log | What to do |
| --- | --- |
| Authentication fails | Check `SMTP_LOGIN` and `SMTP_PASSWORD`, and set `SMTP_AUTH_METHOD=plain`. PostShiba accepts `AUTH PLAIN` only. Restart Sidekiq after each change. |
| `550 unverified domain` or `550 from header not aligned with verified domain` | Set `SMTP_FROM_ADDRESS` to an address on your verified domain. If you set `SMTP_RETURN_PATH`, it must be on that domain too. |
| `550 domain_suspended` | The From domain is paused. Resume it from [Managing domains](/docs/dashboard/domains/manage-domains). |
| `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` or `550 firewall: <rule>` | The recipient is on the [suppression list](/docs/dashboard/emails/email-suppressions) or failed an [email firewall](/docs/dashboard/emails/email-firewall) check. PostShiba suppresses addresses that hard bounce or report spam. |
| `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. Retry later, or resize the cluster. |

## Next steps

- [What happens at your cap](/docs/dashboard/clusters/what-happens-at-your-cap)
- [How to manage suppressions](/docs/dashboard/emails/email-suppressions)
- [Send emails with SMTP](/docs/send-with-smtp) for every setting and reply.
- [Managing webhooks](/docs/webhooks/introduction) to receive delivery events.