Skip to content
machinemail

Suppressions

Addresses we will not send to.

MethodPathSummary
GET/v0/suppressionsList Suppressions
POST/v0/suppressionsAdd 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

limitinteger
Maximum number of items to return. Default 50, maximum 500; larger values are capped.
page_tokenstring
next_page_token from the previous page.
ascendingboolean
Sort oldest first.

Response

200 A page of suppressions (application/json)

countintegerRequired
Number of items returned.
limitinteger
Maximum number of items per page. Default 50, maximum 500; larger values are capped.
next_page_tokenstring
Page token for pagination. Absent on the last page.
suppressionsSuppression[]Required
Newest first unless ascending is set.

Each item of suppressions is a Suppression:

emailstringRequired
The suppressed address (lowercased).
organization_idstringRequired
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.
detailstring
Free text: the bounce diagnostic, or the note given when the address was added manually.
source_message_idstring
Message whose bounce or complaint caused the suppression.
created_atstring (date-time)Required
When the address was suppressed.

Errors

StatusMeaning
400Invalid request: error.type is validation and error.param names the field.
401Missing, invalid, expired or revoked credential.
403The 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).
500Unexpected server error.

Error bodies use the error envelope.

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.

emailstringRequired
Address to suppress.
detailstring
Note stored as detail.
reasonstringDeprecated
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)

emailstringRequired
The suppressed address (lowercased).
organization_idstringRequired
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.
detailstring
Free text: the bounce diagnostic, or the note given when the address was added manually.
source_message_idstring
Message whose bounce or complaint caused the suppression.
created_atstring (date-time)Required
When the address was suppressed.

Errors

StatusMeaning
400Invalid request: error.type is validation and error.param names the field.
401Missing, invalid, expired or revoked credential.
403The 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).
500Unexpected server error.

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

emailstringRequired
The suppressed address (URL-encoded).

Response

200 The suppression (application/json)

emailstringRequired
The suppressed address (lowercased).
organization_idstringRequired
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.
detailstring
Free text: the bounce diagnostic, or the note given when the address was added manually.
source_message_idstring
Message whose bounce or complaint caused the suppression.
created_atstring (date-time)Required
When the address was suppressed.

Errors

StatusMeaning
401Missing, invalid, expired or revoked credential.
403The 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).
404Not found. Also returned for resources outside the credential scope.
500Unexpected 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
{
  "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

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

emailstringRequired
The suppressed address (URL-encoded).

Response

200 Deleted (application/json)

oktrueRequired

Errors

StatusMeaning
401Missing, invalid, expired or revoked credential.
403The 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).
404Not found. Also returned for resources outside the credential scope.
500Unexpected server error.

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
}

On this page

List SuppressionsAdd SuppressionGet SuppressionRemove Suppression
0% read