Skip to content
MailBench SMTP
Start free
Menu
Documentation menu

API reference

Testing

Rendered views and failure simulation.

The latest message, rendered as HTML

GET/v1/inboxes/{inbox_id}/messages/latest/view.html

Handy for screenshot and visual-regression tests.

Path parameters

  • inbox_idstringrequired
    Inbox ID.

Returns

The HTML.

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/inboxes/box_g3bekcev4z7i4psq/messages/latest/view.html" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch("https://app.mailbench.dev/v1/inboxes/box_g3bekcev4z7i4psq/messages/latest/view.html", {
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const body = await res.text();
import os, requests

res = requests.get(
    "https://app.mailbench.dev/v1/inboxes/box_g3bekcev4z7i4psq/messages/latest/view.html",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
body = res.text

The latest message, as plain text

GET/v1/inboxes/{inbox_id}/messages/latest/view.txt

Path parameters

  • inbox_idstringrequired
    Inbox ID.

Returns

The text.

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/inboxes/box_g3bekcev4z7i4psq/messages/latest/view.txt" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch("https://app.mailbench.dev/v1/inboxes/box_g3bekcev4z7i4psq/messages/latest/view.txt", {
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const body = await res.text();
import os, requests

res = requests.get(
    "https://app.mailbench.dev/v1/inboxes/box_g3bekcev4z7i4psq/messages/latest/view.txt",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
body = res.text

Get the failure-simulation settings

GET/v1/inboxes/{id}/chaos

Chaos makes the inbox's SMTP server fail on purpose, so you can test how your app handles refused senders, refused recipients or failed logins.

Path parameters

  • idstringrequired
    Inbox ID.

Returns

  • idstring
  • workspace_idstring
  • inbox_idstring or null
  • enabledbooleanrequired
  • senderobjectrequired
    Child attributes
    • error_codeintegerrequired
      The SMTP reply code to fail with, for example 451 or 550.
    • probabilityintegerrequired
      Percent of attempts that fail.
  • recipientobjectrequired
    Child attributes
    • error_codeintegerrequired
      The SMTP reply code to fail with, for example 451 or 550.
    • probabilityintegerrequired
      Percent of attempts that fail.
  • authenticationobjectrequired
    Child attributes
    • error_codeintegerrequired
      The SMTP reply code to fail with, for example 451 or 550.
    • probabilityintegerrequired
      Percent of attempts that fail.
  • created_atstring (date-time)
  • updated_atstring (date-time)

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/inboxes/box_g3bekcev4z7i4psq/chaos" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch("https://app.mailbench.dev/v1/inboxes/box_g3bekcev4z7i4psq/chaos", {
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const { data } = await res.json();
import os, requests

res = requests.get(
    "https://app.mailbench.dev/v1/inboxes/box_g3bekcev4z7i4psq/chaos",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": {
    "id": "string",
    "workspace_id": "string",
    "inbox_id": null,
    "enabled": true,
    "sender": {
      "error_code": 451,
      "probability": 1
    },
    "recipient": {
      "error_code": 451,
      "probability": 1
    },
    "authentication": {
      "error_code": 451,
      "probability": 1
    },
    "created_at": "2026-10-12T10:00:00Z",
    "updated_at": "2026-10-12T10:00:00Z"
  }
}

Set the failure-simulation settings

PUT/v1/inboxes/{id}/chaos

Path parameters

  • idstringrequired
    Inbox ID.

Request body

  • enabledboolean
  • senderobject
    Child attributes
    • error_codeintegerrequired
      The SMTP reply code to fail with, for example 451 or 550.
    • probabilityintegerrequired
      Percent of attempts that fail.
  • recipientobject
    Child attributes
    • error_codeintegerrequired
      The SMTP reply code to fail with, for example 451 or 550.
    • probabilityintegerrequired
      Percent of attempts that fail.
  • authenticationobject
    Child attributes
    • error_codeintegerrequired
      The SMTP reply code to fail with, for example 451 or 550.
    • probabilityintegerrequired
      Percent of attempts that fail.

Returns

  • idstring
  • workspace_idstring
  • inbox_idstring or null
  • enabledbooleanrequired
  • senderobjectrequired
    Child attributes
    • error_codeintegerrequired
      The SMTP reply code to fail with, for example 451 or 550.
    • probabilityintegerrequired
      Percent of attempts that fail.
  • recipientobjectrequired
    Child attributes
    • error_codeintegerrequired
      The SMTP reply code to fail with, for example 451 or 550.
    • probabilityintegerrequired
      Percent of attempts that fail.
  • authenticationobjectrequired
    Child attributes
    • error_codeintegerrequired
      The SMTP reply code to fail with, for example 451 or 550.
    • probabilityintegerrequired
      Percent of attempts that fail.
  • created_atstring (date-time)
  • updated_atstring (date-time)

Errors

400The request was malformed or a value was invalid.
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 PUT "https://app.mailbench.dev/v1/inboxes/box_g3bekcev4z7i4psq/chaos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "sender": {"error_code": 451, "probability": 1}, "recipient": {"error_code": 451, "probability": 1}, "authentication": {"error_code": 451, "probability": 1}}'
const res = await fetch("https://app.mailbench.dev/v1/inboxes/box_g3bekcev4z7i4psq/chaos", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "enabled": true,
    "sender": {
      "error_code": 451,
      "probability": 1
    },
    "recipient": {
      "error_code": 451,
      "probability": 1
    },
    "authentication": {
      "error_code": 451,
      "probability": 1
    }
  }),
});
const { data } = await res.json();
import os, requests

res = requests.put(
    "https://app.mailbench.dev/v1/inboxes/box_g3bekcev4z7i4psq/chaos",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "enabled": True,
        "sender": {
            "error_code": 451,
            "probability": 1,
        },
        "recipient": {
            "error_code": 451,
            "probability": 1,
        },
        "authentication": {
            "error_code": 451,
            "probability": 1,
        },
    },
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": {
    "id": "string",
    "workspace_id": "string",
    "inbox_id": null,
    "enabled": true,
    "sender": {
      "error_code": 451,
      "probability": 1
    },
    "recipient": {
      "error_code": 451,
      "probability": 1
    },
    "authentication": {
      "error_code": 451,
      "probability": 1
    },
    "created_at": "2026-10-12T10:00:00Z",
    "updated_at": "2026-10-12T10:00:00Z"
  }
}

A message, rendered as HTML

GET/v1/inboxes/{inbox_id}/messages/{message_id}/view.html

Path parameters

  • inbox_idstringrequired
    Inbox ID.
  • message_idstringrequired

Returns

The HTML.

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/inboxes/box_g3bekcev4z7i4psq/messages/<message_id>/view.html" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch("https://app.mailbench.dev/v1/inboxes/box_g3bekcev4z7i4psq/messages/<message_id>/view.html", {
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const body = await res.text();
import os, requests

res = requests.get(
    "https://app.mailbench.dev/v1/inboxes/box_g3bekcev4z7i4psq/messages/<message_id>/view.html",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
body = res.text

Dry-run the failure simulation

POST/v1/inboxes/{id}/chaos/test

Rolls the dice once for each trigger and reports what would have happened. Nothing is sent.

Path parameters

  • idstringrequired
    Inbox ID.

Returns

  • enabledboolean
  • senderobject
    Child attributes
    • triggeredboolean
    • codeinteger
    • messagestring
  • recipientobject
    Child attributes
    • triggeredboolean
    • codeinteger
    • messagestring
  • authenticationobject
    Child attributes
    • triggeredboolean
    • codeinteger
    • messagestring

Errors

401Missing or invalid API key.
404No such object in this workspace.
429Too many requests. Wait `Retry-After` seconds.
curl / JavaScript / Python
curl -X POST "https://app.mailbench.dev/v1/inboxes/box_g3bekcev4z7i4psq/chaos/test" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch("https://app.mailbench.dev/v1/inboxes/box_g3bekcev4z7i4psq/chaos/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/inboxes/box_g3bekcev4z7i4psq/chaos/test",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": {
    "enabled": true,
    "sender": {
      "triggered": true,
      "code": 1,
      "message": "string"
    },
    "recipient": {
      "triggered": true,
      "code": 1,
      "message": "string"
    },
    "authentication": {
      "triggered": true,
      "code": 1,
      "message": "string"
    }
  }
}