Developer API

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.

Authentication

Every developer API request must carry an API KEY: preferably in the X-API-Key header; on endpoints that do not need a mailbox token it may also be sent as the Bearer token. Missing or invalid keys return 401.

Besides the API KEY, reading mail also requires mailbox credentials:

• Temporary mailboxes (v1): the access token returned at creation (valid for 7 days), sent in the Authorization: Bearer header.
• Permanent mailboxes (v2): mailboxes generated by an API KEY are read directly with that KEY (the key is the proof of ownership); legacy claimed mailboxes can still exchange their password for a 24-hour access token.

Getting Your Access Token

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

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

Carrying Credentials

Subsequent requests carry the API KEY together with the mailbox token:

X-API-Key: YOUR_API_KEY
Authorization: Bearer YOUR_TOKEN_HERE

Token Security

API v2: Permanent Mailboxes

Version 2 provisions permanent mailboxes whose account lifetime never expires. Permanent mailboxes can only be created with an API KEY, and the KEY itself is the ownership credential - generated mailboxes have no password. Batch creation is atomic: either every requested mailbox is created or none is. Mail in a permanent mailbox is kept for 24 hours.

Batch Create Permanent Mailboxes

Create between 1 and 100 permanent mailboxes in one request. Send your API KEY in the X-API-Key header. Created mailboxes are bound to that KEY and count against its mailbox limit.

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

Request parameters (all optional): count (1-100, default 1), idLength (8-32, default 8) for the random local-part length, domain (defaults to the first supported domain), and prefix to create one mailbox with a custom local part instead of random addresses.

{
  "success": true,
  "mailboxes": [
    {
      "address": "a1b2c3d4@example.com"
    },
    {
      "address": "e5f6a7b8@example.com"
    }
  ],
  "used": 2,
  "limit": 100
}

used and limit report the KEY’s mailbox quota after this batch. A custom prefix that is already taken returns 409 MAILBOX_EXISTS, and a batch that exceeds the quota returns 409 QUOTA_EXCEEDED.

Renew a Legacy Claimed Mailbox Access Token

Mailboxes claimed by a user with a password (legacy flow) can exchange their address and password for a new 24-hour access token. KEY-generated permanent mailboxes have no password and do not use this endpoint - the API KEY is sufficient.

curl -X POST /api/v2/auth/token \
-H "Content-Type: application/json" \
-d '{"address":"mbx-7a9f@example.com","password":"your-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

The three mailbox-scoped routes below require the X-API-Key of a KEY that owns the address (or a legacy access token for claimed mailboxes):

Every request must include X-API-Key: YOUR_API_KEY. Email IDs are always checked against the path mailbox, so a valid KEY cannot read or delete another mailbox’s message. Mail older than 24 hours is no longer returned and is deleted automatically.

curl -X GET \
"/api/v2/mailboxes/a1b2c3d4@example.com/emails?limit=20&unread_only=true" \
-H "X-API-Key: YOUR_API_KEY"

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 MISSING_API_KEY, INVALID_API_KEY, AUTHENTICATION_REQUIRED, INVALID_CREDENTIALS, INVALID_TOKEN, MAILBOX_FORBIDDEN, EMAIL_NOT_FOUND, NOT_PERMANENT_MAILBOX, QUOTA_EXCEEDED, MAILBOX_EXISTS, 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. Requires an API KEY. Mail in a temporary mailbox is kept for 1 hour, then deleted automatically.

X-API-Key: YOUR_API_KEY

{
  "domain": "example.com"
}

{
  "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.

X-API-Key: YOUR_API_KEY
Authorization: Bearer YOUR_TOKEN_HERE

{
  "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.

X-API-Key: YOUR_API_KEY
Authorization: Bearer YOUR_TOKEN_HERE

{
  "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.

X-API-Key: YOUR_API_KEY
Authorization: Bearer YOUR_TOKEN_HERE

{
  "success": true
}

Error Codes

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

Usage Examples

Node.js Example

const BASE_URL = '/api/v1';
const API_KEY = process.env.VMAIL_API_KEY;

// Step 1: Create a temporary mailbox and get access token
async function createMailbox() {
const response = await fetch(`${BASE_URL}/mailbox`, {
method: 'POST',
headers: {
'X-API-Key': API_KEY,
'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: {
'X-API-Key': API_KEY,
'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: {
'X-API-Key': API_KEY,
'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 os
import requests
import time

BASE_URL = '/api/v1'
API_KEY = os.environ['VMAIL_API_KEY']

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

def create_mailbox():
response = requests.post(
f'{BASE_URL}/mailbox',
headers={'X-API-Key': API_KEY, '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={'X-API-Key': API_KEY, '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={'X-API-Key': API_KEY, '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 (API KEY required)
curl -X POST /api/v1/mailbox \
-H "X-API-Key: YOUR_API_KEY" \
-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 "X-API-Key: YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

# Step 3: Get specific email

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

# Step 4: Delete email

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

Typical Workflow

1. Step 1: Obtain an API KEY - contact the administrator to issue one in the admin panel
2. Step 2: Create a temporary mailbox - with the API KEY you’ll receive an email address and access token
3. Step 3: Use the mailbox address for signup/testing - Give this address to services that need to send you emails
4. Step 4: Poll for emails - carry the API KEY and access token and check periodically (note: temporary mailbox mail is deleted automatically after 1 hour, so retrieve it in time)
5. Step 5: Retrieve email content - Get the full content of emails you’re interested in

Best Practices

• Store the API KEY securely: the API KEY is a required credential on every endpoint - never commit it to version control or expose it in client-side code
• Use polling wisely: When waiting for emails, use reasonable intervals (e.g., 5-10 seconds) to avoid overloading the server
• Retrieve mail in time: temporary mailbox mail is kept for 1 hour and permanent mailbox mail for 24 hours, then deleted automatically
• Handle token expiration: access tokens expire after 7 days - create a new mailbox if needed
• 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.