How to Use the Temp Mail API

The Temp Mail API lets you create temporary email addresses and read incoming messages programmatically. It's built for developers who need disposable emails in automated tests, CI/CD pipelines, or custom applications.

What Can You Do with the API?

• Create temporary email addresses — random or with a specific name and domain
• Read incoming messages — including HTML body, plain text, and attachments
• Use premium and custom domains — create addresses on domains that aren't publicly listed
• Download attachments and raw email source code
• Delete emails and messages when you're done

For the full endpoint reference, see the API documentation. There's also a quick overview on the API page.

Getting Started

Step 1: Get a premium subscription

The API is available to premium subscribers. Once subscribed, you can generate API keys from your profile.

Step 2: Create an API key

1. Go to Profile → API
2. Click "Create new token"
3. Give your key a name (e.g., "CI pipeline", "E2E tests")
4. Copy the key immediately — it's only shown once

Step 3: Make your first API call

All requests use the X-API-Key header for authentication. Here's a quick example — create an email and check for messages:

# Create a temporary email
curl -X POST https://api.temp-mail.io/v1/emails \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Check for messages
curl https://api.temp-mail.io/v1/emails/YOUR_EMAIL/messages \
  -H "X-API-Key: YOUR_API_KEY"

That's it. See the full documentation for all endpoints, parameters, and response formats.

Common Use Cases

Automated testing

The most popular use case. Create temp emails in your test suite to verify sign-up flows, email notifications, OTP codes, and password resets. Works great with Playwright, Cypress, and Selenium.

CI/CD pipelines

Integrate temp mail into GitHub Actions, GitLab CI, or Jenkins. Test email-dependent features automatically on every push without maintaining real email accounts.

GDPR-compliant development

Use temporary emails in dev and staging environments instead of real user data. No personal data to worry about, no compliance headaches.

Custom applications

Build temp mail into your own product — whether it's a privacy tool, an onboarding flow, or anything else that needs disposable email addresses.

Official SDKs

We provide official libraries so you don't have to work with the REST API directly:

• Python
• PHP
• Go
• .NET

Rate Limits

Your monthly request limit depends on the API package you choose during subscription. You can pick the package that fits your usage — from smaller volumes for testing to larger ones for production workloads.

Every API response includes rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Reset). You can also check your current usage at any time via the GET /v1/rate_limit endpoint or on the Profile → API page.

Managing Your Keys

From Profile → API you can:

• See all your active keys and when they were created
• Monitor usage statistics (requests used vs. total per month)
• Delete keys you no longer need