MailcrateLanes
Every email goes out on the marketing or the transactional lane. The lane decides who can receive it, and the default is not always the one you want.
Every email Mailcrate sends travels on one of two lanes. The lane answers one question: did the recipient ask for this email?
- Transactional: mail the recipient needs because of something they did. Password resets, receipts, sign-in links, shipping updates.
- Marketing: mail you chose to send them. Newsletters, product announcements, promotions.
What the lane changes
| Marketing | Transactional | |
|---|---|---|
| Recipient unsubscribed from your marketing | Not sent (suppressed) | Sent |
| Recipient opted out of the send's subscription group | Not sent | Not sent |
| Address hard-bounced, complained, or was added to the suppression list | Not sent | Not sent |
| Workspace frequency cap (at most n marketing emails per contact per window) | Counts and applies | Ignored |
| Daily and monthly sending quota | Counts | Counts |
The rows that matter most are the first and the third. A transactional email reaches someone who unsubscribed from your newsletter, which is what you want for a password reset. Nothing reaches an address that bounced or complained, on either lane, because those emails cannot or must not be delivered.
Which lane a send uses
You choose it with the lane field on POST /public/sending/mail. When you leave it out, the default depends on what you are sending:
| You send | Default lane |
|---|---|
A transactional message (transactionalMessageId) | transactional |
A template (templateId) | marketing |
Inline HTML (html) | marketing |
A template send defaults to marketing
Sending a template by templateId uses the marketing lane unless you say otherwise. A password reset sent that way is silently suppressed for every customer who ever unsubscribed from your newsletter. Set "lane": "transactional" on every send that the recipient asked for:
{
"contactEmail": "ada@example.com",
"templateId": "password-reset",
"lane": "transactional",
"data": { "resetUrl": "https://app.example.com/reset/8f2c" }
}The lane a send actually used is in the response ("lane": "transactional") and on the delivery in the app, so you can check it.
When a send is blocked
A send that the lane rules block is not an error. The API still answers 200 and returns a delivery, with status set to suppressed and a suppressionReason that says why:
{
"id": "0b8e7c52-1f3a-4d2b-9c61-5a7e2f9d4b30",
"status": "suppressed",
"lane": "marketing",
"suppressionReason": "unsubscribed"
}suppressionReason | Why | Lanes |
|---|---|---|
unsubscribed | The contact unsubscribed from your marketing | Marketing only |
frequency-cap | The contact already got the workspace's maximum number of marketing emails in the cap window | Marketing only |
group-opt-out | The contact opted out of the send's subscriptionGroupId | Both |
hard-bounce, soft-bounce, complaint, manual, import | The address is on the suppression list | Both |
Check status rather than the HTTP status code when it matters whether the email went out. The suppressed delivery stays in the delivery log, so you can see later why someone did not get it.
Choosing well
- Use transactional only for mail the recipient triggered. Sending marketing content on the transactional lane goes around your recipients' unsubscribe choices. That is a legal problem in most countries, and mailbox providers notice it in your complaint rate.
- Keep an unsubscribe link in marketing templates. New templates start with a footer that has one (
{{ unsubscribe_url }}) and your postal address ({{ sender_address }}). You can take that footer out of a purely transactional template. - Use a subscription group (
subscriptionGroupId) for optional mail such as product tips, so people can opt out of that kind of email without unsubscribing from everything.