Developer API - NerBoll

Overview

The API allows you to programmatically create temporary or permanent mailboxes, retrieve emails, and manage email data. It is designed for automated testing, CI/CD pipelines, and integration workflows.

ℹ️

Base URLs: /api/v1 for temporary mailboxes and /api/v2 for permanent mailbox provisioning.

Authentication

The API uses a simple token-based authentication system. When you create a temporary mailbox, you receive an access token that is valid for 7 days. Use this token in the Authorization header for all subsequent requests.

Getting Your Access Token

No pre-registration required! Simply call the mailbox creation endpoint and you’ll receive your mailbox address along with an access token.

curl -X POST /api/v1/mailbox \
-H "Content-Type: application/json"

Using Your Token

Include your token in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_TOKEN_HERE

Token Security

⚠️

Important:

Tokens are tied to specific mailboxes - you can only access the mailbox that was created with that token
Tokens expire after 7 days
Store tokens securely and never commit them to version control
Each mailbox creation generates a new token
Claiming a mailbox revokes its anonymous temporary API token

API v2: Permanent Mailboxes

Version 2 provisions mailboxes whose account lifetime never expires. The access token still expires after 24 hours and can be renewed with the mailbox password. Batch creation is administrator-only and atomic: either every requested mailbox is created or none is.

Batch Create Permanent Mailboxes

Create between 1 and 100 permanent mailboxes in one request. Set BATCH_ADMIN_TOKEN as a Worker secret and send it as a Bearer token. The generated passwords are returned only in this response, so store them securely.

curl -X POST /api/v2/mailboxes/batch \
-H "Authorization: Bearer ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"count":2,"domain":"example.com"}'

{
  "success": true,
  "batch": {
    "id": "f4e2c7b0-3c0f-4e5b-9f4d-9a1c2e6c2a10",
    "count": 2,
    "createdAt": "2026-08-03T12:00:00.000Z"
  },
  "mailboxes": [
    {
      "address": "mbx-7a9f@example.com",
      "password": "generated-password",
      "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "tokenType": "Bearer",
      "tokenExpiresIn": 86400,
      "accountExpiresAt": null
    },
    {
      "address": "mbx-91c2@example.com",
      "password": "another-generated-password",
      "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "tokenType": "Bearer",
      "tokenExpiresIn": 86400,
      "accountExpiresAt": null
    }
  ]
}

Renew a Mailbox Access Token

Exchange a permanent mailbox address and its password for a new 24-hour access token.

curl -X POST /api/v2/auth/token \
-H "Content-Type: application/json" \
-d '{"address":"mbx-7a9f@example.com","password":"generated-password"}'

The response contains accessToken, tokenType: "Bearer", expiresIn: 86400, and mailbox.accountExpiresAt: null.

Password login is throttled per Worker isolate and PBKDF2 verification is concurrency-limited. For public production traffic, configure Cloudflare WAF or Edge Rate Limiting as the global brute-force control; isolate-local throttling cannot share counters across regions.

Permanent Mailbox Emails

Use the access token returned by batch creation or login for all three mailbox-scoped routes:

Method	Route	Description
`GET`	`/api/v2/mailboxes/:address/emails`	List messages. Supports `limit` (1-100), `offset`, and `unread_only=true/false`.
`GET`	`/api/v2/mailboxes/:address/emails/:id`	Read one complete message, including text, HTML, and headers.
`DELETE`	`/api/v2/mailboxes/:address/emails/:id`	Delete one message from that mailbox.

Every request must include Authorization: Bearer MAILBOX_ACCESS_TOKEN. Email IDs are always checked against the path mailbox, so a valid token cannot read or delete another mailbox’s message.

curl -X GET \
"/api/v2/mailboxes/mbx-7a9f@example.com/emails?limit=20&unread_only=true" \
-H "Authorization: Bearer MAILBOX_ACCESS_TOKEN"

Error Response Format

Version 2 API errors use one stable JSON envelope. details is included for validation errors when the client needs field-level information.

{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The mailbox access token is invalid or expired"
  }
}

Common v2 error codes include AUTHENTICATION_REQUIRED, INVALID_ADMIN_TOKEN, INVALID_CREDENTIALS, INVALID_TOKEN, MAILBOX_FORBIDDEN, EMAIL_NOT_FOUND, MAILBOX_ADDRESS_CONFLICT, NOT_PERMANENT_MAILBOX, LOGIN_RATE_LIMITED, LOGIN_BUSY, PAYLOAD_TOO_LARGE, and VALIDATION_ERROR.

Create Temporary Mailbox

Generate a new temporary email address and receive an access token for it.

POST

/api/v1/mailbox

Request Body (Optional)

{
  "domain": "example.com"
}

Response (201 Created)

{
  "success": true,
  "mailbox": {
    "address": "random123@example.com",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": "7 days",
    "createdAt": "2025-10-03T12:00:00.000Z"
  }
}

List Emails

Retrieve all emails for a specific mailbox with optional pagination and filtering.

GET

/api/v1/mailbox/:address/emails

Headers

Authorization: Bearer YOUR_TOKEN_HERE

Query Parameters

limit (number, optional) - Number of emails to return (default: 50, max: 100)
offset (number, optional) - Offset for pagination (default: 0)
unread_only (boolean, optional) - Only return unread emails

Response (200 OK)

{
  "success": true,
  "emails": [
    {
      "id": "abc123",
      "from": {
        "address": "sender@example.com",
        "name": "Sender Name"
      },
      "to": [
        {
          "address": "random123@example.com",
          "name": ""
        }
      ],
      "subject": "Welcome!",
      "date": "2025-10-03T12:00:00.000Z",
      "createdAt": "2025-10-03T12:00:00.000Z",
      "isRead": false,
      "readAt": null,
      "priority": "normal",
      "textPreview": "This is a preview of the email content...",
      "hasHtml": true
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Get Email Details

Retrieve complete details of a specific email including full content and headers.

GET

/api/v1/mailbox/:address/emails/:id

Headers

Authorization: Bearer YOUR_TOKEN_HERE

Response (200 OK)

{
  "success": true,
  "email": {
    "id": "abc123",
    "from": {
      "address": "sender@example.com",
      "name": "Sender Name"
    },
    "to": [
      {
        "address": "random123@example.com",
        "name": ""
      }
    ],
    "subject": "Welcome!",
    "messageId": "<abc123@mail.example.com>",
    "date": "2025-10-03T12:00:00.000Z",
    "text": "Plain text content...",
    "html": "<html>HTML content...</html>",
    "headers": [
      {
        "Content-Type": "text/html; charset=utf-8"
      }
    ],
    "isRead": false,
    "priority": "normal"
  }
}

Delete Email

Delete a specific email from the mailbox.

DELETE

/api/v1/mailbox/:address/emails/:id

Headers

Authorization: Bearer YOUR_TOKEN_HERE

Response (200 OK)

{
  "success": true
}

Error Codes

The API uses standard HTTP status codes to indicate the success or failure of requests.

Status Code	Description
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing token
403	Forbidden - Token doesn’t match mailbox
404	Not Found - Resource doesn’t exist
500	Internal Server Error

Usage Examples

Node.js Example

const BASE_URL = '/api/v1';

// Step 1: Create a temporary mailbox and get access token
async function createMailbox() {
const response = await fetch(`${BASE_URL}/mailbox`, {
method: 'POST',
headers: {
'Content-Type': 'application/json'
}
});

const data = await response.json();
console.log('Mailbox created:', data.mailbox.address);
console.log('Token:', data.mailbox.token);
return data.mailbox;
}

// Step 2: Get emails for the mailbox using the token
async function getEmails(mailboxAddress, token) {
const response = await fetch(
`${BASE_URL}/mailbox/${mailboxAddress}/emails?limit=10`,
{
headers: {
'Authorization': `Bearer ${token}`
}
}
);

const data = await response.json();
console.log(`Found ${data.total} emails`);
return data.emails;
}

// Step 3: Get a specific email
async function getEmail(mailboxAddress, emailId, token) {
const response = await fetch(
`${BASE_URL}/mailbox/${mailboxAddress}/emails/${emailId}`,
{
headers: {
'Authorization': `Bearer ${token}`
}
}
);

const data = await response.json();
return data.email;
}

// Usage
(async () => {
const mailbox = await createMailbox();

// Wait for emails...
await new Promise(resolve => setTimeout(resolve, 5000));

const emails = await getEmails(mailbox.address, mailbox.token);
if (emails.length > 0) {
const fullEmail = await getEmail(mailbox.address, emails[0].id, mailbox.token);
console.log('Email content:', fullEmail.text);
}
})();

Python Example

import requests
import time

BASE_URL = '/api/v1'

# Step 1: Create a temporary mailbox and get access token

def create_mailbox():
response = requests.post(
f'{BASE_URL}/mailbox',
headers={'Content-Type': 'application/json'}
)
data = response.json()
print(f"Mailbox created: {data['mailbox']['address']}")
print(f"Token: {data['mailbox']['token']}")
return data['mailbox']

# Step 2: Get emails for the mailbox using the token

def get_emails(mailbox_address, token):
response = requests.get(
f'{BASE_URL}/mailbox/{mailbox_address}/emails',
headers={'Authorization': f'Bearer {token}'},
params={'limit': 10}
)
data = response.json()
print(f"Found {data['total']} emails")
return data['emails']

# Step 3: Get a specific email

def get_email(mailbox_address, email_id, token):
response = requests.get(
f'{BASE_URL}/mailbox/{mailbox_address}/emails/{email_id}',
headers={'Authorization': f'Bearer {token}'}
)
return response.json()['email']

# Usage

mailbox = create_mailbox()
time.sleep(5) # Wait for emails

emails = get_emails(mailbox['address'], mailbox['token'])
if emails:
full_email = get_email(mailbox['address'], emails[0]['id'], mailbox['token'])
print(f"Email content: {full_email['text']}")

cURL Examples

# Step 1: Create mailbox and get token
curl -X POST /api/v1/mailbox \
-H "Content-Type: application/json"

# Response will include:

# {

# "success": true,

# "mailbox": {

# "address": "random123@example.com",

# "token": "eyJhbGc...",

# "expiresIn": "7 days"

# }

# }

# Step 2: List emails (use the token from above)

curl -X GET /api/v1/mailbox/random123@example.com/emails \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

# Step 3: Get specific email

curl -X GET /api/v1/mailbox/random123@example.com/emails/abc123 \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

# Step 4: Delete email

curl -X DELETE /api/v1/mailbox/random123@example.com/emails/abc123 \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Typical Workflow

Step 1: Create a temporary mailbox - You’ll receive an email address and access token
Step 2: Use the mailbox address for signup/testing - Give this address to services that need to send you emails
Step 3: Poll for emails - Use the access token to check for new emails periodically
Step 4: Retrieve email content - Get the full content of emails you’re interested in
Step 5: Clean up - Delete emails or let the mailbox expire after 7 days

Best Practices

Store tokens securely: Never commit tokens to version control or expose them in client-side code
Use polling wisely: When waiting for emails, use reasonable intervals (e.g., 5-10 seconds) to avoid overloading the server
Handle token expiration: Tokens expire after 7 days - create a new mailbox if needed
Clean up: Delete emails when you’re done to save resources
Error handling: Always check the response status and handle errors appropriately
One token per mailbox: Each mailbox has its own token - you cannot use a token to access other mailboxes

Support

If you encounter any issues or have questions about the API, please contact us through the main website or consult the documentation.