Documentation API

Base URL

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

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.

// Request Body (optional)
{
  "domain": "get-a-temp-email.xyz"
}

// Response
{
  "success": true,
  "data": {
    "token": "aBcDeFgHiJkLmNoPqRsTuVwXyZ123456",
    "email": "[email protected]",
    "createdAt": "2024-12-01T00:00:00.000Z",
    "expiresAt": "2024-12-02T00:00:00.000Z"
  }
}

Get Inbox Info

Retrieve information about an existing inbox using its token.

Get Emails

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

// Response
{
  "success": true,
  "data": [
    {
      "id": "email_abc123",
      "from": "[email protected]",
      "subject": "Your verification code",
      "extracted": {
        "codes": ["123456"],
        "links": ["https://github.com/verify/abc"]
      }
    }
  ]
}

Get Available Domains

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

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

Smart Code Extraction

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

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

Premium API endpoints require wallet authentication. First authenticate with your TON wallet to obtain a session token, then include it in the Authorization header.

// All premium endpoints require this header
Authorization: Bearer {sessionToken}

Get Mailboxes

Retrieve all fixed mailboxes associated with your wallet account.

// Response
{
  "success": true,
  "data": [
    {
      "email": "[email protected]",
      "type": "paid",
      "status": "active",
      "retentionDays": 7,
      "emailCount": 5,
      "accessToken": "abc123...",
      "notify": {
        "enabled": true,
        "platform": "telegram",
        "target": "123456789"
      },
      "createdAt": "2025-01-01T00:00:00.000Z"
    }
  ]
}

Create Fixed Mailbox

Create a new fixed mailbox with your custom email address. Requires an available mailbox slot.

// Request Body
{
  "address": "yourname",
  "domain": "get-a-temp-email.xyz",
  "retentionDays": 7
}

// Response
{
  "success": true,
  "data": {
    "email": "[email protected]",
    "type": "paid",
    "status": "active",
    "retentionDays": 7,
    "accessToken": "abc123..."
  }
}

Update Mailbox Settings

Update retention days and notification settings for a fixed mailbox.

// Request Body
{
  "retentionDays": 7,
  "notify": {
    "enabled": true,
    "platform": "telegram",  // or "webhook"
    "target": "123456789"    // chat_id or webhook URL
  }
}

// Response
{
  "success": true,
  "data": { ... }  // Updated mailbox object
}

Delete Mailbox

Delete a fixed mailbox. This action is irreversible and frees up a mailbox slot.

// Response
{
  "success": true
}