API Documentation
Test Emails provides a straightforward REST API that allows you to provision temporary email addresses and read incoming messages. All responses are returned in JSON format.
1. Create a New Mailbox
Creates a brand new temporary email address. No authentication required.
POST https://test-emails.com/hcgi/api/mailbox
// Response (200 OK)
{
"address": "random123@test-emails.com",
"password": "auto-generated-password",
"token": "eyJhbGc... (JWT token for reading messages)"
}2. Fetch Messages
Retrieve all emails sent to your temporary address. You must provide the JWT token obtained during mailbox creation in the x-mail-token header.
GET https://test-emails.com/hcgi/api/mailbox/messages
Headers:
x-mail-token: <your-token>
// Response (200 OK)
{
"messages": [
{
"id": "msg_12345",
"from": { "address": "no-reply@example.com", "name": "Example Support" },
"subject": "Verify your account",
"intro": "Your verification code is 123456",
"createdAt": "2026-08-11T12:00:00.000Z",
"seen": false
}
]
}3. Read a Specific Message
Get the full HTML or plain text body of an email.
GET https://test-emails.com/hcgi/api/mailbox/messages/:id
Headers:
x-mail-token: <your-token>
// Response (200 OK)
{
"id": "msg_12345",
"html": ["<html><body><p>Your verification code is 123456</p></body></html>"],
"text": "Your verification code is 123456",
"subject": "Verify your account"
}