Skip to content
My Beast
Cart
Developer docsMenu

Mail · API reference

Suppressions

Your suppression list holds the addresses we won't send to, because they bounced or the recipient complained. We add them automatically. See Bounces and suppressions.

Endpoints

https://services.my-beast.com/mail/api/email/v1

The suppression object

An address on your suppression list, and why it's there.

Fields

  • emailstring

    The address. Addresses are compared without regard to case.

  • reasonstring

    bounced or complained.

  • email_idstring

    The ID of the email that bounced or was complained about.

  • created_atstring

    When the address was added (ISO 8601, UTC).

Example
{
  "email": "old-address@example.com",
  "reason": "bounced",
  "email_id": "em_01JA2M3C9VD5RT",
  "created_at": "2026-10-02T15:41:09Z"
}

List suppressions

GET/suppressions

Returns the addresses on your suppression list, newest first.

Query parameters

  • limitintegeroptional

    How many to return, from 1 to 100. Default 20.

  • afterstringoptional

    The email of the last item on the previous page. Leave it out for the first page. See Pagination.

Response

200 OK. A page of suppression objects.

Errors

  • 403test_keyThe key is a test inbox's (mb_test_…). These endpoints take a live key.
  • 422validation_errorlimit is out of range, or after isn't an address in this list.

Any endpoint can also return the common errors.

Request

curl https://services.my-beast.com/mail/api/email/v1/suppressions \
  -H "Authorization: Bearer $MYBEAST_API_KEY"

Response

200 OK
{
  "data": [
    {
      "email": "old-address@example.com",
      "reason": "bounced",
      "email_id": "em_01JA2M3C9VD5RT",
      "created_at": "2026-10-02T15:41:09Z"
    }
  ],
  "has_more": false
}

Remove a suppression

DELETE/suppressions/{email}

Takes an address off your suppression list, so you can send to it again. If it bounces or complains again, it's added back.

Path parameters

  • emailstringrequired

    The address, URL-encoded (@ becomes %40).

Response

200 OK. The address and deleted: true.

Errors

  • 403test_keyThe key is a test inbox's (mb_test_…). These endpoints take a live key.
  • 404not_foundThis address isn't on your suppression list.

Any endpoint can also return the common errors.

Request

curl -X DELETE https://services.my-beast.com/mail/api/email/v1/suppressions/old-address%40example.com \
  -H "Authorization: Bearer $MYBEAST_API_KEY"

Response

200 OK
{
  "email": "old-address@example.com",
  "deleted": true
}