Skip to content
My Beast
Cart
Developer docsMenu

Mail · API reference

Webhooks

A webhook sends events about your emails to a URL of yours. You can have up to 5. The webhooks guide covers payloads, signatures and retries.

Endpoints

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

The webhook object

A URL and the events sent to it.

Fields

  • idstring

    Unique ID, starting with wh_.

  • urlstring

    Where events are sent.

  • eventsarray of strings

    The events sent to it.

  • created_atstring

    When the webhook was created (ISO 8601, UTC).

  • secretstring

    The signing secret, starting with whsec_. Only returned by Create a webhook. Use it to verify signatures.

Example
{
  "id": "wh_01JA2T4H8MC6YP",
  "url": "https://acme.com/webhooks/my-beast",
  "events": [
    "email.delivered",
    "email.bounced",
    "email.complained",
    "email.failed"
  ],
  "created_at": "2026-10-09T09:20:15Z"
}

Events

EventMeaning
email.sentWe started delivering an email to a recipient.
email.deliveredThe recipient's mail server accepted the email.
email.bouncedThe email bounced for a recipient. The address is now on your suppression list.
email.complainedA recipient marked the email as spam. The address is now on your suppression list.
email.failedWe didn't deliver the email to a recipient. reason says why.

Events are per recipient: an email to three addresses can send three of each. The webhooks guide shows the payload and how to check its signature.

Create a webhook

POST/webhooks

Starts sending the chosen events to a URL. The response includes the signing secret. Store it now: it isn't shown again.

Body

  • urlstringrequired

    Where to send events: a public https:// URL, up to 2,048 characters.

  • eventsarray of stringsrequired

    The events to send, one or more of email.sent, email.delivered, email.bounced, email.complained, email.failed.

Response

200 OK. The new webhook object, with its secret.

Errors

  • 403test_keyThe key is a test inbox's (mb_test_…). These endpoints take a live key.
  • 403webhook_limit_reachedYou already have 5 webhooks.
  • 422validation_errorThe URL isn't a public https:// URL, or events is empty or has an unknown event.

Any endpoint can also return the common errors.

Request

curl -X POST https://services.my-beast.com/mail/api/email/v1/webhooks \
  -H "Authorization: Bearer $MYBEAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://acme.com/webhooks/my-beast",
    "events": [
      "email.delivered",
      "email.bounced",
      "email.complained",
      "email.failed"
    ]
  }'

Response

200 OK
{
  "id": "wh_01JA2T4H8MC6YP",
  "url": "https://acme.com/webhooks/my-beast",
  "events": [
    "email.delivered",
    "email.bounced",
    "email.complained",
    "email.failed"
  ],
  "created_at": "2026-10-09T09:20:15Z",
  "secret": "whsec_5Kq8vR2xN7mT4bW9cJ3hL6pD1fG0sY"
}

List webhooks

GET/webhooks

Returns your webhooks, newest first. Secrets aren't included.

Query parameters

  • limitintegeroptional

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

  • afterstringoptional

    The ID of the last webhook on the previous page. Leave it out for the first page. See Pagination.

Response

200 OK. A page of webhook 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 a webhook in this list.

Any endpoint can also return the common errors.

Request

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

Response

200 OK
{
  "data": [
    {
      "id": "wh_01JA2T4H8MC6YP",
      "url": "https://acme.com/webhooks/my-beast",
      "events": [
        "email.delivered",
        "email.bounced",
        "email.complained",
        "email.failed"
      ],
      "created_at": "2026-10-09T09:20:15Z"
    }
  ],
  "has_more": false
}

Delete a webhook

DELETE/webhooks/{id}

Stops sending events to the webhook's URL, including deliveries that were waiting to be retried.

Path parameters

  • idstringrequired

    The webhook's ID.

Response

200 OK. The webhook's ID and deleted: true.

Errors

  • 403test_keyThe key is a test inbox's (mb_test_…). These endpoints take a live key.
  • 404not_foundNo webhook on your plan has this ID.

Any endpoint can also return the common errors.

Request

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

Response

200 OK
{
  "id": "wh_01JA2T4H8MC6YP",
  "deleted": true
}