API reference

Suppressions

The Suppressions endpoints.

Auth: Session token · Base URL: https://api.mailkite.dev

Endpoints

Each row expands to its request and response schema. The address bar follows along, so any endpoint can be linked to directly.

GET /api/contacts/suppressions List suppressed addresses (unsubscribes, hard bounces, spam complaints, manual). Sends to a suppressed address are dropped before delivery.

List suppressed addresses (unsubscribes, hard bounces, spam complaints, manual). Sends to a suppressed address are dropped before delivery.

Response body

suppressions-response.json

Field	Type	Notes
suppressions req	object[]	Addresses this account will not send to, newest first. Sends to a suppressed address are dropped before delivery.
suppressions[].id req	string	Suppression id (sup_…).
suppressions[].user_id req	string	Owning account (usr_…).
suppressions[].email req	string	The suppressed address (normalized lowercase).
suppressions[].reason req	"unsubscribe" · "hard_bounce" · "spam_complaint" · "manual"	Why the address is suppressed.
suppressions[].origin req	string	Who created it: system (bounce/complaint webhook) or customer (manual/API).
suppressions[].note req	string · null	Free-text note attached at creation — null when none.
suppressions[].created_at req	number	Creation time, ms epoch.

An actual response, recorded from the conformance suite.

response.json

{
  "suppressions": [
    {
      "id": "sup_4Kp8RwQz",
      "user_id": "usr_7Fj3MnQw",
      "email": "bounced@example.com",
      "reason": "hard_bounce",
      "origin": "system",
      "note": null,
      "created_at": 1753900000000
    }
  ]
}

suppressions-response.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/suppressions-response.json",
  "title": "Suppression list",
  "type": "object",
  "required": [
    "suppressions"
  ],
  "additionalProperties": false,
  "properties": {
    "suppressions": {
      "type": "array",
      "description": "Addresses this account will not send to, newest first. Sends to a suppressed address are dropped before delivery.",
      "items": {
        "type": "object",
        "required": [
          "id",
          "user_id",
          "email",
          "reason",
          "origin",
          "note",
          "created_at"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "Suppression id (sup_…).",
            "examples": [
              "sup_4Kp8RwQz"
            ]
          },
          "user_id": {
            "type": "string",
            "description": "Owning account (usr_…).",
            "examples": [
              "usr_7Fj3MnQw"
            ]
          },
          "email": {
            "type": "string",
            "description": "The suppressed address (normalized lowercase).",
            "examples": [
              "bounced@example.com"
            ]
          },
          "reason": {
            "type": "string",
            "enum": [
              "unsubscribe",
              "hard_bounce",
              "spam_complaint",
              "manual"
            ],
            "description": "Why the address is suppressed.",
            "examples": [
              "hard_bounce"
            ]
          },
          "origin": {
            "type": "string",
            "description": "Who created it: system (bounce/complaint webhook) or customer (manual/API).",
            "examples": [
              "system"
            ]
          },
          "note": {
            "type": [
              "string",
              "null"
            ],
            "description": "Free-text note attached at creation — null when none.",
            "examples": [
              null
            ]
          },
          "created_at": {
            "type": "number",
            "description": "Creation time, ms epoch.",
            "examples": [
              1753900000000
            ]
          }
        }
      }
    }
  }
}

POST /api/contacts/suppressions Suppress an address so this account never sends to it again (reason defaults to manual).

Suppress an address so this account never sends to it again (reason defaults to manual).

Request body

add-suppression-request.json

Field	Type	Notes
email req	string	The address to stop sending to.
reason	"unsubscribe" · "hard_bounce" · "spam_complaint" · "manual"	Why — defaults to manual when omitted or unrecognized.
note	string	Optional free-text note (who/why), shown alongside the entry.

The smallest body that makes this call — every other field is optional.

request.json

{
  "email": "unsubscribed@example.com",
  "reason": "unsubscribe",
  "note": "customer asked via support ticket #482"
}

add-suppression-request.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/add-suppression-request.json",
  "title": "Add suppression request body",
  "type": "object",
  "required": [
    "email"
  ],
  "additionalProperties": false,
  "properties": {
    "email": {
      "type": "string",
      "description": "The address to stop sending to.",
      "examples": [
        "unsubscribed@example.com"
      ]
    },
    "reason": {
      "type": "string",
      "enum": [
        "unsubscribe",
        "hard_bounce",
        "spam_complaint",
        "manual"
      ],
      "description": "Why — defaults to manual when omitted or unrecognized.",
      "examples": [
        "unsubscribe"
      ]
    },
    "note": {
      "type": "string",
      "description": "Optional free-text note (who/why), shown alongside the entry.",
      "examples": [
        "customer asked via support ticket #482"
      ]
    }
  }
}

Response body

add-suppression-response.json

Field	Type	Notes
suppressed req	boolean	Always true on success.
email req	string	The normalized address that was suppressed.

add-suppression-response.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/add-suppression-response.json",
  "title": "Add suppression result",
  "type": "object",
  "required": [
    "suppressed",
    "email"
  ],
  "additionalProperties": false,
  "properties": {
    "suppressed": {
      "type": "boolean",
      "description": "Always true on success.",
      "examples": [
        true
      ]
    },
    "email": {
      "type": "string",
      "description": "The normalized address that was suppressed.",
      "examples": [
        "unsubscribed@example.com"
      ]
    }
  }
}

DELETE /api/contacts/suppressions/:email Remove an address from the suppression list (URL-encode the email in the path). Removing an unsuppressed address is a no-op success.

Remove an address from the suppression list (URL-encode the email in the path). Removing an unsuppressed address is a no-op success.

Response body

remove-suppression-response.json

Field	Type	Notes
removed req	boolean	Always true — removing an address that was not suppressed is a no-op success.

remove-suppression-response.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/remove-suppression-response.json",
  "title": "Remove suppression result",
  "type": "object",
  "required": [
    "removed"
  ],
  "additionalProperties": false,
  "properties": {
    "removed": {
      "type": "boolean",
      "description": "Always true — removing an address that was not suppressed is a no-op success.",
      "examples": [
        true
      ]
    }
  }
}