TempMail API Documentation

Create and manage temporary email addresses on theend.my. Receive emails programmatically via a simple REST API.

Base URL: https://theend.my:8000
All API endpoints require an API key passed via the X-API-Key header.

Authentication

Every request must include your API key in the X-API-Key header. API keys can be obtained from the admin panel.

# Include your API key in every request
curl -H "X-API-Key: your_api_key_here" \
     https://theend.my:8000/api/mail/list
import requests

headers = {"X-API-Key": "your_api_key_here"}
response = requests.get("https://theend.my:8000/api/mail/list", headers=headers)
print(response.json())
const response = await fetch("https://theend.my:8000/api/mail/list", {
    headers: { "X-API-Key": "your_api_key_here" }
});
const data = await response.json();

Credits System

Creating a mailbox costs 1 credit. Your credit balance is managed by the admin. If you run out of credits, mailbox creation requests will return a 402 error.

Error Handling

The API returns standard HTTP status codes:

CodeMeaning
200Success
401Missing or invalid API key
402Insufficient credits
404Resource not found
409Mailbox already exists
429Rate limit exceeded
500Server error

Create Mailbox

POST /api/mail/create Create a new temporary mailbox (1 credit)

Request Body (optional)

FieldTypeDescription
usernamestringDesired username (3-32 chars, alphanumeric). If omitted, a random one is generated.
 
# Create with random username
curl -X POST https://theend.my:8000/api/mail/create \
     -H "X-API-Key: your_key" \
     -H "Content-Type: application/json"

# Create with specific username
curl -X POST https://theend.my:8000/api/mail/create \
     -H "X-API-Key: your_key" \
     -H "Content-Type: application/json" \
     -d '{"username": "mytemp"}'
response = requests.post(
    "https://theend.my:8000/api/mail/create",
    headers={"X-API-Key": "your_key"},
    json={"username": "mytemp"}  # optional
)
mailbox = response.json()
print(mailbox["email"])  # mytemp@theend.my
const res = await fetch("https://theend.my:8000/api/mail/create", {
    method: "POST",
    headers: {
        "X-API-Key": "your_key",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({ username: "mytemp" })
});
const mailbox = await res.json();

Response

{
    "email": "mytemp@theend.my",
    "domain": "theend.my",
    "created_at": "2026-08-11T12:00:00"
}

Delete Mailbox

DELETE /api/mail/{email} Delete a mailbox and all its messages 
curl -X DELETE https://theend.my:8000/api/mail/mytemp@theend.my \
     -H "X-API-Key: your_key"
requests.delete(
    "https://theend.my:8000/api/mail/mytemp@theend.my",
    headers={"X-API-Key": "your_key"}
)
await fetch("https://theend.my:8000/api/mail/mytemp@theend.my", {
    method: "DELETE",
    headers: { "X-API-Key": "your_key" }
});

List Mailboxes

GET /api/mail/list List all mailboxes for your API key 
curl https://theend.my:8000/api/mail/list \
     -H "X-API-Key: your_key"
response = requests.get(
    "https://theend.my:8000/api/mail/list",
    headers={"X-API-Key": "your_key"}
)
mailboxes = response.json()
const res = await fetch("https://theend.my:8000/api/mail/list", {
    headers: { "X-API-Key": "your_key" }
});
const mailboxes = await res.json();

Response

[
    {
        "email": "mytemp@theend.my",
        "domain": "theend.my",
        "created_at": "2026-08-11T12:00:00"
    }
]

Get Inbox

GET /api/mail/{email}/inbox Get all messages in a mailbox 
curl https://theend.my:8000/api/mail/mytemp@theend.my/inbox \
     -H "X-API-Key: your_key"
response = requests.get(
    "https://theend.my:8000/api/mail/mytemp@theend.my/inbox",
    headers={"X-API-Key": "your_key"}
)
const res = await fetch("https://theend.my:8000/api/mail/mytemp@theend.my/inbox", {
    headers: { "X-API-Key": "your_key" }
});

Response

[
    {
        "id": 1,
        "from": "sender@example.com",
        "subject": "Hello!",
        "received_at": "2026-08-11T12:30:00",
        "is_read": false
    }
]

Read Message

GET /api/mail/{email}/message/{id} Read a specific message (marks as read) 
curl https://theend.my:8000/api/mail/mytemp@theend.my/message/1 \
     -H "X-API-Key: your_key"
response = requests.get(
    "https://theend.my:8000/api/mail/mytemp@theend.my/message/1",
    headers={"X-API-Key": "your_key"}
)
message = response.json()
const res = await fetch("https://theend.my:8000/api/mail/mytemp@theend.my/message/1", {
    headers: { "X-API-Key": "your_key" }
});

Response

{
    "id": 1,
    "from_addr": "sender@example.com",
    "subject": "Hello!",
    "body": "This is the email body content.",
    "received_at": "2026-08-11T12:30:00",
    "is_read": true
}

Delete Message

DELETE /api/mail/{email}/message/{id} Delete a specific message 
curl -X DELETE https://theend.my:8000/api/mail/mytemp@theend.my/message/1 \
     -H "X-API-Key: your_key"
requests.delete(
    "https://theend.my:8000/api/mail/mytemp@theend.my/message/1",
    headers={"X-API-Key": "your_key"}
)
await fetch("https://theend.my:8000/api/mail/mytemp@theend.my/message/1", {
    method: "DELETE",
    headers: { "X-API-Key": "your_key" }
});

Message Count

GET /api/mail/{email}/count Get message count for a mailbox 
curl https://theend.my:8000/api/mail/mytemp@theend.my/count \
     -H "X-API-Key: your_key"
response = requests.get(
    "https://theend.my:8000/api/mail/mytemp@theend.my/count",
    headers={"X-API-Key": "your_key"}
)
print(response.json())
const res = await fetch("https://theend.my:8000/api/mail/mytemp@theend.my/count", {
    headers: { "X-API-Key": "your_key" }
});
const counts = await res.json();

Response

{
    "total": 5,
    "unread": 2,
    "read": 3
}