Send email

Suppressions

Use suppressions to stop delivery to email addresses that must not receive more mail. A suppression can apply to a team, project, or route.

Lettermint checks every To, Cc, and Bcc recipient before delivery. This check applies to immediate and scheduled messages. If one recipient matches a suppression, Lettermint skips that recipient and continues with the other recipients.

Suppression records do not expire. They stay active until you remove them. One address can match more than one record, such as a team hard bounce and a route unsubscribe. Removing one record does not remove the others.

Reasons

Reason	API value	How it starts
Hard bounce	`hard_bounce`	Lettermint receives a permanent delivery failure for the address
Spam complaint	`spam_complaint`	A recipient reports a message as spam
Unsubscribe	`unsubscribe`	A recipient uses hosted unsubscribe, or a delivery event is classified as an unsubscribe
Manual	`manual`	A user, Team API client, import, or MCP client adds the record

The suppression reason is unsubscribe. The webhook event for a recipient unsubscribe is message.unsubscribed.

Disposable recipient suppression is a route setting, not a suppression-list reason that you can add manually. When the setting is enabled, Lettermint skips matching recipients only for the current message. It does not add them to a suppression list. See Route settings.

Automatic suppressions

Lettermint adds a suppression after some recipient signals. You do not need to add these addresses yourself.

Trigger	Scope	Mail blocked
Permanent failure for an invalid address, inactive mailbox, invalid domain, or hard quota issue	Team	All mail
Spam complaint	Source route	Broadcast mail on a broadcast route, or all mail on a transactional route
Unsubscribe through the hosted page or a delivery event	Source route	Broadcast mail on a broadcast route, or all mail on a transactional route

Only a permanent bounce can create a hard bounce suppression. Soft bounces, deferrals, temporary quota issues, and other delivery failures do not add an automatic suppression.

Scopes

Scope	Applies to	Required ID
Team	All projects and routes in the team	None
Project	All routes in one project	`project_id`
Route	One route	`route_id`

Higher-level suppressions take precedence. A team-level suppression blocks sends across all projects and routes.

Mail categories

The applies_to field controls which route types a suppression can block.

API value	Effect
`all`	Blocks transactional and broadcast mail in the selected scope
`broadcast`	Blocks broadcast mail only

Manual suppressions use all when you omit applies_to. You can use broadcast at team or project scope. At route scope, you can use it only with a broadcast route.

Hard bounce suppressions always use all. A complaint or unsubscribe must use route scope. Its mail category must match the route type.

Add suppressions

You can add one address or up to 1000 addresses in one Team API request.

import { Lettermint } from "lettermint";

const api = Lettermint.api(process.env.LETTERMINT_TEAM_TOKEN!);

await api.suppressions.create({
  emails: ["customer@example.com"],
  reason: "manual",
  scope: "project",
  project_id: "project-id",
});

This example omits applies_to, so the suppression blocks all mail in the project. Set it to broadcast when you want a manual team or project suppression to block broadcast mail only.

List recent suppressions

Use date filters when polling for suppressions that were created or updated during a window. Date-only values include the full day.

import { Lettermint } from "lettermint";

const api = Lettermint.api(process.env.LETTERMINT_TEAM_TOKEN!);
const suppressions = await api.suppressions.list({
  "filter[startDate]": "2026-01-01T00:00:00Z",
  "filter[endDate]": "2026-01-31",
});

Find the cause

An automatic suppression can include its source message. Use this message to find the delivery event that caused the suppression. The source message is not available when it was removed by the message retention policy or when the API token cannot read messages.

Remove suppressions

Users with the matching team or project suppression permission can remove team, project, and route suppressions from the dashboard. Team API clients with write:suppressions access can remove them too.

Removing a suppression deletes that record. The address can still be blocked by another matching record.

Spam complaint records use a protected removal flow. A removal request returns HTTP 202 when it creates or reuses a support review ticket. The record stays active until support approves the request. Request removal only after the recipient confirms that they want mail again, or when you have verified that the complaint was false.

Suppression webhooks

Transactional and broadcast routes can send a webhook whenever an individual suppression affecting them is added or removed:

suppression.added
suppression.removed

Each entry produces its own event, including entries added through a bulk request. Route suppressions notify webhooks on that route. Project suppressions notify webhooks for routes in the project. Team suppressions notify webhooks for routes in the team. Global suppressions do not emit these events. Inbound routes do not support them.

A removal event is sent only after the suppression is actually deleted. Requests that remain pending for manual review do not emit suppression.removed.

See Webhook events for payloads and field definitions.

Next steps

Email activity - Inspect suppressed message events
Routes - Understand route-level lists
Webhook events - Synchronize suppression changes affecting a route
Team API reference - Review suppression endpoints

Idempotency Tags