Skip to content
MailBench SMTP
Start free
Menu
Documentation menu

API reference

Webhooks

Signed HTTP callbacks for new messages.

List webhooks

GET/v1/webhooks

Signing secrets are never listed.

Returns a list of

  • idstringrequired
  • inbox_idstring or null
  • urlstring (uri)required
  • created_atstring (date-time)required

Errors

401Missing or invalid API key.
429Too many requests. Wait `Retry-After` seconds.
curl / JavaScript / Python
curl "https://app.mailbench.dev/v1/webhooks" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch("https://app.mailbench.dev/v1/webhooks", {
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const { data } = await res.json();
import os, requests

res = requests.get(
    "https://app.mailbench.dev/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": [
    {
      "id": "wh_4mq7h2b9x1k3d8ra",
      "inbox_id": null,
      "url": "https://ci.example.com/hooks/email",
      "created_at": "2026-10-12T10:00:00Z"
    }
  ]
}

Create a webhook

POST/v1/webhooks

Each new message is POSTed to url as JSON, signed with the returned secret (shown once). Failed deliveries are retried. How many webhooks you can have depends on your plan (402 limit_reached beyond it).

Request body

  • urlstring (uri)required
  • inbox_idstring or null
    Limit to one inbox. Omit for every inbox in the workspace.

Returns

  • idstringrequired
  • inbox_idstring or null
  • urlstring (uri)required
  • created_atstring (date-time)required
  • secretstringrequired
    Used to sign deliveries. Shown once.

Errors

400The request was malformed or a value was invalid.
401Missing or invalid API key.
402Your plan's limit for this would be exceeded (`limit_reached`).
403The key is read-only, or the action needs a dashboard session.
404No such object in this workspace.
429Too many requests. Wait `Retry-After` seconds.
curl / JavaScript / Python
curl -X POST "https://app.mailbench.dev/v1/webhooks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://ci.example.com/hooks/email", "inbox_id": null}'
const res = await fetch("https://app.mailbench.dev/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "url": "https://ci.example.com/hooks/email",
    "inbox_id": null
  }),
});
const { data } = await res.json();
import os, requests

res = requests.post(
    "https://app.mailbench.dev/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "url": "https://ci.example.com/hooks/email",
        "inbox_id": None,
    },
)
data = res.json()["data"]
Response 201
{
  "success": true,
  "data": {
    "id": "wh_4mq7h2b9x1k3d8ra",
    "inbox_id": null,
    "url": "https://ci.example.com/hooks/email",
    "created_at": "2026-10-12T10:00:00Z",
    "secret": "string"
  }
}

Delete a webhook

DELETE/v1/webhooks/{id}

Path parameters

  • idstringrequired

Returns

  • deletedintegerrequired

Errors

401Missing or invalid API key.
403The key is read-only, or the action needs a dashboard session.
404No such object in this workspace.
429Too many requests. Wait `Retry-After` seconds.
curl / JavaScript / Python
curl -X DELETE "https://app.mailbench.dev/v1/webhooks/wh_4mq7h2b9x1k3d8ra" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch("https://app.mailbench.dev/v1/webhooks/wh_4mq7h2b9x1k3d8ra", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const { data } = await res.json();
import os, requests

res = requests.delete(
    "https://app.mailbench.dev/v1/webhooks/wh_4mq7h2b9x1k3d8ra",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": {
    "deleted": 1
  }
}

Recent deliveries

GET/v1/webhooks/{id}/deliveries

The last 50, with status, attempts and the last HTTP status or error.

Path parameters

  • idstringrequired

Returns a list of

  • idinteger (int64)required
  • message_idstringrequired
  • eventstringrequired
  • statusstringrequired
    One of pending, delivered, failed.
  • attemptsintegerrequired
  • last_statusinteger or null
    The last HTTP status your endpoint returned.
  • last_errorstring or null
  • created_atstring (date-time)required
  • finished_atstring (date-time) or null
  • next_attempt_atstring (date-time) or null

Errors

401Missing or invalid API key.
404No such object in this workspace.
429Too many requests. Wait `Retry-After` seconds.
curl / JavaScript / Python
curl "https://app.mailbench.dev/v1/webhooks/wh_4mq7h2b9x1k3d8ra/deliveries" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch("https://app.mailbench.dev/v1/webhooks/wh_4mq7h2b9x1k3d8ra/deliveries", {
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const { data } = await res.json();
import os, requests

res = requests.get(
    "https://app.mailbench.dev/v1/webhooks/wh_4mq7h2b9x1k3d8ra/deliveries",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": [
    {
      "id": 8412,
      "message_id": "msg_htumcicppd26jek6",
      "event": "message.received",
      "status": "pending",
      "attempts": 1,
      "last_status": 200,
      "last_error": null,
      "created_at": "2026-10-12T10:00:00Z",
      "finished_at": null,
      "next_attempt_at": null
    }
  ]
}

Send a test event

POST/v1/webhooks/{id}/test

Queues a webhook.test event. Check the result under deliveries.

Path parameters

  • idstringrequired

Returns

  • delivery_idinteger (int64)required

Errors

401Missing or invalid API key.
403The key is read-only, or the action needs a dashboard session.
404No such object in this workspace.
429Too many requests. Wait `Retry-After` seconds.
curl / JavaScript / Python
curl -X POST "https://app.mailbench.dev/v1/webhooks/wh_4mq7h2b9x1k3d8ra/test" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch("https://app.mailbench.dev/v1/webhooks/wh_4mq7h2b9x1k3d8ra/test", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const { data } = await res.json();
import os, requests

res = requests.post(
    "https://app.mailbench.dev/v1/webhooks/wh_4mq7h2b9x1k3d8ra/test",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
data = res.json()["data"]
Response 202
{
  "success": true,
  "data": {
    "delivery_id": 1
  }
}

Retry a finished delivery

POST/v1/webhook-deliveries/{id}/retry

Queues it again now with a fresh attempt budget. Only finished deliveries can be retried.

Path parameters

  • idinteger (int64)required
    Delivery ID, from the deliveries list.

Returns

  • requeuedinteger (int64)required

Errors

401Missing or invalid API key.
403The key is read-only, or the action needs a dashboard session.
404No such object in this workspace.
429Too many requests. Wait `Retry-After` seconds.
curl / JavaScript / Python
curl -X POST "https://app.mailbench.dev/v1/webhook-deliveries/<id>/retry" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch("https://app.mailbench.dev/v1/webhook-deliveries/<id>/retry", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const { data } = await res.json();
import os, requests

res = requests.post(
    "https://app.mailbench.dev/v1/webhook-deliveries/<id>/retry",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": {
    "requeued": 1
  }
}