Skip to content

Categories in depth

The categories reference lists the six recognized values. This page explains how categories affect sending.

What a category controls

Section titled “What a category controls”

When you set category on the HTTP API or the X-Atmos-Category SMTP header, the relay routes the message through three decisions:

  1. Whether to add List-Unsubscribe and List-Unsubscribe-Post headers (RFC 8058 one-click).
  2. Whether a recipient can bypass an unsubscribe-only entry in the DID’s suppression list.
  3. Which category value to include in the Feedback-ID header.

The relay removes X-Atmos-Category before it signs the message. It adds the category to Feedback-ID, which receiving systems can read.

Each category, in detail

Section titled “Each category, in detail”
Section titled “login-link”

Use for: magic-link sign-in. Recipient just typed their address into a sign-in form and is waiting.

What the relay does:

  • No List-Unsubscribe header added.
  • Unsubscribe-only suppression entries are bypassed. Other suppression reasons still block the recipient.
  • The category in Feedback-ID is transactional.

password-reset

Section titled “password-reset”

Use for: password reset links. Recipient just clicked “forgot password” and is watching their inbox.

Like login-link, this category adds no List-Unsubscribe header, bypasses unsubscribe-only suppression entries, and uses transactional as its Feedback-ID category. The distinct value can help you identify password-reset traffic in your own systems.

mfa-otp

Section titled “mfa-otp”

Use for: multi-factor codes. TOTP confirmations, push-auth secondary delivery, SMS-fallback codes routed to email.

Like the other user-initiated transactional categories, this adds no List-Unsubscribe header, bypasses unsubscribe-only suppression entries, and uses transactional as its Feedback-ID category. Set an expiry time for each code in your own system.

verification

Section titled “verification”

Use for: email address verification. Signup confirmation, address-change confirmation, “is this your email” challenges.

Like the other user-initiated transactional categories, this adds no List-Unsubscribe header, bypasses unsubscribe-only suppression entries, and uses transactional as its Feedback-ID category.

bulk

Section titled “bulk”

Use for: marketing email, newsletters, product updates, announcements, anything sent to a list the recipient signed up for (or otherwise didn’t request right this minute).

What the relay does:

  • Adds List-Unsubscribe: <https://...> and List-Unsubscribe-Post: List-Unsubscribe=One-Click per RFC 8058.
  • Per-recipient unsubscribe token: one click unsubs that recipient only, not your whole list.
  • Enforces the suppression list at submission. Comail removes suppressed recipients before the message enters the send queue. The message can still send to other recipients.
  • Feedback-ID stamped as bulk.

Sender-provided List-Unsubscribe headers

Section titled “Sender-provided List-Unsubscribe headers”

If a bulk or broadcast message already has either unsubscribe header, Comail adds neither of its own.

You must provide a valid RFC 8058 pair: List-Unsubscribe must contain an HTTPS URI (you can also include a mailto: URI), and List-Unsubscribe-Post must be exactly List-Unsubscribe=One-Click.

Header matching is case-insensitive per RFC 5322. Suppression-list enforcement stays active when sender headers take precedence.

Self-managed senders with their own unsubscribe infrastructure should include both headers in the message and tag as bulk or broadcast. Senders who want comail’s per-recipient token approach should omit both headers entirely.

broadcast

Section titled “broadcast”

Use for: list announcements. You can distinguish broadcast from bulk in your own sending records.

At the policy layer, broadcast uses the same unsubscribe headers and suppression rules as bulk. Its Feedback-ID category is broadcast.

Untagged (omitting the field)

Section titled “Untagged (omitting the field)”

If you omit category or use an unrecognized value, the relay treats the message as untagged:

  • No List-Unsubscribe headers added.
  • The suppression list is enforced. Unsubscribe-only entries block untagged mail.
  • The category in Feedback-ID is transactional.

The AUP treats untagged mail as bulk. Set a category for each message.

A decision tree

Section titled “A decision tree”

Walk this when you’re integrating and you don’t know which value to pick:

Was this message triggered by the recipient's own action?
├─ Yes:
│   ├─ Is it a sign-in link?        → login-link
│   ├─ Is it a password reset?      → password-reset
│   ├─ Is it an MFA / OTP code?     → mfa-otp
│   └─ Is it an address verification?→ verification
│
└─ No, this is a list send:
    ├─ Is it a one-off announcement?→ bulk or broadcast (your call)
    └─ Is it part of a recurring cadence? → broadcast

A few edge cases:

A welcome email is verification only if it asks the recipient to confirm their email address. Use bulk for a welcome message sent to a list.

A receipt sent after a purchase has no dedicated category. Select a recognized category that fits your sending policy. Untagged messages have no unsubscribe headers, but remain subject to unsubscribe suppression.

A subscription renewal notice has no dedicated category. Decide which suppression and unsubscribe rules the message needs; do not use one of the four user-initiated categories unless it matches the recipient’s action.

A “your password was changed” notice is not an email-address verification message. Choose a category that fits your unsubscribe policy.

What miscategorising costs you

Section titled “What miscategorising costs you”

The relay does not infer intent from the message body. Choose a category that matches the message. An incorrect choice can make Comail apply the wrong suppression and unsubscribe rules.

Bulk mail tagged as transactional

Section titled “Bulk mail tagged as transactional”

Do not tag a newsletter as verification to bypass an unsubscribe-only suppression entry or omit unsubscribe headers. The AUP prohibits category misuse.

Transactional mail tagged as bulk

Section titled “Transactional mail tagged as bulk”

If you tag a password reset as bulk, the relay adds List-Unsubscribe. A recipient who later uses that link will add their address to your suppression list.

The recipient will be blocked from future bulk messages. A password-reset message can bypass that unsubscribe-only entry. Other suppression reasons still block it.

Untagged when you mean bulk

Section titled “Untagged when you mean bulk”

The recipient unsubscribed from your newsletter last week. This week’s untagged message has no List-Unsubscribe header, but the unsubscribe entry still blocks it. Use bulk or broadcast for list mail so Comail adds unsubscribe headers.

What the relay strips before signing

Section titled “What the relay strips before signing”

The relay reads and removes X-Atmos-Category before DKIM signing. It adds a Feedback-ID header with a category value and sender details. Bulk and broadcast retain distinct values; the other categories use transactional. Receiving providers decide how to use this header.

Section titled “Related”

Back to docs