API Reference

Complete REST API documentation for managing mailboxes and messages

Quick Start

The DevInbox API provides REST endpoints for creating temporary and persistent mailboxes, retrieving messages, and sending email from persistent inboxes. All API requests use HTTPS and return JSON responses. Perfect for integration testing and automated workflows.

Authentication

API Key Authentication

Include your API key in the X-Api-Key header of all requests:

curl -H "X-Api-Key: your_api_key_here" \
  https://api.devinbox.io/mailboxes

Find your API key in your dashboard under Settings ? API Keys

Base URL

https://api.devinbox.io

Status Endpoints

GET /status

Returns OK if the API service is running and available. This endpoint does not require authentication.

Response 200 OK

200 OK

Example

curl https://api.devinbox.io/status

Mailbox Endpoints

POST /mailboxes

Creates a new mailbox (temporary or persistent). Returns a unique mailbox key and password for SMTP authentication. Note: Persistent mailboxes can only be created via the web portal - API only supports temporary mailboxes.

Request Body

{
  "name": null,
  "projectName": "my-project",
  "isTemporary": true
}

Request Parameters

• name - Optional name for persistent mailboxes (API creates temporary only)
• projectName - Project to associate mailbox with (uses default if not specified)
• isTemporary - Must be true for API requests (default: true)

Response 200 OK

{
  "key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "password": "xyz789abcdef123456..."
}

The mailbox email address is: {key}@devinbox.io

Example

curl -X POST https://api.devinbox.io/mailboxes \
  -H "X-Api-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"projectName": "test-project", "isTemporary": true}'

Error Responses

• 400 - Project not found or persistent mailbox creation attempted
• 401 - Invalid or missing API key
• 429 - Rate limit exceeded

Message Endpoints

GET /messages/{key}/count

Returns the total number of messages in the specified mailbox.

Response 200 OK

{
  "key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "count": 3
}

Example

curl -H "X-Api-Key: your_api_key_here" \
  https://api.devinbox.io/messages/a1b2c3d4e5f6/count

GET /messages/{key}?skip=0&take=10

Retrieves messages from a mailbox with pagination support.

Query Parameters

• skip - Number of messages to skip (default: 0)
• take - Number of messages to return (default: 10, max: 25)

Response 200 OK

{
  "key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "count": 1,
  "messages": [
    {
      "uniqueId": "12345678-1234-1234-1234-123456789abc",
      "from": [ "noreply@example.com" ],
      "to": [ "a1b2c3d4@devinbox.io" ],
      "cc": null,
      "bcc": null,
      "subject": "Welcome to Our Service!",
      "body": "<h1>Welcome!</h1><p>Thank you for signing up...</p>",
      "isHtml": true,
      "received": "2024-01-15T10:35:00Z"
    }
  ]
}

Example

curl -H "X-Api-Key: your_api_key_here" \
  "https://api.devinbox.io/messages/a1b2c3d4e5f6?skip=0&take=5"

GET /messages/{key}/single

Returns the message when the mailbox contains exactly one message. Returns error if mailbox contains 0 or more than 1 message.

Response 200 OK

{
  "uniqueId": "12345678-1234-1234-1234-123456789abc",
  "from": [ "noreply@example.com" ],
  "to": [ "a1b2c3d4@devinbox.io" ],
  "cc": null,
  "bcc": null,
  "subject": "Welcome!",
  "body": "Thank you for registering...",
  "isHtml": false,
  "received": "2024-01-15T10:35:00Z"
}

Perfect for integration tests that expect exactly one email notification.

Example

curl -H "X-Api-Key: your_api_key_here" \
  https://api.devinbox.io/messages/a1b2c3d4e5f6/single

GET /messages/{key}/last

Returns the most recent message from the mailbox. Returns error if mailbox is empty.

Example

curl -H "X-Api-Key: your_api_key_here" \
  https://api.devinbox.io/messages/a1b2c3d4e5f6/last

GET /messages/{key}/get?id={guid}

Retrieves a specific message from the specified mailbox using its unique ID.

Query Parameters

• id - The unique GUID of the message

Example

curl -H "X-Api-Key: your_api_key_here" \
  "https://api.devinbox.io/messages/a1b2c3d4e5f6/get?id=12345678-1234-1234-1234-123456789abc"

Sending Email

Every persistent inbox can send email as well as receive it. Agents send as themselves, from their own {key}@devinbox.io address, over SPF/DKIM-authenticated infrastructure so receiving servers can verify the mail genuinely came from your inbox. Sending is available on persistent inboxes only.

POST /messages/{key}/send

Sends an email from the persistent inbox identified by {key}. The API key must hold the send scope. The From address is always the inbox's own address, {key}@devinbox.io.

Request Body

{
  "to": [ "customer@example.com" ],
  "cc": null,
  "bcc": null,
  "subject": "Re: Your order #1024",
  "text": "Thanks - your order is confirmed.",
  "html": "<p>Thanks - your order is confirmed.</p>",
  "inReplyTo": "12345678-1234-1234-1234-123456789abc"
}

Request Parameters

• to - Array of recipient addresses (required)
• cc - Optional array of CC addresses
• bcc - Optional array of BCC addresses. to, cc and bcc combined may not exceed 50 recipients
• subject - Message subject
• text / html - Message body; provide text, html, or both
• inReplyTo - Optional. The uniqueId of a message previously received in this inbox. Sets real In-Reply-To / References headers so your reply lands in the recipient's existing thread

Example

curl -X POST https://api.devinbox.io/messages/a1b2c3d4e5f6/send \
  -H "X-Api-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"to": ["customer@example.com"], "subject": "Re: Your order #1024", "text": "Thanks - your order is confirmed.", "inReplyTo": "12345678-1234-1234-1234-123456789abc"}'

Reply-only on the free plan is deliberate. Free API keys can send, but every send must reference a received message via inReplyTo - agents can hold a conversation but can't cold-email strangers. It keeps free-tier sending clean and protects deliverability for everyone. Cold outbound (sending without inReplyTo) unlocks on the Developer plan and above.

Error Responses

• 400 - Invalid recipients, more than 50 combined, or a required field is missing
• 401 - Invalid or missing API key
• 403 - API key lacks the send scope, or a free-plan send omitted inReplyTo
• 429 - Monthly send limit reached

Template Verification

Template verification allows you to validate that emails match expected patterns and extract structured data from them. Templates must be created in your project before using these endpoints.

GET /messages/{key}/{template}/single

Returns the single message and parses it using the specified template. The mailbox must contain exactly one message. The response includes the original message data plus parsed template parameters.

Response 200 OK

{
  "uniqueId": "12345678-1234-1234-1234-123456789abc",
  "from": [ "noreply@example.com" ],
  "to": [ "user123@devinbox.io" ],
  "cc": null,
  "bcc": null,
  "subject": "Welcome to DevInbox, John Smith!",
  "body": "<h1>Welcome John!</h1><p>Your verification code is ABC123</p>",
  "isHtml": true,
  "received": "2024-01-15T10:35:00Z",
  "templateData": {
    "subjectParams": {
      "UserName": "John Smith",
      "ProductName": "DevInbox"
    },
    "bodyParams": {
      "FirstName": "John",
      "VerificationCode": "ABC123",
      "CompanyName": "Acme Corp"
    },
    "templateName": "welcome-email",
    "matchSuccess": true
  }
}

The templateData object contains the extracted parameters from both subject and body, plus metadata about the template matching process.

Template Match Failure Response

{
  "uniqueId": "12345678-1234-1234-1234-123456789abc",
  "from": [ "noreply@example.com" ],
  "to": [ "user123@devinbox.io" ],
  "subject": "Unexpected email format",
  "body": "This email doesn't match the template",
  "isHtml": false,
  "received": "2024-01-15T10:35:00Z",
  "templateData": {
    "subjectParams": null,
    "bodyParams": null,
    "templateName": "welcome-email",
    "matchSuccess": false,
    "matchFailureReason": "Subject pattern did not match template"
  }
}

Example

curl -H "X-Api-Key: your_api_key_here" \
  https://api.devinbox.io/messages/a1b2c3d4e5f6/welcome-email/single

GET /messages/{key}/{template}/last

Returns the most recent message and parses it using the specified template. Response format is identical to the single message endpoint above.

Common Use Cases

# Get password reset email and extract reset token
curl -H "X-Api-Key: your_key" \
  https://api.devinbox.io/messages/a1b2c3d4e5f6/password-reset/last

# Verify welcome email contains correct user data
curl -H "X-Api-Key: your_key" \
  https://api.devinbox.io/messages/a1b2c3d4e5f6/user-registration/single

# Extract order details from confirmation email
curl -H "X-Api-Key: your_key" \
  https://api.devinbox.io/messages/a1b2c3d4e5f6/order-confirmation/last

Template Parameter Extraction

Templates use named capture groups to extract parameters:

• Subject Template: Welcome to (?<ProductName>.*), (?<UserName>.*)!
• Body Template: Hello (?<FirstName>.*?).*code is (?<VerificationCode>\w+)
• Extracted Data: Parameters become key-value pairs in templateData

Error Handling

HTTP Status Codes

• 200 OK - Request succeeded
• 400 Bad Request - Invalid request parameters, template not found, or mailbox constraints not met
• 401 Unauthorized - Invalid or missing API key
• 403 Forbidden - Access denied to resource or tenant mismatch
• 404 Not Found - Mailbox or message not found
• 429 Too Many Requests - Rate limit exceeded

Error Response Example

{
  "error": "Rate limit exceeded",
  "message": "Monthly mailbox creation limit reached",
  "retryAfter": "60"
}

Common Error Messages

• Template 'template-name' not found or you don't have access to it
• Mailbox 'key' contains X messages (for /single endpoint)
• Mailbox 'key' doesn't contain messages (for /last endpoint)
• Project 'project-name' not found
• Creation of persistent mailboxes via API is not supported
• Template verification failed: message does not match template pattern
• Invalid template format: missing required capture groups

Rate Limits

Rate Limit Headers

The API includes rate limit information in response headers:

• X-RateLimit-Remaining - Operations remaining
• X-RateLimit-Limit-Type - Type of limit (Monthly, Daily)

Operation Types

• MailboxCreated - Creating new mailboxes via POST /mailboxes
• MessageVerified - Template verification endpoints (/template/single, /template/last)
• ApiCall - All other message retrieval operations

Plan Limits

Plan	Mailboxes/Month	Verifications/Month
Developer (Free)	500	1,000
Team	5,000	10,000
Business	25,000	50,000
Enterprise	100,000	200,000

Code Examples

import requests
import time

API_KEY = "your_api_key"
BASE_URL = "https://api.devinbox.io"
headers = {"X-Api-Key": API_KEY}

# Create temporary mailbox
response = requests.post(
    f"{BASE_URL}/mailboxes",
    headers=headers,
    json={"isTemporary": True})
mailbox = response.json()
email_address = f"{mailbox['key']}@devinbox.io"

# Wait for email and get single message
time.sleep(5)  # Wait for email delivery
response = requests.get(
    f"{BASE_URL}/messages/{mailbox['key']}/single",
    headers=headers)
message = response.json()
print(f"Subject: {message['subject']}")

# Get message with template verification
template_response = requests.get(
    f"{BASE_URL}/messages/{mailbox['key']}/welcome-email/single",
    headers=headers)
template_message = template_response.json()

# Extract and validate template parameters
if template_message['templateData']['matchSuccess']:
    user_name = template_message['templateData']['subjectParams']['UserName']
    verification_code = template_message['templateData']['bodyParams']['VerificationCode']
    print(f"Template matched! User: {user_name}, Code: {verification_code}")
else:
    print(f"Template match failed: {template_message['templateData']['matchFailureReason']}")

const API_KEY = 'your_api_key';
const BASE_URL = 'https://api.devinbox.io';
const headers = { 'X-Api-Key': API_KEY };

// Create temporary mailbox
const response = await fetch(`${BASE_URL}/mailboxes`, {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({ isTemporary: true })
});
const mailbox = await response.json();
const emailAddress = `${mailbox.key}@devinbox.io`;

// Check message count
const countResponse = await fetch(
    `${BASE_URL}/messages/${mailbox.key}/count`,
    { headers }
);
const count = await countResponse.json();
console.log(`Messages: ${count.count}`);

// Get message with template verification
const templateResponse = await fetch(
    `${BASE_URL}/messages/${mailbox.key}/welcome-email/single`,
    { headers }
);
const message = await templateResponse.json();

// Extract template parameters
if (message.templateData.matchSuccess) {
    const userName = message.templateData.subjectParams.UserName;
    const verificationCode = message.templateData.bodyParams.VerificationCode;
    console.log(`User: ${userName}, Code: ${verificationCode}`);
}

import { Configuration, MailboxesApi, MessagesApi } from '@dev-inbox/client-api';

const configuration = new Configuration({
    basePath: 'https://api.devinbox.io',
    baseOptions: {
        headers: { 'X-API-Key': 'your_api_key' }
    }
});
const mailboxesApi = new MailboxesApi(configuration);
const messagesApi = new MessagesApi(configuration);

// Create temporary mailbox
const mailboxResponse = await mailboxesApi.createMailbox({ isTemporary: true });
const mailbox = mailboxResponse.data;
const emailAddress = `${mailbox.key}@devinbox.io`;

// Check message count
const countResponse = await messagesApi.getMessageCount(mailbox.key);
const count = countResponse.data;
console.log(`Messages: ${count.count}`);

// Get message with template verification
const templateResponse = await messagesApi.getSingleMessageWithTemplate(
    mailbox.key,
    'welcome-email'
);
const message = templateResponse.data;

// Extract template parameters
const subject = message.subject as Record<string, string>;
const body = message.body as Record<string, string>;
if (subject && body) {
    const userName = subject.UserName;
    const verificationCode = body.VerificationCode;
    console.log(`User: ${userName}, Code: ${verificationCode}`);
}

using System.Net.Http;
using System.Text;
using System.Text.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "your_api_key");
var baseUrl = "https://api.devinbox.io";

// Create temporary mailbox
var createRequest = new { isTemporary = true };
var json = JsonSerializer.Serialize(createRequest);
var content = new StringContent(json, Encoding.UTF8, "application/json");

var response = await client.PostAsync($"{baseUrl}/mailboxes", content);
var mailboxJson = await response.Content.ReadAsStringAsync();
var mailbox = JsonSerializer.Deserialize<dynamic>(mailboxJson);

// Get last message
var messageResponse = await client.GetAsync(
    $"{baseUrl}/messages/{mailbox.key}/last");
var messageJson = await messageResponse.Content.ReadAsStringAsync();

# Create mailbox
MAILBOX=$(curl -s -X POST https://api.devinbox.io/mailboxes \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"isTemporary": true}')

# Extract key from response
KEY=$(echo $MAILBOX | jq -r '.key')

# Check message count
curl -H "X-Api-Key: your_api_key" \
  https://api.devinbox.io/messages/$KEY/count

# Get all messages
curl -H "X-Api-Key: your_api_key" \
  https://api.devinbox.io/messages/$KEY

# Get single message (when exactly 1 exists)
curl -H "X-Api-Key: your_api_key" \
  https://api.devinbox.io/messages/$KEY/single

# Get last message with template parsing
curl -H "X-Api-Key: your_api_key" \
  https://api.devinbox.io/messages/$KEY/welcome-template/last

GitHub Repositories

Explore our open-source SDKs and contribute to the DevInbox ecosystem on GitHub.

DevInbox Organization

Browse all DevInbox repositories and SDKs on GitHub.

.NET SDK

C# client library for the DevInbox API.

Python SDK

Complete Python client generated from OpenAPI specification.

Node.js SDK

TypeScript/JavaScript SDK for managing test mailboxes.

Java SDK

Java client library for DevInbox API integration.

What's Next?

Developer Guide →

Step-by-step guide for integrating DevInbox into your testing workflow.

Email Templates →

Learn how to create and use email templates for verification.