logo-icon-dark logo-icon-light
Get Started

API Reference

Complete REST API documentation for managing mailboxes and messages

Quick Start

The DevInbox API provides REST endpoints for creating temporary mailboxes and retrieving messages. 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

Mailbox Endpoints

POST /mailboxes

Creates a new temporary mailbox. Returns a unique mailbox key and password for SMTP authentication.

Request Body

{
  "name": null,
  "projectName": null,
  "isTemporary": true
}

Response 200 OK

{
  "key": "a1b2c3d4e5f6",
  "password": "xyz789..."
}

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 '{}'

Message Endpoints

GET /messages/{'{key}'}/count

Returns the total number of messages in the specified mailbox.

Response 200 OK

{
  "key": "a1b2c3d4e5f6",
  "count": 3
}
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": "a1b2c3d4e5f6",
  "count": 1,
  "messages": [
    {
      "uniqueId": "guid-here",
      "from": [ "noreply@app.com" ],
      "to": [ "a1b2c3d4@devinbox.io" ],
      "subject": "Welcome!",
      "body": "Email body...",
      "isHtml": true,
      "received": "2024-01-15T10:35:00Z"
    }
  ]
}
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.

Perfect for integration tests that expect exactly one email notification.

GET /messages/{'{key}'}/last

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

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

Retrieves a specific message by its unique ID.

Query Parameters

  • • id - The unique GUID of the message

Template Verification

Template verification allows you to validate that emails match expected patterns and extract structured data from them.

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

Returns the single message and parses it using the specified template. The mailbox must contain exactly one message.

Response 200 OK

{
  "uniqueId": "guid-here",
  "from": [ "noreply@app.com" ],
  "to": [ "a1b2c3d4@devinbox.io" ],
  "subject": {
    "recipientName": "John Smith"
  },
  "body": {
    "verificationCode": "ABC123",
    "companyName": "Acme Corp"
  },
  "isHtml": true,
  "received": "2024-01-15T10:35:00Z"
}

The subject and body fields contain parsed template parameters instead of raw text.

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

Returns the most recent message and parses it using the specified template.

Example Use Case

 Get last "welcome" email and extract data
curl -H "X-Api-Key: your_key" \
  https://api.devinbox.io/messages/a1b2c3/user-welcome/last

Error Handling

HTTP Status Codes

  • • 200 OK - Request succeeded
  • • 400 Bad Request - Invalid request parameters
  • • 401 Unauthorized - Invalid or missing API key
  • • 403 Forbidden - Access denied to resource
  • • 404 Not Found - Resource not found
  • • 429 Too Many Requests - Rate limit exceeded

Error Response Example

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

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)

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

Python

import requests
API_KEY = "your_api_key"
headers = {"X-Api-Key": API_KEY}
 Create mailbox
r = requests.post(
    "https://api.devinbox.io/mailboxes",
    headers=headers, json={})
mailbox = r.json()
 Get messages
r = requests.get(
    f"https://api.devinbox.io/messages/{mailbox['key']}",
    headers=headers)
messages = r.json()

JavaScript

const API_KEY = 'your_api_key';
const headers = { 'X-Api-Key': API_KEY };
 Create mailbox
const res = await fetch(
    'https://api.devinbox.io/mailboxes',
    { method: 'POST', headers })
const mailbox = await res.json();
 Get messages
const msgs = await fetch(
    `https://api.devinbox.io/messages/${mailbox.key}`,
    { headers })
const messages = await msgs.json();

C#

var client = new HttpClient();
client.DefaultRequestHeaders.Add(
    "X-Api-Key", "your_api_key");
 Create mailbox
var response = await client.PostAsync(
    "https://api.devinbox.io/mailboxes",
    new StringContent("{}", 
        Encoding.UTF8, 
        "application/json"));
var mailbox = await response
    .Content.ReadAsStringAsync();

Go

client := &http.Client{}
req, _ := http.NewRequest("POST",
    "https://api.devinbox.io/mailboxes",
    bytes.NewBuffer([]byte("{}")))
req.Header.Set("X-Api-Key", 
    "your_api_key")
resp, err := client.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)

Next Steps

Ready to integrate DevInbox into your testing workflow? Check out our guides and examples.

Integration Testing Email Templates Developer Guide