Начало работы с API DustMail

The DustMail API lets you programmatically create temporary email addresses and receive emails. This is perfect for automated testing, CI/CD pipelines, and building privacy-focused applications. This guide walks through every endpoint with copy-pasteable examples in cURL, Node.js, and Python so you can be up and running in under five minutes.

Authentication

All API requests require an API key. Generate one from your Dashboard, then pass it via theAuthorization header:

Authorization: Bearer dm_live_your_api_key

Alternatively, the same key can be sent in X-API-Keyif your HTTP client prefers a custom header. Keys are shown to you once at creation time and stored as a SHA-256 hash on our side - if you lose a key, you'll need to rotate to a new one.

Creating an Inbox

Send a POST request to create a new temporary email address:

POST https://dustmail.net/api/v1/inbox

You can optionally specify a custom username in the request body if your API key belongs to a Premium account. Premium keys can also choose from the configured inbox domains. Otherwise, a random address like[email protected] will be generated on the default domain.

cURL example

curl -X POST https://dustmail.net/api/v1/inbox \
  -H "Authorization: Bearer dm_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"duration": 30}'

Node.js example

const res = await fetch('https://dustmail.net/api/v1/inbox', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${process.env.DUSTMAIL_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ duration: 30 }),
});
const inbox = await res.json();

Python example

import os, requests
r = requests.post(
  'https://dustmail.net/api/v1/inbox',
  headers={'Authorization': f'Bearer {os.environ["DUSTMAIL_KEY"]}'},
  json={'duration': 30},
)
inbox = r.json()

Polling for Emails

After creating an inbox, poll the inbox endpoint to check for new emails:

GET https://dustmail.net/api/v1/inbox/YOUR_INBOX_ID

The response includes both text and HTML versions of each email, along with sender information and timestamps. Polling every 5-10 seconds is a good balance between responsiveness and rate limit usage.

For long-running tests, use exponential backoff after the first miss: poll every 2 seconds for the first 30 seconds, then every 5 seconds, then every 15 seconds. This catches fast deliveries quickly while not burning rate limit on slow ones.

Listing and Cleaning Up Inboxes

Use GET /api/v1/inbox to list all active inboxes belonging to your API key, and DELETE /api/v1/inbox/{id} to deactivate one early. In an automated test suite, the recommended pattern is: create the inbox in a setup hook, keep its ID in test scope, and delete it in a teardown hook. This keeps your active inbox count low and avoids hitting the daily creation limit.

Rate Limits

Free accounts get 100 API calls per day. This is enough for light testing and personal projects. Premium accounts get unlimited API calls - upgrade from the Pricing page.

Note that “API calls” counts every request, including polls. If you poll once every 5 seconds for 30 seconds, that's 6 calls per inbox. A test suite running 50 email-driven tests in a free-tier CI build will hit the limit within about a dozen runs - which is when most teams upgrade to Premium.

Handling 429 responses

When you exceed the limit, the API returns HTTP 429 with a Retry-Afterheader indicating when the next call is permitted. Respect this header instead of retrying immediately. In CI, treat 429 as a soft failure that should retry on the next scheduled run rather than fail the build.

Use Cases

• E2E Testing - Create inboxes in test suites to verify email flows
• CI/CD Pipelines - Automate email verification in deployment pipelines
• Privacy Apps - Integrate disposable email into your product
• Monitoring - Track deliverability by sending to DustMail inboxes
• Customer onboarding tests - Validate signup-confirmation flows automatically
• Marketing email QA - Render production emails to throwaway addresses for review

Best Practices

Treat API keys like passwords.Don't commit them. Pull them from environment variables or a secret manager and rotate periodically. The DustMail dashboard lets you create multiple keys per account so you can scope a key to a specific service and revoke it independently.

Pick the shortest duration that works. Long-lived inboxes hold data longer and cost you against the active-inbox quota. For a single verification flow, 5 to 15 minutes is plenty.

Always clean up. Even though inboxes auto-expire, calling DELETE in teardown means the inbox stops being polled and stops counting against your quota immediately. This pattern keeps test runs clean and predictable.

Full Documentation

For complete API reference including all endpoints, request/response schemas, and code examples in multiple languages, visit the API Documentation.