TempMail.co API

REST API

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Base URL

https://api.tempmail.co/v1

Endpoints

GET /me

Get your account information.

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

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

POST /addresses

Create a new temporary email address.

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

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

GET /addresses/{email}

Get address details. Extends expiration by 7 days.

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

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

DELETE /addresses/{email}

Delete an address and all its emails.

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

Returns 204 No Content on success.

GET /addresses/{email}/emails

List emails for an address with pagination.

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

Query params: page (default: 1)

{
    "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"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 20,
        "total": 1
    }
}

GET /emails/{uuid}

Get full email content including body.

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

{
    "data": {
        "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.</p>",
        "created_at": "2025-01-16T00:00:00.000000Z",
        "address": {
            "email": "[email protected]",
            "expires_at": "2025-01-23T00:00:00.000000Z"
        }
    }
}

Rate Limits

Action	Limit
Create addresses	5/min, 100/day
All other requests	5/second

Rate limited requests return 429 with Retry-After header.

Errors

Status	Meaning
401	Invalid or missing token
404	Resource not found
422	Validation error
429	Rate limited

{
    "message": "The given data was invalid.",
    "errors": {
        "field": ["Error message"]
    }
}

---

Webhooks

Get notified instantly when emails arrive at your API-created addresses.

Setup

1. Go to API Settings in your dashboard
2. Add your webhook URL
3. We'll POST to your URL when emails arrive

Payload

{
    "event": "email.received",
    "data": {
        "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",
        "address": {
            "email": "[email protected]",
            "expires_at": "2025-01-23T00:00:00.000000Z"
        }
    }
}

Notes

• Only API-created addresses trigger webhooks
• Your endpoint must respond with HTTP 200
• 30 second timeout
• Failed deliveries retry 3 times

---

MCP Integration

Use the Model Context Protocol to let AI assistants manage your temporary emails.

MCP Endpoint

https://www.tempmail.co/mcp

MCP Authentication

Same as REST API - include your token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Tools

Tool	Description
get-current-user	Get authenticated user details
create-tempmail-address	Create a new temporary email
delete-tempmail-address	Delete an address and its emails
list-tempmail-addresses	List your addresses (optional limit)
get-tempmail-address	Get address details
list-emails-for-address	List emails for an address (optional page)
get-tempmail-email	Get full email content by UUID

Claude Code

Add to .claude/settings.json:

{
    "mcpServers": {
        "tempmail": {
            "type": "http",
            "url": "https://www.tempmail.co/mcp",
            "headers": {
                "Authorization": "Bearer YOUR_API_TOKEN"
            }
        }
    }
}

Cursor

1. Open Settings → MCP
2. Add HTTP provider with URL https://www.tempmail.co/mcp
3. Set Authorization header with your token

---

Support

Questions? Email [email protected]