API Documentation

Complete REST API for programmatic access to TmpMail services. Perfect for testing, automation, and CI/CD pipelines.

Quick Start

# Create a new inbox
curl -X POST https://get-a-temp-email.xyz/api/inbox

# Get emails (use the token from above)
curl https://get-a-temp-email.xyz/api/inbox/{token}/emails

Base URL

https://get-a-temp-email.xyz

All API endpoints are available via HTTPS. HTTP requests will be redirected.

Authentication

TmpMail API uses token-based authentication. When you create an inbox, you receive a unique token. This token is used to access your inbox and emails. Keep your token private - anyone with the token can access your emails.

Create Inbox

Create a new temporary email inbox. Returns a unique token and email address.

POST/api/inbox
// Request Body (optional)
{
  "domain": "get-a-temp-email.xyz"  // Optional: specify domain
}

// Response
{
  "success": true,
  "data": {
    "token": "aBcDeFgHiJkLmNoPqRsTuVwXyZ123456",
    "email": "alex1234@get-a-temp-email.xyz",
    "createdAt": "2024-12-01T00:00:00.000Z",
    "expiresAt": "2024-12-02T00:00:00.000Z"
  }
}

Example (cURL)

curl -X POST https://get-a-temp-email.xyz/api/inbox \
  -H "Content-Type: application/json" \
  -d '{"domain": "get-a-temp-email.xyz"}'

Get Inbox Info

Retrieve information about an existing inbox using its token.

GET/api/inbox/:token
// Response
{
  "success": true,
  "data": {
    "token": "aBcDeFgHiJkLmNoPqRsTuVwXyZ123456",
    "email": "alex1234@get-a-temp-email.xyz",
    "createdAt": "2024-12-01T00:00:00.000Z",
    "expiresAt": "2024-12-02T00:00:00.000Z",
    "emailCount": 3
  }
}

Get Emails

Retrieve all emails for an inbox. Includes smart-extracted verification codes and links.

GET/api/inbox/:token/emails
// Response
{
  "success": true,
  "data": [
    {
      "id": "email_abc123",
      "from": "noreply@github.com",
      "fromDomain": "github.com",
      "subject": "Your verification code",
      "textContent": "Your code is 123456",
      "htmlContent": "<p>Your code is <b>123456</b></p>",
      "receivedAt": "2024-12-01T12:00:00.000Z",
      "extracted": {
        "codes": ["123456"],
        "links": ["https://github.com/verify/abc"],
        "templateUsed": "GitHub"
      }
    }
  ]
}

Example (Python)

import requests
import time

# Create a new inbox
response = requests.post("https://get-a-temp-email.xyz/api/inbox")
inbox = response.json()["data"]
print(f"Your temp email: {inbox['email']}")
print(f"Token: {inbox['token']}")

# Poll for emails (wait up to 5 minutes)
for _ in range(60):
    response = requests.get(
        f"https://get-a-temp-email.xyz/api/inbox/{inbox['token']}/emails"
    )
    emails = response.json()["data"]

    if emails:
        # Get verification code from first email
        codes = emails[0]["extracted"]["codes"]
        if codes:
            print(f"Verification code: {codes[0]}")
            break

    time.sleep(5)  # Wait 5 seconds between checks

Get Available Domains

Get the list of available email domains you can use when creating an inbox.

GET/api/domains
// Response
{
  "success": true,
  "data": [
    { "domain": "get-a-temp-email.xyz", "label": "Default", "default": true }
  ]
}

Rate Limits

To ensure fair usage, the API has the following rate limits:

EndpointLimit
POST /api/inbox10 requests/minute per IP
GET /api/inbox/:token/emails60 requests/minute per token
Other endpoints100 requests/minute per IP

Error Responses

The API uses standard HTTP status codes and returns errors in a consistent format:

{
  "success": false,
  "error": "Error message description"
}
StatusDescription
400Bad request - Invalid parameters
404Not found - Inbox or email doesn't exist
429Too many requests - Rate limit exceeded
500Server error - Please try again

Smart Code Extraction

TmpMail automatically extracts verification codes and important links from emails. We support templates from these popular services:

GitHubGoogleTwitter/XFacebookMicrosoftAppleDiscordSlackNotionLinkedInNetflixStripeVercelZoomPayPalAmazonDropboxSpotifyUberOpenAI

Don't see your service? Our generic code detection works for most verification emails.

Ready to integrate?

Start using TmpMail API in your projects today. No API key required.

Try TmpMail NowContact for Enterprise