MailerSend

MailerSend takes two credentials: an API token for its API, and one of its SMTP users for the relay. Its webhooks report what happened after the handoff — deliveries, hard and soft bounces, delays, and complaints — which powers the delivered state, webhooks like mail.delivered and mail.bounced, and automatic suppressions.

Before you start

• A MailerSend account with your sender domain added and verified — see Deliverability for what each record proves.
• For the API transport: an API token. Create it with an expiration date: a token created without one expires after 24 hours, and every send fails after that. Sending access is enough.
• For the SMTP transport: an SMTP user (Domains → your domain → SMTP) — its own username and password, not the API token.

Add the account in Mailway

1. Add the provider.

   In the console, open Providers → New provider, pick MailerSend and paste the API token and the SMTP user’s login. Mailway relays SMTP mail over smtp.mailersend.net on port 587 (STARTTLS, required), and sends API and console mail over MailerSend’s API. Secrets are encrypted at rest.

   Tip

   Keep the SMTP user’s login and leave Send via on Auto. Without it (or set to API only), relayed mail can’t be handed over as-is, because MailerSend’s API is structured-only. It then skips the account unless a project admin enables re-encoding on the attachment.

2. Attach it to a project.

   Open the project, attach the provider, and position it in the failover order.

Delivery events

Without delivery events, MailerSend only reports that it accepted the mail. With them, MailerSend tells Mailway what happened afterwards.

1. Open delivery tracking. In the console, open the provider → Delivery tracking (beside Configure). Mailway creates the provider’s webhook URL and shows it ready to copy. The URL contains a per-provider secret — treat it like a password.

2. Add the webhook in MailerSend. Domains → your domain → Manage → Webhooks → Add webhook. Name it Mailway, paste the URL as the Endpoint URL, and tick activity.delivered, activity.hard_bounced, activity.soft_bounced, activity.spam_complaint, and — on plans that offer them — activity.deferred and activity.suppressed. activity.sent means dispatched, not delivered; it and the opens, clicks, unsubscribes, and surveys can stay off.

3. Store the signing secret (required). Save the webhook, then copy its signing secret into the dialog’s Paste the signing secret step. MailerSend checks the URL while you save; Mailway answers that check, and refuses real events until the secret is stored.

What each event does in Mailway

MailerSend event	Mailway outcome
activity.delivered	The mail turns delivered (confirmed by the provider’s event).
activity.hard_bounced	The mail turns bounced; the address is auto-suppressed for the project.
activity.soft_bounced, activity.deferred	Recorded as soft_bounced (temporary; a later delivery outranks it).
activity.spam_complaint	The mail turns complained; the address is auto-suppressed.
activity.suppressed	Recorded as dropped: MailerSend didn’t send it. The mail keeps its state.

Note

Events correlate through the message id MailerSend returns — at the API handoff, and in the 250 Message queued as <id> reply of its SMTP relay. An event only ever affects mail your own team sent through that provider.

Check the connection

• Connection check. The provider page’s connection check logs in over SMTP and makes one free API call, without sending anything.
• Delivery events. Send a test email from the Delivery tracking dialog’s last step: it waits for MailerSend’s first event and ticks when it arrives.

What MailerSend changes

In our test account MailerSend appended “Delivered by MailerSend” to both the text and the HTML part, tracked opens and clicks by default, and, over SMTP, removed every custom header — List-Unsubscribe included. See What providers change.

Limits

• Custom headers over the API (List-Unsubscribe, X- headers and the like, set in the HTTP API headers field) need a MailerSend Professional plan or higher. On a lower plan MailerSend refuses them, and Mailway sends the mail without them. It’s still delivered, but without your headers.
• Otherwise your MailerSend plan’s own sending limits apply. Mailway adds none for MailerSend beyond your Mailway plan’s quotas.