Emails

Marketing and transactional email

Every email is either marketing or transactional. Email is marketing unless you label it transactional, so unlabelled mail is sent as it always was. The category decides two things:

• Who it reaches. When a recipient unsubscribes, they stop getting marketing email from you, but email you label transactional still reaches them. Hard bounces and complaints block both, and so do manual suppressions by default; a manual suppression you add with "scope": "marketing" blocks marketing email only. See Suppressions.
• The unsubscribe header. Marketing email carries the one-click List-Unsubscribe and List-Unsubscribe-Post headers that Gmail and Yahoo ask bulk senders for. Transactional email has neither.

How the category is chosen:

1. An email is transactional only when you label it so: "category": "transactional" in an API, batch or template send, or the header X-SMTPfast-Category: transactional over SMTP. If you pass both, the field wins.
2. An email whose html or text contains an unsubscribe placeholder ({{unsubscribe_url}} or {{{RESEND_UNSUBSCRIBE_URL}}}) is always marketing, even when labelled transactional, so the link in it can stop it. For a template send, the rendered body is checked.
3. Everything else is marketing: unlabelled email, broadcasts, broadcast test sends and signup form emails.

Label password resets, receipts and other transactional mail with "category": "transactional" (or the X-SMTPfast-Category header) so a marketing opt-out does not block them. Unlabelled mail is treated as marketing, as before. The template's own category label does not affect this.

{
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Reset your password",
  "html": "<p>Use this link to choose a new password.</p>",
  "category": "transactional"
}

The category is stored on the email and returned as category by GET /v1/emails and GET /v1/emails/:id.

Tracking per email

Open and click tracking follow your account settings (Settings, Email Tracking), which apply to every email sent through the API and SMTP. Broadcasts have their own tracking settings. Click tracking sends each link through a redirect and records the full URL, which you can read back with GET /v1/emails/clicked-links. For a link that carries a secret, such as a password reset or sign-in token, turn tracking off so the token stays out of the redirect and the log. There are four ways, from the narrowest:

1. One link. Add data-smtpfast-track="off" to the <a> tag. That link goes out exactly as written, the others in the email are still tracked, and the attribute is removed before sending.
2. One email, over the API. "track_clicks": false and "track_opens": false on POST /v1/emails or on a batch item. true turns tracking on for that email even when your account has it off.
3. One email, over SMTP. The headers X-SMTPfast-Track-Clicks: false and X-SMTPfast-Track-Opens: false (or true). They are removed before sending. With the API you can also pass them in headers; a field wins over its header.
4. All transactional email. Turn off "Track transactional email" in Settings, Email Tracking. Email labelled transactional then goes out untracked unless the email itself asks for tracking.

<p>Hi Ada, use this button to choose a new password:</p>
<a data-smtpfast-track="off" href="https://yourapp.com/reset?token=8f3a...">Reset password</a>
<p>Questions? <a href="https://yourapp.com/help">Visit the help center</a></p>

Click tracking rewrites links written as <a href="https://..."> in the HTML part, whatever the link text says. A URL written as plain text, and the plain-text part of an email, are never rewritten; a mail app may still turn such a URL into a link. Any value other than true or false in a field or header is refused with a 400; a null field is the same as leaving it out. The fields apply to POST /v1/emails and batch items. Replies and forwards sent from an inbox follow your account settings, and the per-link attribute works in them too.