← Back to Home

🔐 Authentication

The API uses two authentication methods depending on the endpoint type.

Public API (X-API-KEY)

All public endpoints require an API key passed via header.

Required Header

X-API-KEY: mk_your_api_key_here

Admin API (JWT Bearer)

Admin endpoints require JWT token from login endpoint.

Required Header

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

📖 Overview

TPMail is a temporary email service API. Generate disposable email addresses and receive messages.

Base URL: https://your-domain.com/api

Response Format: JSON

Public API

GET /api/emails/domains

List all available active domains for email generation.

Request

curl -X GET https://your-domain.com/api/emails/domains \
  -H "X-API-KEY: mk_your_api_key"

Response

["gencutaraka.xyz", "example.com"]
POST /api/emails/generate

Generate a new temporary email address. Expires after 24 hours.

Request (Optional Body)

{ "domain": "gencutaraka.xyz" }

cURL Example

curl -X POST https://your-domain.com/api/emails/generate \
  -H "X-API-KEY: mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"domain": "gencutaraka.xyz"}'

Response

{
  "email": "a1b2c3d4@gencutaraka.xyz",
  "expires_at": "2025-12-22T10:00:00.000Z"
}
GET /api/emails/:email/messages

Retrieve all messages received by a temporary email.

cURL Example

curl -X GET https://your-domain.com/api/emails/abc@domain.com/messages \
  -H "X-API-KEY: mk_your_api_key"

Response

[
  {
    "from": "sender@example.com",
    "subject": "Welcome!",
    "body": "<html>...</html>",
    "received_at": "2025-12-21T10:30:00.000Z"
  }
]

Admin API

POST /api/admin/login

Authenticate as admin and receive JWT token.

Request Body

{
  "email": "admin@example.com",
  "password": "admin123"
}

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600
}
GET /api/admin/stats

Get dashboard statistics. Requires JWT authentication.

Response

{
  "total_domains": 2,
  "active_domains": 2,
  "total_emails": 150,
  "active_emails": 45,
  "total_messages": 320
}
GET /api/admin/domains

List all registered domains with IMAP configuration.

POST /api/admin/domains

Create a new domain with IMAP settings.

Request Body

{
  "domain": "newdomain.com",
  "imap_host": "mail.newdomain.com",
  "imap_port": 993,
  "imap_user": "catch@newdomain.com",
  "imap_password": "password"
}
PATCH /api/admin/domains/:id

Update domain configuration. All fields are optional.

DELETE /api/admin/domains/:id

Delete a domain. Also deletes all associated emails and messages.

API Keys

GET /api/admin/api-keys

List all API keys. Keys are partially masked for security.

POST /api/admin/api-keys

Generate a new API key. Full key is only shown once!

Request Body

{ "name": "Production API Key" }

Response

{
  "id": "uuid",
  "name": "Production API Key",
  "key": "mk_full_key_shown_only_once"
}
⚠️ Important: The full API key is only shown once. Store it securely!
DELETE /api/admin/api-keys/:id

Revoke and delete an API key.

Utilities

POST /api/admin/imap/test

Test IMAP connection before adding a new domain.

Request Body

{
  "host": "mail.example.com",
  "port": 993,
  "user": "user@example.com",
  "password": "password"
}

Response

{
  "success": true,
  "message": "IMAP connection successful"
}