Getting Started
Introduction Authentication
Endpoints
Domains Inboxes Emails Webhook

Introduction

The TempMail REST API allows you to programmatically create temporary email inboxes, retrieve emails, and manage your temp mail workflow.

Base URL https://tempmail.geniusgsm.com/api

All API responses are in JSON format. All requests must include the Content-Type: application/json header.

Authentication

Most endpoints are publicly accessible. For authenticated endpoints, use Token Authentication:

Authorization: Token your_api_token_here

Domains

List available domains

GET /api/domains/ Get all active domains

Returns a list of all active email domains available for inbox creation.

Response

[
  {
    "id": 1,
    "name": "tempmail.geniusgsm.com",
    "is_active": true
  }
]

Inboxes

POST /api/inboxes/create_inbox/ Create a new inbox

Request Body

ParameterTypeDescription
domain_idrequiredintegerID of the email domain
ttloptionalintegerLifetime in seconds (default: 3600)

Example

POST /api/inboxes/create_inbox/
{
  "domain_id": 1,
  "ttl": 3600
}

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "abc123@tempmail.geniusgsm.com",
  "expires_at": "2026-06-17T20:00:00Z",
  "ttl": 3600
}
GET /api/inboxes/{id}/emails/ Get inbox emails

Returns all emails received in a specific inbox.

GET /api/inboxes/550e8400-e29b-41d4-a716-446655440000/emails/
DELETE /api/inboxes/{id}/ Delete inbox

Permanently deletes an inbox and all associated emails.

DELETE /api/inboxes/550e8400-e29b-41d4-a716-446655440000/

Emails

GET /api/emails/{id}/ Get email details

Returns the full content of a specific email including HTML body and attachments.

Response

{
  "id": "email-uuid",
  "from_email": "sender@example.com",
  "from_name": "Sender Name",
  "subject": "Email Subject",
  "body_text": "Plain text content",
  "body_html": "<html>...</html>",
  "received_at": "2026-06-17T19:00:00Z",
  "is_read": false
}

Webhook

POST /api/webhook/email/ Receive incoming email (server-side)

This endpoint is used by the mail server to deliver incoming emails to inboxes. Not intended for direct use.