Temp Mail API for Developers: Disposable Email REST API Guide
A complete guide to creating and managing disposable email addresses via the dissolve.email API. Includes examples in TypeScript, cURL, and Python for CI/CD testing, signup automation, and webhook integrations.
7 min read
If you're building an app that sends emails (signup confirmations, password resets, notifications), you need a reliable way to test those flows without using real inboxes. The dissolve.email API lets you create temporary email addresses on demand, receive real emails, and read them programmatically. No SMTP server to configure, no shared test inbox that fills up with junk.
This guide walks through every step: authentication, creating inboxes, reading messages, setting up webhooks, and cleaning up. All examples are verified against the live API.
Authentication
Every API request requires an API key passed as a Bearer token. Generate one from your API dashboard. Pro plans get up to 5 keys, Business plans get 10.
API keys use the format sk_live_... and are scoped to your account. Rate limits depend on your plan: Pro allows 100 requests per minute, Business allows 1,000.
Creating Inboxes
A single POST request creates a fully functional email inbox. On Pro plans, you can choose a custom name. Free-tier inboxes get a random address.
TypeScript SDK
// create-inbox.ts
import { Dissolve } from "@dissolve-email/sdk";
const dissolve = new Dissolve({ apiKey: process.env.DISSOLVE_API_KEY });
// Create a temporary inbox with a custom name
const inbox = await dissolve.inboxes.create({
name: "signup-test",
domain: "dissolve.email",
});
console.log(inbox.address); // "signup-test@dissolve.email"
console.log(inbox.id); // "inb_Kp9xMn..."
console.log(inbox.expiresAt); // ISO timestamp
cURL
# Create an inbox
curl -X POST https://api.dissolve.email/api/inbox \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"name": "test-inbox", "domain": "dissolve.email"}'
# Response:
# {
# "id": "inb_Kp9xMn2q...",
# "address": "test-inbox@dissolve.email",
# "expiresAt": "2026-02-27T12:30:00Z"
# }
Inbox lifetime depends on your plan: 10 minutes on Free, 30 on Pro, 60 on Business. Pro and Business plans can extend inboxes indefinitely in 30- or 60-minute increments.
Reading Messages
Once your inbox is live, any email sent to that address is stored and available via the API. Messages include the sender, subject, plain text body, HTML body, and any attachments.
TypeScript SDK
// read-messages.ts
// List messages in the inbox
const messages = await dissolve.messages.list(inbox.id);
for (const msg of messages) {
console.log(msg.from); // "noreply@github.com"
console.log(msg.subject); // "Verify your email address"
console.log(msg.snippet); // First 200 chars of body
}
// Get the full message content
const full = await dissolve.messages.get(inbox.id, messages[0].id);
console.log(full.text); // Plain text body
console.log(full.html); // Full HTML body
cURL
# List messages
curl https://api.dissolve.email/api/inbox/inb_Kp9xMn2q/messages \
-H "Authorization: Bearer sk_live_your_key"
# Get a specific message
curl https://api.dissolve.email/api/inbox/inb_Kp9xMn2q/messages/msg_abc123 \
-H "Authorization: Bearer sk_live_your_key"
Pro and Business plans get real-time delivery via Server-Sent Events (SSE), so you can stream messages as they arrive instead of polling. Free-tier users can poll at 60-second intervals.
Webhooks for Real-Time Events
Instead of polling for new messages, you can register a webhook URL and get notified the instant an email lands. Webhooks are available on Pro and Business plans.
// setup-webhook.ts
// Register a webhook to get notified when emails arrive
const webhook = await dissolve.webhooks.create({
url: "https://your-app.com/webhooks/email",
events: ["message.received"],
inboxId: inbox.id, // scope to a specific inbox
});
// Your webhook endpoint receives:
// {
// "event": "message.received",
// "data": {
// "inboxId": "inb_Kp9xMn2q...",
// "messageId": "msg_abc123",
// "from": "noreply@github.com",
// "subject": "Verify your email"
// }
// }
Webhooks fire for three event types: message.received, inbox.created, and inbox.expired. Each payload includes a signing secret for verification, and failed deliveries are retried automatically.
Python Example
The API is plain HTTP, so it works with any language. Here's the same flow in Python using requests:
# test_email.py
import requests
API_URL = "https://api.dissolve.email/api"
headers = {"Authorization": "Bearer sk_live_your_key"}
# Create inbox
inbox = requests.post(f"{API_URL}/inbox", headers=headers, json={
"name": "python-test",
"domain": "dissolve.email"
}).json()
print(f"Email: {inbox['address']}")
# Poll for messages
import time
for _ in range(30):
msgs = requests.get(
f"{API_URL}/inbox/{inbox['id']}/messages",
headers=headers
).json()
if msgs:
print(f"Got email: {msgs[0]['subject']}")
break
time.sleep(1)
CI/CD Integration
The API is designed for automated testing pipelines. Here's how to integrate it into your CI/CD workflow:
- Per-test isolation: create a new inbox for each test case, so there's no state leakage between runs
- No shared credentials: each API key is scoped to your account, no shared test email passwords to rotate
- Automatic cleanup: inboxes expire on their own, so your test environment never fills up with stale data
- Attachments supported: test attachment handling with up to 5 MB (Free), 25 MB (Pro), or 50 MB (Business) per message
Full SDK Resource List
The TypeScript SDK provides typed methods for every API endpoint:
dissolve.inboxes: create, list, update, delete, sharedissolve.messages: list, get, searchdissolve.webhooks: register, list, manage event subscriptionsdissolve.labels: create and manage custom labelsdissolve.inboxRules: create and manage automation rulesdissolve.inboxTemplates: save and reuse inbox configurationsdissolve.teams: create teams, manage members, share inboxesdissolve.agent: create AI agent identities with auto-verificationdissolve.apiKeys: generate and revoke keysdissolve.user: account info and usage stats
Install with npm install @dissolve-email/sdk and see the full documentation for every method signature.
Rate Limits and Quotas
API limits are enforced per-key per-minute. If you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header.
- Free: no API access
- Pro: 100 requests/minute, 10 concurrent inboxes, 5 API keys
- Business: 1,000 requests/minute, 50 concurrent inboxes, 10 API keys
Get Started
Ready to integrate disposable email into your project?
- Sign up for a Pro or Business plan
- Generate an API key from your dashboard
- Install the SDK:
npm install @dissolve-email/sdk - Read the API documentation for the full endpoint reference
Or jump straight in and create a free inbox to see it work.
Try it while you read
A disposable inbox takes one press on the home page. No signup.
Keep reading
Product updates
Inbox Rules: Automate Email Forwarding, Labels, and Filtering
Automate your disposable inbox with rules that forward emails to your personal address, apply custom labels, or auto-delete spam. Configure up to 50 rules per account with regex pattern matching.
6 min read
Product updates
AI Agent Identities: Automate Signups for Cursor & AI Tools
Instantly create temporary email + password identity pairs for your AI agents. Automate signup flows, extract verification codes, and let Cursor, Claude, or any AI tool operate independently. No human inbox needed.
9 min read
Tutorials
Testing Email Flows with Playwright and Temporary Inboxes
Automate your email verification tests with Playwright and temporary inboxes. Perfect for testing signups, password resets, and transactional emails.
8 min read