API Documentation - TempMail.co

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

Sign up for a free account
Verify your email address
Generate an API token in your dashboard
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:

Go to your dashboard
Add your webhook URL in the settings
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

MCP Integration

Prefer to let an AI assistant manage inboxes for you? TempMail ships with a Model Context Protocol (MCP) server that exposes the same functionality as our HTTP API.

Endpoints

Local server: php artisan mcp:start tempmail
HTTP endpoint: /mcp/tempmail

Authenticating Tools

Every MCP tool expects a token argument. Generate a personal access token in your dashboard and share it with the assistant (just like the Authorization header in the REST API).

Available Tools

get-current-tempmail-user — confirms the token, returning account and token metadata.
list-tempmail-addresses — shows recently active addresses (optional limit).
create-tempmail-address — provisions a fresh disposable address.
get-tempmail-address — fetches an address you already created.
list-emails-for-address — paginated emails for a specific address (page optional).
get-tempmail-email — loads the full email payload by UUID.

Test It Quickly

Run php artisan mcp:inspector tempmail, paste your token, and call the tools interactively before wiring them into your MCP-compatible client.

Connect With Popular MCP Clients

Cursor

Start the local server: php artisan mcp:start tempmail.
Open Cursor → Settings → MCP.
Add a new local provider pointing to the command above and paste your TempMail token into the provider settings.
Enable the provider and ask Cursor to "use TempMail tools"—it will list the available commands.

Claude Code (or other web MCP clients)

Ensure your TempMail app is running (Laravel Herd serves it at https://tempmail.test).
Add a web MCP server with the URL generated by php artisan route:list | grep /mcp/tempmail (usually https://tempmail.test/mcp/tempmail).
Supply the TempMail personal access token when prompted. Claude Code will pass it as the token argument on each tool call.
Trigger the MCP tools from your chat prompt—e.g., "Create a TempMail address for me"—and the assistant will handle the token exchange automatically.

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!

TempMail.co API

Getting Started

Introduction

Authentication

Quick Start

Base URL

API Endpoints

User Info

GET /me

Managing Addresses

POST /addresses

GET /addresses/{email}

GET /addresses/{email}/emails

Reading Emails

GET /emails/{uuid}

Webhooks

Real-time Email Notifications

Webhook Payload

MCP Integration

Endpoints

Authenticating Tools

Available Tools

Test It Quickly

Connect With Popular MCP Clients

Complete Example

Step 1: Create an Address

Step 2: Use the Email

Step 3: Read Email Content

API Reference

Rate Limits

Address Lifecycle

Error Responses

Need Help?

Sign up for more features