API Documentation

TempMail.co API

Getting Started

Introduction

TempMail.co provides a simple REST API for creating temporary email addresses and retrieving emails. Perfect for testing, automation, or any application that needs disposable email addresses.

What you can do:

  • Generate temporary email addresses instantly
  • Retrieve emails sent to those addresses
  • Get real-time notifications when emails arrive
  • Manage multiple addresses from one account

Authentication

All API requests require an API token. Include it in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Quick Start

  1. Sign up for a free account
  2. Verify your email address
  3. Generate an API token in your dashboard
  4. Start making API calls!

Base URL

https://api.tempmail.co/v1

API Endpoints

User Info

GET /me

Get your account information.

curl -X GET "https://api.tempmail.co/v1/me" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
    "data": {
        "email": "[email protected]"
    }
}

Managing Addresses

POST /addresses

Create a new temporary email address. We'll automatically assign you a random address from our available domains.

curl -X POST "https://api.tempmail.co/v1/addresses" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
    "data": {
        "email": "[email protected]",
        "expires_at": "2025-01-23T00:00:00.000000Z",
        "emails": []
    }
}

The address expires 7 days after creation, but accessing it resets the timer.

GET /addresses/{email}

Get details about a specific address and see any emails it has received. This also extends the expiration by another 7 days.

curl -X GET "https://api.tempmail.co/v1/addresses/[email protected]" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
    "data": {
        "email": "[email protected]",
        "expires_at": "2025-01-23T00:00:00.000000Z"
    }
}

GET /addresses/{email}/emails

Get all emails for an address with pagination. Useful when an address has received many emails.

curl -X GET "https://api.tempmail.co/v1/addresses/[email protected]/emails" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Query Parameters:

  • page (optional) - Page number for pagination (default: 1)

Response:

{
    "data": [
        {
            "uuid": "550e8400-e29b-41d4-a716-446655440000",
            "from": "[email protected]",
            "to": "[email protected]",
            "subject": "Please verify your account",
            "created_at": "2025-01-16T00:00:00.000000Z"
        }
    ],
    "links": {
        "first": "https://api.tempmail.co/v1/addresses/[email protected]/emails?page=1",
        "last": "https://api.tempmail.co/v1/addresses/[email protected]/emails?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "per_page": 20,
        "total": 1
    }
}

Reading Emails

GET /emails/{uuid}

Get the full content of an email, including the message body.

curl -X GET "https://api.tempmail.co/v1/emails/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
    "data": {
        "address": {
            "email": "[email protected]",
            "expires_at": "2025-01-23T00:00:00.000000Z"
        },
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "from": "[email protected]",
        "to": "[email protected]",
        "subject": "Please verify your account",
        "body": "<p>Click <a href='https://example.com/verify'>here</a> to verify your account.</p>",
        "created_at": "2025-01-16T00:00:00.000000Z"
    }
}

Webhooks

Real-time Email Notifications

Get notified instantly when emails arrive by setting up a webhook. Perfect for automation and real-time processing.

Setup:

  1. Go to your dashboard
  2. Add your webhook URL in the settings
  3. We'll POST to your URL whenever a new email arrives

Webhook Payload

When an email arrives, we'll send this to your webhook URL:

{
    "event": "email.received",
    "data": {
        "address": {
            "email": "[email protected]",
            "expires_at": "2025-01-23T00:00:00.000000Z"
        },
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "from": "[email protected]",
        "to": "[email protected]",
        "subject": "Please verify your account",
        "body": "<p>Click here to verify your account.</p>",
        "created_at": "2025-01-16T00:00:00.000000Z"
    }
}

Important:

  • Only API-created addresses trigger webhooks
  • Your endpoint should respond with HTTP 200
  • We timeout after 30 seconds
  • Failed deliveries are retried 3 times

Complete Example

Here's how to create an address, use it, and check for emails:

Step 1: Create an Address

curl -X POST "https://api.tempmail.co/v1/addresses" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
    "data": {
        "email": "[email protected]",
        "expires_at": "2025-01-23T00:00:00.000000Z",
        "emails": []
    }
}

Step 2: Use the Email

Use [email protected] to sign up for a service, then check for emails:

curl -X GET "https://api.tempmail.co/v1/addresses/[email protected]/emails" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Step 3: Read Email Content

Found emails? Get the full content:

curl -X GET "https://api.tempmail.co/v1/emails/abc-123-def-456" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

That's it! You now have the verification link or whatever content was sent.

API Reference

Rate Limits

To ensure fair usage, we limit:

  • Creating addresses: 5 per minute, 100 per day
  • Everything else: 5 requests per second

Hit the limit? You'll get a 429 response with retry information:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
Retry-After: 60

Address Lifecycle

  • New addresses expire after 7 days
  • Accessing an address resets the timer to 7 more days
  • Expired addresses and their emails are permanently deleted

Error Responses

Standard HTTP status codes:

  • 200 - Success
  • 401 - Bad or missing API token
  • 404 - Address/email not found
  • 422 - Invalid request data
  • 429 - Rate limited
  • 500 - Our bad! Try again

Error details are in this format:

{
    "message": "The given data was invalid.",
    "errors": {
        "field_name": ["Specific error message here"]
    }
}

Need Help?

Email us: [email protected]

We're here to help you integrate successfully!

Have feedback?