Lists and suppressions

Two mechanisms decide which addresses an inbox may talk to:

• Lists are allow and block lists you manage, for inbound (receive) and outbound (send) mail, at organization, pod or inbox level.
• Suppressions are addresses MachineMail will not send to, mostly added automatically after hard bounces and spam complaints.

Lists

A list is addressed by a direction and a type:

# Block a whole domain from reaching any inbox in the organization
curl https://api.machinemail.dev/v0/lists/receive/block \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entry": "*@spam.example", "reason": "noise"}'

{
  "entry": "spam.example",
  "organization_id": "org_01m4fy8h140000efvagszh6rpx",
  "reason": "noise",
  "direction": "receive",
  "list_type": "block",
  "entry_type": "domain",
  "created_at": "2026-10-09T09:00:16.403Z"
}

An entry is either an email address or a domain:

• ada@example.com is an email entry and matches that address only.
• example.com, @example.com and *@example.com all become the domain entry example.com. A domain entry also matches its subdomains, such as mail.example.com.

Entries are lowercased. Adding an entry that already exists returns the existing one.

Levels

The same endpoints exist at three levels. The path decides where the entry lives:

Each level supports GET (list entries), POST (add, body { entry, reason? }), GET .../{entry} and DELETE .../{entry}. Listing shows only the entries stored at that exact level.

When mail is checked against an inbox, the entries from all three levels apply together: the organization’s, the inbox’s pod’s and the inbox’s own.

How lists decide

For a given address and direction:

1. If it matches an allow entry, it is allowed.
2. Otherwise, if it matches a block entry, it is blocked.
3. Otherwise, if any allow entries exist for that direction, it is blocked. A non-empty allow list means “only these”.
4. Otherwise it is allowed.

So an allow entry always beats a block entry, and adding one allow entry turns that direction into an allowlist.

What blocking does

Receive. Mail from a blocked sender is still stored, but labelled BLOCKED only (no INBOX), and emits message.received.blocked instead of message.received. It is hidden from lists unless you pass include_blocked=true with a key that has label_blocked_read. This keeps an audit trail without putting the message in front of your agent.

Send. Sending to a blocked recipient fails with 403 forbidden (“Sending to … is blocked by a send list”). Nothing is sent to any recipient.

Lists and trust

Receive lists also feed the trust report. trust.sender.on_allow_list and on_block_list reflect them. An allowlisted sender whose mail passes aligned DMARC can reach the verified level without prior correspondence, and a blocklisted sender is always quarantined.

A receive allow list is a strong control for agents that should only take instructions from known people: everything else is blocked before the agent sees it. It is not a way to raise trust for a few senders while still receiving other mail.

Suppressions

A suppression stops all sending to an address from every inbox in the organization. Sending to a suppressed recipient fails with 403 forbidden (“Recipient … is suppressed (bounce)”).

MachineMail adds suppressions automatically:

{
  "email": "gone@example.com",
  "organization_id": "org_01m4fy8h140000efvagszh6rpx",
  "reason": "bounce",
  "detail": "550 5.1.1 user unknown",
  "source_message_id": "msg_01m4fy8h340000kzb2kp66c161",
  "created_at": "2026-10-09T09:20:00.000Z"
}

Suppressions are organization-wide and use the list_entry_read, list_entry_create and list_entry_delete permissions. Bounces and complaints also emit message.bounced and message.complained events.

A complaint suppression (the recipient reported your mail as spam) cannot be removed through the API, the CLI, MCP or the dashboard: DELETE returns 403 forbidden with Complaint suppressions can only be removed by MachineMail support; email support@machinemail.dev. Email support@machinemail.dev if the recipient has asked for your mail again. A later bounce for the same address does not replace a complaint.

Only remove a suppression when you know the address works again. Repeated sends to dead or complaining addresses hurt deliverability for everyone on the same domain.

Next