BansosMailBansosMail
Sign in

Integrate BansosMail in minutes

Create protected inboxes, receive incoming emails, and retrieve messages through a simple API — without maintaining your own mail server.

Live API — every endpoint below is real and callable today
Node.js · JavaScript
const API_KEY = process.env.BANSOSMAIL_API_KEY;
const BASE_URL = "https://www.bansosmail.com/api/v1";

async function bansosmail(path) {
  const res = await fetch(`${BASE_URL}${path}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  return res.json();
}

// 1. Access a protected inbox by address
const inbox = await bansosmail("/inboxes?address=you@example.com");

// 2. Retrieve incoming messages
const { messages } = await bansosmail(`/inboxes/${inbox.id}/messages`);

// 3. Retrieve one message's details (includes 24h expiry)
const message = await bansosmail(`/inboxes/${inbox.id}/messages/${messages[0].id}`);

console.log(message.subject, "expires at", message.expires_at);
Every example demonstrates the same documented flow below.Open API reference
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://www.bansosmail.com/api/v1
POST/inboxes

Auto-generate a new protected inbox. Omit domain/username to get a random address on the default active public domain — the exact flow for spinning up a throwaway inbox to receive an OTP or verification link.

Parameters

  • domainPublic domain to use — optional, defaults to the first active one
  • usernameLocal part (3–64 lowercase letters/digits/._-) — optional, randomly generated if omitted
curl -X POST \
  -H "Authorization: Bearer bm_live_..." \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://www.bansosmail.com/api/v1/inboxes

Response

{
  "id": "ib_abc123",
  "address": "kx8pd2m1@tinghohoa.me",
  "domain": "tinghohoa.me",
  "created_at": "2026-07-23T04:59:06.919Z"
}
GET/inboxes?address=:address

Look up an inbox your key owns by its full email address.

Parameters

  • addressFull email address — required
curl -H "Authorization: Bearer bm_live_..." \
  "https://www.bansosmail.com/api/v1/inboxes?address=kx8pd2m1@tinghohoa.me"

Response

{
  "id": "ib_abc123",
  "username": "kx8pd2m1",
  "domain": "tinghohoa.me",
  "domain_kind": "public",
  "kind": "protected",
  "created_at": "2026-07-23T04:59:06.919Z"
}
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_live_..." \
  https://www.bansosmail.com/api/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/latest

Fetch only the most recent non-expired message — the exact endpoint for polling an inbox for its OTP or verification link right after triggering it.

Parameters

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

Response

{
  "message": {
    "id": "msg_abc",
    "from_address": "noreply@example.com",
    "subject": "Your verification code is 482913",
    "text_body": "Your one-time verification code is 482913.",
    "received_at": "2026-07-23T04:59:48.318Z",
    "expires_at": "2026-07-24T04:59:48.318Z"
  }
}
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_live_..." \
  https://www.bansosmail.com/api/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_live_..." \
  https://www.bansosmail.com/api/v1/inboxes/ib_abc123/messages/msg_abc

Response

{ "deleted": true }

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.