For developers

Temporary email API

Create inboxes and read messages from code: for sign-up autotests, checking mailings and email confirmations.

Authentication

Every request is signed with a key in the Authorization header. Keys are issued on paid plans.

Authorization: Bearer um_YOUR_KEY

Base URL

https://urusmail.pro/api/v1

Quick start

Create an inbox
Wait for a message (the request itself waits up to 30 seconds)
Read the message: text, verification code and links

# 1. create an inbox
curl -X POST https://urusmail.pro/api/v1/inboxes \
  -H "Authorization: Bearer um_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl_minutes": 60}'
# -> {"inbox":{"id":123,"email":"swift.fox1234@urusmail.pro","expires_at":"..."}}

# 2. wait for a message (up to 30 s)
curl "https://urusmail.pro/api/v1/inboxes/123/messages?wait=30" \
  -H "Authorization: Bearer um_YOUR_KEY"
# -> {"messages":[{"id":456,"subject":"Your code","code":"482910", ...}]}

# 3. read the full message
curl https://urusmail.pro/api/v1/inboxes/123/messages/456 \
  -H "Authorization: Bearer um_YOUR_KEY"

const API = "https://urusmail.pro/api/v1";
const headers = { Authorization: "Bearer " + process.env.URUSMAIL_KEY, "Content-Type": "application/json" };

// create an inbox for one test
const { inbox } = await (await fetch(API + "/inboxes", { method: "POST", headers, body: JSON.stringify({ ttl_minutes: 30 }) })).json();

// ... your app sends a confirmation email to inbox.email ...

// wait for the email and take the code
let code = null;
for (let i = 0; i < 4 && !code; i++) {
  const { messages } = await (await fetch(`${API}/inboxes/${inbox.id}/messages?wait=30`, { headers })).json();
  code = messages[0]?.code ?? null;
}
console.log(inbox.email, code);

await fetch(`${API}/inboxes/${inbox.id}`, { method: "DELETE", headers });

Endpoints

GET	/me	Plan, limits and current usage
GET	/domains	Domains you can create inboxes on
POST	/inboxes	Create an inbox. Body: name, domain, ttl_minutes (all optional)
GET	/inboxes	List your inboxes
GET	/inboxes/{id}	A single inbox
DELETE	/inboxes/{id}	Delete an inbox with its messages
GET	/messages	All messages of the account in one list. Parameters: inbox_id, since_id, limit (up to 100)
GET	/inboxes/{id}/messages	Messages in an inbox. Parameters: since_id, wait (0–30 seconds)
GET	/inboxes/{id}/messages/{mid}	Full message: text, html, code, links
DELETE	/inboxes/{id}/messages/{mid}	Delete a message
GET	/custom-domains	Your domains and the DNS records they need
POST	/custom-domains	Add a domain. Body: domain, catch_all
POST	/custom-domains/{id}/verify	Check DNS records and enable mail reception
PATCH	/custom-domains/{id}	Turn catch_all on or off
DELETE	/custom-domains/{id}	Delete a domain and its inboxes

What a message contains

code	The verification code if found next to words like "code" or "verification"; otherwise null
text	Message text. For HTML-only emails the text is built from the HTML without styles
html	The original HTML (render it only inside a sandboxed frame)
links	Links from the message, up to 50

Custom domain

Add a domain with POST /custom-domains. The response contains two DNS records.
At your registrar, create the TXT record with the verification code and an MX record pointing to mail.urusmail.pro.
Call /verify. Once both records are found, the domain appears in GET /domains and you can create inboxes on it.
With catch_all, an email to any address on the domain creates an inbox by itself, if your plan allows.

Errors and limits

401	Missing or invalid key
403	The key is disabled or expired
404	Inbox, message or domain not found (or not yours)
409	Plan limit reached or the address is taken
429	Per-minute request limit exceeded. Retry later (Retry-After header)

Errors always have the same shape:

{ "error": { "code": "inbox_limit", "message": "Inbox limit reached (10). Delete an inbox or upgrade the plan" } }

At most three requests per key can wait for a message at the same time. An inbox keeps the last 200 messages.

Pricing and getting a key