Skip to content
destroy.network is now dissolve.email
Tutorials

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.

By dissolve.email team

7 min read

REST API request and TypeScript SDK code examples for creating disposable email addresses

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, share
  • dissolve.messages: list, get, search
  • dissolve.webhooks: register, list, manage event subscriptions
  • dissolve.labels: create and manage custom labels
  • dissolve.inboxRules: create and manage automation rules
  • dissolve.inboxTemplates: save and reuse inbox configurations
  • dissolve.teams: create teams, manage members, share inboxes
  • dissolve.agent: create AI agent identities with auto-verification
  • dissolve.apiKeys: generate and revoke keys
  • dissolve.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?

  1. Sign up for a Pro or Business plan
  2. Generate an API key from your dashboard
  3. Install the SDK: npm install @dissolve-email/sdk
  4. 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.

Generate an inbox