Skip to main content

Temp Mail API

This API allows you to create temporary email addresses and manage messages.

How it works​

  • Create a new email address by using our domain names
  • Use this email address on any website
  • The website sends an email message to the email address you specify
  • A message comes to our SMTP server, processed and added to the database
  • You make a request to the API to fetch the message list
  • That's it! You're awesome!

Base URL​

https://api.temp-mail.io

Authentication​

All API endpoints require authentication using an API key. Include your API key in the X-API-Key header with each request.

For example:

curl -H "X-API-Key: YOUR_API_KEY" https://api.temp-mail.io/v1/domains

You need active premium account to use the API. To obtain key visit this page.

Rate Limiting​

The API implements rate limiting to ensure fair usage. Rate limit information is included in the response headers:

  • X-Ratelimit-Limit: Maximum number of requests per period
  • X-Ratelimit-Remaining: Remaining requests in the current period
  • X-Ratelimit-Used: Number of requests made in the current period
  • X-Ratelimit-Reset: Time when the rate limit resets (UTC epoch seconds)

Basic Usage​

Here's an example of a typical API usage scenario:

1. Create a Temporary Email​

curl -X POST https://api.temp-mail.io/v1/emails \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "email": "user@example.com",
  "ttl": 86400
}

2. Get List of Messages​

curl https://api.temp-mail.io/v1/emails/user@example.com/messages \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "messages": [
    {
      "id": "a48b927e-3a24-42ff-a748-d516e5474f85",
      "from": "\"Service\" <no-reply@service.com>",
      "subject": "Welcome!",
      "created_at": "2023-12-16T10:00:00Z"
    }
  ]
}

3. Get Specific Message​

curl https://api.temp-mail.io/v1/messages/a48b927e-3a24-42ff-a748-d516e5474f85 \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "id": "a48b927e-3a24-42ff-a748-d516e5474f85",
  "from": "\"Service\" <no-reply@service.com>",
  "to": "user@example.com",
  "subject": "Welcome!",
  "body_text": "Welcome to our service!",
  "body_html": "<p>Welcome to our service!</p>",
  "created_at": "2023-12-16T10:00:00Z",
  "attachments": [
    {
      "id": "b59c038f-4b2d-4e0a-9f8b-e3f6d7c8a9b0",
      "name": "welcome.pdf",
      "size": 12345
    }
  ]
}

4. Download Attachment​

curl https://api.temp-mail.io/v1/messages/a48b927e-3a24-42ff-a748-d516e5474f85/attachments/b59c038f-4b2d-4e0a-9f8b-e3f6d7c8a9b0 \
  -H "X-API-Key: YOUR_API_KEY" \
  --output welcome.pdf

5. Get Message Source Code​

curl https://api.temp-mail.io/v1/messages/a48b927e-3a24-42ff-a748-d516e5474f85/source \
  -H "X-API-Key: YOUR_API_KEY"

6. Delete Message​

curl -X DELETE https://api.temp-mail.io/v1/messages/a48b927e-3a24-42ff-a748-d516e5474f85 \
  -H "X-API-Key: YOUR_API_KEY"

7. Delete Temporary Email​

curl -X DELETE https://api.temp-mail.io/v1/emails/user@example.com \
  -H "X-API-Key: YOUR_API_KEY"

Error Handling​

The API uses standard HTTP status codes and returns detailed error information in JSON format:

{
  "error": {
    "type": "request_error",
    "code": "not_found",
    "detail": "Message not found"
  },
  "meta": {
    "request_id": "a48b927e-3a24-42ff-a748-d516e5474f85"
  }
}