Transactional and marketing mail

Every message SMTP Relay sends is either transactional or marketing. The category decides whether the relay adds one-click unsubscribe headers, which let the recipient's mail app show an unsubscribe button. Gmail and Yahoo ask for those headers on bulk mail.

Transactional

Mail a person expects because of something they did: receipts, alerts, password resets, sign-in codes. The relay sends it as your application wrote it.

Marketing

Newsletters, announcements and campaigns. The relay adds unsubscribe headers, and over the send API it sends each recipient a separate copy.

The relay reads the first of these that is set:

1. Over the send API, the category field: transactional or marketing. The API refuses any other value.
2. Over SMTP, the header X-Mail-Category: marketing or X-Mail-Category: transactional. Case does not matter.
3. The relay's default category, which starts as transactional.

Over SMTP, an X-Mail-Category header with any other value, such as newsletter, makes the message transactional, whatever the default.

Each marketing message gets two headers:

List-Unsubscribe: <https://api.coritan.com/api/v1/mail/unsubscribe/{token}>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The link points at our API. Its {token} is signed, and names the relay and the one recipient the copy is for. Because the link belongs to one person, how the relay adds it depends on how the message arrives.

Over the send API

The relay sends each address in to and cc its own copy, addressed to that person alone, with its own link. The headers replace any List-Unsubscribe pair you put in headers. The message also carries X-Mail-Category: marketing.

Over SMTP

The relay adds the headers only to a message with exactly one recipient and no List-Unsubscribe header of its own. A message with several recipients goes out as it is, without unsubscribe headers, because one link cannot name them all. For bulk mail over SMTP, send one message per recipient, or add your own List-Unsubscribe headers.

A transactional message gets no unsubscribe headers from the relay. Over the send API it carries X-Mail-Category: transactional, and any List-Unsubscribe pair you add in headers is kept.

When the recipient selects the unsubscribe button, their mail app posts to the link, as RFC 8058 describes. Someone who opens the link in a browser gets the same result. Either way:

• We add the address to the relay's suppression list with the reason unsubscribe.
• The page says alex@example.com will not receive further marketing email from this sender.
• Selecting the link again changes nothing.

The unsubscribe covers the whole relay, every sending domain included. A link does not expire.

The default applies to every message that does not set a category. On the relay's Overview tab, in the Deliverability card, choose Default message category. A toast confirms the change, such as Default category is now marketing. It applies to messages sent from then on.

Set it to marketing only when most of what the relay sends is bulk mail, and mark receipts and other transactional messages as transactional one by one. A Mail Hosting service has its own default, on its Settings tab: see Mail Hosting settings.

Set the relay's default category:

curl -X PATCH https://api.coritan.com/api/v1/client/smtp-relay/4812/category \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"default_category": "marketing"}'

default_category is transactional or marketing; any other value answers 422. The answer is the new default:

{"default_category": "marketing"}

The unsubscribe link is GET or POST /mail/unsubscribe/{token}. It needs no key or token of yours, ignores the request body, and answers 200 with the plain-text sentence above. A link that has been changed or cut short answers 404 Unknown unsubscribe link. Your application does not call it: receiving mail apps and recipients do.