suppressions.md

Suppressions

List, add, check and remove the addresses MachineMail will not send to. Permanent bounces and complaints add an address to the suppression list automatically.

Source: https://machinemail.dev/docs/reference/api/suppressions

Method Path Summary
GET /v0/suppressions List Suppressions
POST /v0/suppressions Add Suppression
GET /v0/suppressions/{email} Get Suppression
DELETE /v0/suppressions/{email} Remove Suppression

List Suppressions

GET /v0/suppressions

Every suppressed address in the organization (also for pod and inbox credentials). Addresses are added automatically on permanent bounces and complaints.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: list_entry_read.

Query parameters

Field Type Description
limit integer Maximum number of items to return. Default 50, maximum 500; larger values are capped.
page_token string next_page_token from the previous page.
ascending boolean Sort oldest first.

Response

200 A page of suppressions (application/json)

Field Type Description
count integer required Number of items returned.
limit integer Maximum number of items per page. Default 50, maximum 500; larger values are capped.
next_page_token string Page token for pagination. Absent on the last page.
suppressions Suppression[] required Newest first unless ascending is set.

Each item of suppressions is a Suppression:

Field Type Description
email string required The suppressed address (lowercased).
organization_id string required ID of the organization.
reason "bounce" | "complaint" | "manual" required bounce: a permanent bounce. complaint: the recipient reported spam; only MachineMail support can remove it. manual: added with POST /v0/suppressions.
detail string Free text: the bounce diagnostic, or the note given when the address was added manually.
source_message_id string Message whose bounce or complaint caused the suppression.
created_at string (date-time) required When the address was suppressed.

Errors

Status Meaning
400 Invalid request: error.type is validation and error.param names the field.
401 Missing, invalid, expired or revoked credential.
403 The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
500 Unexpected server error.

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/suppressions" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "count": 1,
  "limit": 50,
  "next_page_token": "eyJvIjo1MH0",
  "suppressions": [
    {
      "email": "agent@machinemail.dev",
      "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
      "reason": "bounce",
      "detail": "string",
      "source_message_id": "string",
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ]
}

Add Suppression

POST /v0/suppressions

Suppress an address for the whole organization, with reason: "manual". Adding an address that is already suppressed replaces a bounce or manual suppression (its reason becomes manual); a complaint suppression is returned unchanged. Sends to a suppressed address return 403.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: list_entry_create.

Request body

Content type: application/json.

Field Type Description
email string required Address to suppress.
detail string Note stored as detail.
reason string deprecated Old name of detail (it is stored as detail; the suppression reason is always manual). Ignored when detail is set.

Response

201 Created (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/v0/suppressions" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "agent@machinemail.dev",
  "reason": "string"
}'

{
  "email": "agent@machinemail.dev",
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "reason": "bounce",
  "detail": "string",
  "source_message_id": "string",
  "created_at": "2026-10-01T12:00:00.000Z"
}

Get Suppression

GET /v0/suppressions/{email}

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: list_entry_read.

Path parameters

Field Type Description
email string required The suppressed address (URL-encoded).

Response

200 The suppression (application/json)

Errors

Status Meaning
401 Missing, invalid, expired or revoked credential.
403 The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
404 Not found. Also returned for resources outside the credential scope.
500 Unexpected server error.

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/suppressions/customer@example.com" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "email": "agent@machinemail.dev",
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "reason": "bounce",
  "detail": "string",
  "source_message_id": "string",
  "created_at": "2026-10-01T12:00:00.000Z"
}

Remove Suppression

DELETE /v0/suppressions/{email}

Allow sending to the address again. Organization-scoped credentials only: pod and inbox credentials get 403. Only bounce and manual suppressions can be removed: a complaint suppression returns 403 (Complaint suppressions can only be removed by MachineMail support; email support@machinemail.dev).

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: list_entry_delete.

Path parameters

Field Type Description
email string required The suppressed address (URL-encoded).

Response

200 Deleted (application/json)

Field Type Description
ok true required

Errors

Error bodies use the error envelope.

Example

curl -X DELETE "https://api.machinemail.dev/v0/suppressions/customer@example.com" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "ok": true
}