Skip to content
MailBench SMTP
Start free
Menu
Documentation menu

API reference

Inboxes

An inbox has its own SMTP username and password.

List inboxes

GET/v1/inboxes

Returns a list of

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

res = requests.get(
    "https://app.mailbench.dev/v1/inboxes",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": [
    {
      "id": "box_g3bekcev4z7i4psq",
      "name": "Staging app",
      "smtp_username": "u_4f8k2m9x",
      "message_count": 12,
      "created_at": "2026-10-12T10:00:00Z"
    }
  ]
}

Create an inbox

POST/v1/inboxes

Returns the SMTP credentials. The password is shown once; rotate it with POST /v1/inboxes/{id}/credentials if you lose it.

Request body

  • namestringrequired

Returns

  • idstringrequired
  • namestringrequired
  • smtp_usernamestringrequired
  • message_countintegerrequired
  • created_atstring (date-time)required
  • smtpobjectrequired
    Child attributes
    • hoststringrequired
    • portsarray of integersrequired
    • usernamestringrequired
    • passwordstringrequired
      Shown once.
    • notestring

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.
409An inbox with that name already exists.
429Too many requests. Wait `Retry-After` seconds.
curl / JavaScript / Python
curl -X POST "https://app.mailbench.dev/v1/inboxes" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Staging app"}'
const res = await fetch("https://app.mailbench.dev/v1/inboxes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Staging app"
  }),
});
const { data } = await res.json();
import os, requests

res = requests.post(
    "https://app.mailbench.dev/v1/inboxes",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "name": "Staging app",
    },
)
data = res.json()["data"]
Response 201
{
  "success": true,
  "data": {
    "id": "box_g3bekcev4z7i4psq",
    "name": "Staging app",
    "smtp_username": "u_4f8k2m9x",
    "message_count": 12,
    "created_at": "2026-10-12T10:00:00Z",
    "smtp": {
      "host": "smtp.example.com",
      "ports": [
        587,
        465,
        2525
      ],
      "username": "string",
      "password": "string",
      "note": "string"
    }
  }
}

Get an inbox

GET/v1/inboxes/{id}

Path parameters

  • idstringrequired
    Inbox ID.

Returns

  • idstringrequired
  • namestringrequired
  • smtp_usernamestringrequired
  • message_countintegerrequired
  • created_atstring (date-time)required

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" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch("https://app.mailbench.dev/v1/inboxes/box_g3bekcev4z7i4psq", {
  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",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": {
    "id": "box_g3bekcev4z7i4psq",
    "name": "Staging app",
    "smtp_username": "u_4f8k2m9x",
    "message_count": 12,
    "created_at": "2026-10-12T10:00:00Z"
  }
}

Delete an inbox and every message in it

DELETE/v1/inboxes/{id}

Path parameters

  • idstringrequired
    Inbox ID.

Returns

  • deleted_messagesintegerrequired

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/inboxes/box_g3bekcev4z7i4psq" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch("https://app.mailbench.dev/v1/inboxes/box_g3bekcev4z7i4psq", {
  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/inboxes/box_g3bekcev4z7i4psq",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": {
    "deleted_messages": 1
  }
}

Rotate the SMTP password

POST/v1/inboxes/{id}/credentials

The old password stops working immediately. The new one is shown once.

Path parameters

  • idstringrequired
    Inbox ID.

Returns

  • idstringrequired
  • namestringrequired
  • smtp_usernamestringrequired
  • message_countintegerrequired
  • created_atstring (date-time)required
  • smtpobjectrequired
    Child attributes
    • hoststringrequired
    • portsarray of integersrequired
    • usernamestringrequired
    • passwordstringrequired
      Shown once.
    • notestring

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/inboxes/box_g3bekcev4z7i4psq/credentials" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch("https://app.mailbench.dev/v1/inboxes/box_g3bekcev4z7i4psq/credentials", {
  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/credentials",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": {
    "id": "box_g3bekcev4z7i4psq",
    "name": "Staging app",
    "smtp_username": "u_4f8k2m9x",
    "message_count": 12,
    "created_at": "2026-10-12T10:00:00Z",
    "smtp": {
      "host": "smtp.example.com",
      "ports": [
        587,
        465,
        2525
      ],
      "username": "string",
      "password": "string",
      "note": "string"
    }
  }
}

Delete every message in an inbox

DELETE/v1/inboxes/{id}/messages

The inbox and its credentials stay.

Path parameters

  • idstringrequired
    Inbox ID.

Returns

  • deleted_messagesintegerrequired

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/inboxes/box_g3bekcev4z7i4psq/messages" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch("https://app.mailbench.dev/v1/inboxes/box_g3bekcev4z7i4psq/messages", {
  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/inboxes/box_g3bekcev4z7i4psq/messages",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": {
    "deleted_messages": 1
  }
}