B
BansosMail
Sign in
Built for developers

Receive emails with a developer-first API

Create temporary or protected inboxes, retrieve incoming messages the moment they arrive, and manage access with scoped tokens — all through a small, predictable REST API.

Read authenticationIllustrative demo — not a live connection.
Live demo
API Reference

API Reference

Every endpoint below is documented with request parameters, example requests, and real response shapes.

Authentication

All requests require an API key sent via the Authorization header.

Create a key from your Dashboard. The plaintext secret is shown once. Keys cannot be regenerated — revoke and issue a new one.
Authorization: Bearer <YOUR_BANSOSMAIL_API_KEY>

Base URL

https://api.bansosmail.com/v1
GET/inboxes/:id/messages

Retrieve all non-expired messages for an inbox, newest first, within the 24-hour retention window.

Parameters

  • idInbox ID (uuid) — required
curl -H "Authorization: Bearer bm_api_..." \
  https://api.bansosmail.com/v1/inboxes/ib_abc123/messages

Response

{
  "messages": [
    {
      "id": "msg_abc",
      "from_address": "sender@example.com",
      "subject": "Your verification code",
      "text_body": "Your code is 428193",
      "received_at": "2026-07-22T10:30:00Z",
      "expires_at": "2026-07-23T10:30:00Z"
    }
  ]
}
GET/inboxes/:id/messages/:messageId

Fetch a single message including full HTML and plain-text body.

Parameters

  • idInbox ID (uuid) — required
  • messageIdMessage ID (uuid) — required
curl -H "Authorization: Bearer bm_api_..." \
  https://api.bansosmail.com/v1/inboxes/ib_abc123/messages/msg_abc

Response

{
  "id": "msg_abc",
  "from_address": "sender@example.com",
  "subject": "Your verification code",
  "text_body": "Your code is 428193",
  "html_body": "<p>Your code is <b>428193</b></p>",
  "received_at": "2026-07-22T10:30:00Z",
  "expires_at": "2026-07-23T10:30:00Z"
}
DELETE/inboxes/:id/messages/:messageId

Permanently delete a message and its metadata.

Parameters

  • idInbox ID (uuid) — required
  • messageIdMessage ID (uuid) — required
curl -X DELETE \
  -H "Authorization: Bearer bm_api_..." \
  https://api.bansosmail.com/v1/inboxes/ib_abc123/messages/msg_abc

Response

{ "deleted": true }
GET/inboxes?address=:address

Look up an inbox by its full email address.

Parameters

  • addressFull email address — required
curl -H "Authorization: Bearer bm_api_..." \
  "https://api.bansosmail.com/v1/inboxes?address=user@example.com"

Response

{
  "id": "ib_abc123",
  "username": "user",
  "domain": "example.com",
  "domain_kind": "public",
  "kind": "public_unclaimed",
  "created_at": "2026-07-22T08:00:00Z"
}

SDK Examples

const API_KEY = "bm_api_...";
const INBOX_ID = "ib_abc123";

const res = await fetch(
  `https://api.bansosmail.com/v1/inboxes/${INBOX_ID}/messages`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);

const { messages } = await res.json();
for (const msg of messages) {
  console.log(msg.subject, msg.from_address);
}

Error Codes

CodeDescription
200Success
400Bad request
401Missing/invalid API key
403Insufficient permissions
404Not found
429Rate limit exceeded
500Internal server error
Rate limiting: 100 requests/minute per API key. Exceeding it returns 429.