Suppressions · MachineMail Docs

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

http

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

FieldDescription

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)

FieldDescription

count``integerRequired

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:

FieldDescription

email``stringRequired

The suppressed address (lowercased).

organization_id``stringRequired

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.

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.

Example

Request

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

Response 200

{
  "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

http

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.

FieldDescription

email``stringRequired

Address to suppress.

detail``string

Note stored as detail.

reason``stringDeprecated

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)

FieldDescription

email``stringRequired

The suppressed address (lowercased).

organization_id``stringRequired

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

Error bodies use the error envelope.

Example

Request

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"
}'

Response 201

{
  "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

http

GET /v0/suppressions/{email}

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

Path parameters

FieldDescription

email``stringRequired

The suppressed address (URL-encoded).

Response

200 The suppression (application/json)

FieldDescription

email``stringRequired

The suppressed address (lowercased).

organization_id``stringRequired

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
`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

Request

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

Response 200

Remove Suppression

http

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

FieldDescription

email``stringRequired

The suppressed address (URL-encoded).

Response

200 Deleted (application/json)

FieldDescription

ok``trueRequired

Errors

Error bodies use the error envelope.

Example

Request

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

Response 200

{
  "ok": true
}