TempEmail API Documentation

Introduction

Welcome to the Temp Mail API documentation. This API provides endpoints for managing temporary email accounts, receiving messages, and domain management. All endpoints return JSON responses and use standard HTTP methods.

Authentication

Most API endpoints require authentication using JWT (JSON Web Token). Include the token in the Authorization header of your requests.

Token Structure

interface TokenPayload {
  iat: number;           // Issued at timestamp
  id: string;            // Mailbox ID
  mercure?: {
    subscribe?: string[]; // Mercure subscription permissions
    publish?: string[];   // Mercure publish permissions
  };
}

Using the Token

Add the following header to your HTTP requests:

const headers = {
  'Authorization': `Bearer ${token}`,
  'Content-Type': 'application/json'
};

Accounts

POST/api/accounts

Register a New Account

Create a new temporary email account. Rate limited to 1 registration per IP every 30 seconds.

Authentication: Not required

Request Body

Field	Type	Description
email	string	Email address (automatically converted to lowercase)
password	string	Account password

Example Request

const response = await fetch('/api/accounts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: '[email protected]',
    password: 'securePassword123'
  })
});

const data = await response.json();
console.log(data);

Success Response (200)

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "123456",
    "name": "[email protected]",
    "quota": 104857600,
    "used": 0,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "createdAt": 1640000000000
  }
}

POST/api/token

Get Authentication Token (Login)

Authenticate and receive a JWT token for accessing protected endpoints.

Authentication: Not required

Example Request

const response = await fetch('/api/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: '[email protected]',
    password: 'securePassword123'
  })
});

const { data } = await response.json();
localStorage.setItem('token', data.token);

Success Response (200)

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "123456",
    "email": "[email protected]",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

GET/api/me

Get Current User Information

Retrieve information about the currently authenticated user.

Authentication: Required

Example Request

const token = localStorage.getItem('token');

const response = await fetch('/api/me', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const data = await response.json();
console.log(data);

Success Response (200)

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "123456",
    "name": "[email protected]",
    "quota": 104857600,
    "used": 1024000,
    "status": 1,
    "createdAt": 1640000000000
  }
}

DELETE/api/accounts

Delete Account

Permanently delete the authenticated user's account and all associated data.

Authentication: Required

Example Request

const token = localStorage.getItem('token');

const response = await fetch('/api/accounts', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const data = await response.json();
console.log(data);

Messages

GET/api/messages

Get Message List (Paginated)

Retrieve a paginated list of messages for the authenticated user.

Authentication: Required

Query Parameters

Parameter	Type	Required	Description
limit	number	No	Items per page (10-50, default: 10)
cursor	string	No	Pagination cursor for next page

Example Request

const token = localStorage.getItem('token');
const limit = 20;
const cursor = null; // or cursor from previous response

const params = new URLSearchParams({ limit: limit.toString() });
if (cursor) params.append('cursor', cursor);

const response = await fetch(`/api/messages?${params}`, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const data = await response.json();
console.log(data);

Success Response (200)

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "789",
        "from": "[email protected]",
        "to": "[email protected]",
        "subject": "Welcome to Temp Mail",
        "summary": "Thank you for signing up...",
        "size": 2048,
        "isRead": false,
        "createdAt": 1640000000000
      }
    ],
    "pagination": {
      "nextCursor": "12345",
      "limit": 20
    }
  }
}

GET/api/messages/:id

Get Message Detail

Retrieve detailed information about a specific message.

Authentication: Required

Example Request

const token = localStorage.getItem('token');
const messageId = '789';

const response = await fetch(`/api/messages/${messageId}`, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const data = await response.json();
console.log(data);

GET/api/messages/:id/raw

Get Raw Message Content

Retrieve the raw RFC format (MIME) content of a message.

Authentication: Required

Example Request

const token = localStorage.getItem('token');
const messageId = '789';

const response = await fetch(`/api/messages/${messageId}/raw`, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const data = await response.json();
console.log(data.data.raw);

GET/api/messages/:id/read

Mark Message as Read

Mark a specific message as read.

Authentication: Required

Example Request

const token = localStorage.getItem('token');
const messageId = '789';

const response = await fetch(`/api/messages/${messageId}/read`, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const data = await response.json();
console.log(data);

DELETE/api/messages/:id

Delete Message

Permanently delete a specific message.

Authentication: Required

Example Request

const token = localStorage.getItem('token');
const messageId = '789';

const response = await fetch(`/api/messages/${messageId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const data = await response.json();
console.log(data);

Domains

GET/api/domains

Get Domain List

Retrieve a list of available domains for temporary email addresses.

Authentication: Required

Example Request

const token = localStorage.getItem('token');

const response = await fetch('/api/domains', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const data = await response.json();
console.log(data);

Success Response (200)

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "1",
      "domain": "tempmail.com"
    },
    {
      "id": "2",
      "domain": "example.org"
    }
  ]
}

Error Handling

All API endpoints return errors in a standardized JSON format. Use HTTP status codes to determine the type of error.

Standard Error Response

{
  "code": 400,
  "message": "Invalid email format",
  "data": null
}

Common Error Codes

Status Code	Description
400	Bad Request - Invalid parameters or data format
401	Unauthorized - Invalid or missing authentication token
403	Forbidden - Insufficient permissions or account disabled
404	Not Found - Resource does not exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server-side error