HomeDocsAPI Reference

API Reference

Full REST API documentation with request/response examples for every endpoint.

Overview

All endpoints are under https://minutemail.xyz/api. Responses are JSON. Authentication is via the Authorization: Bearer <sessionToken> header.

Base URL

https://minutemail.xyz/api

Note

The session token is returned when you create a mailbox. Include it in the Authorization header for all subsequent requests to that mailbox.

Create Mailbox

POST/api/mailbox

Create a new temporary mailbox with a specified duration.

Request Body

FieldTypeDescription
durationnumberMinutes: 2, 5, 10, 15, 30, 45, or 60. Default: 10
bash
curl -X POST https://minutemail.xyz/api/mailbox \
  -H "Content-Type: application/json" \
  -d '{"duration": 10}'

Response 201

json
{
  "id": "abc123def456",
  "address": "[email protected]",
  "createdAt": 1711738800000,
  "expiresAt": 1711739400000,
  "duration": 10,
  "sessionToken": "tok_abc123..."
}

Get Mailbox

GET/api/mailbox/:id

Retrieve mailbox metadata and all emails. Requires session token.

bash
curl https://minutemail.xyz/api/mailbox/abc123def456 \
  -H "Authorization: Bearer tok_abc123..."

Response 200

json
{
  "id": "abc123def456",
  "address": "[email protected]",
  "createdAt": 1711738800000,
  "expiresAt": 1711739400000,
  "emails": [
    {
      "id": "email_001",
      "from": "[email protected]",
      "subject": "Verify your email",
      "preview": "Click the link below to verify...",
      "receivedAt": 1711738900000,
      "read": false
    }
  ]
}

Get Email

GET/api/mailbox/:id/email/:emailId

Retrieve a specific email with full body content and attachments.

bash
curl https://minutemail.xyz/api/mailbox/abc123def456/email/email_001 \
  -H "Authorization: Bearer tok_abc123..."

Response 200

json
{
  "id": "email_001",
  "from": "[email protected]",
  "fromName": "Example App",
  "to": "[email protected]",
  "subject": "Verify your email",
  "textBody": "Click: https://example.com/verify?t=...",
  "htmlBody": "<html>...</html>",
  "receivedAt": 1711738900000,
  "read": true,
  "attachments": []
}

Extend Mailbox

POST/api/mailbox/:id/extend

Extend the mailbox expiration time. Default adds 10 minutes.

FieldTypeDescription
minutesnumberMinutes to add. Default: 10. Max total: 60 from now.
bash
curl -X POST https://minutemail.xyz/api/mailbox/abc123def456/extend \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tok_abc123..." \
  -d '{"minutes": 15}'

Delete Mailbox

DELETE/api/mailbox/:id

Permanently destroy a mailbox and all its data immediately.

bash
curl -X DELETE https://minutemail.xyz/api/mailbox/abc123def456 \
  -H "Authorization: Bearer tok_abc123..."

Warning

This action is irreversible. All emails, attachments, and metadata are permanently deleted.

Attachments

GET/api/mailbox/:id/email/:emailId/attachment/:filename

Download a specific attachment from an email. Returns the raw file with appropriate Content-Type headers.

bash
curl -O https://minutemail.xyz/api/mailbox/abc123/email/email_001/attachment/report.pdf \
  -H "Authorization: Bearer tok_abc123..."

Error Codes

All error responses follow the same format:

json
{ "error": "Human-readable error message" }
StatusMeaning
400Bad request — invalid parameters
401Unauthorized — missing or invalid session token
404Not found — mailbox or email doesn't exist (or expired)
429Rate limited — too many requests from this IP
500Server error — unexpected failure
PreviousUser GuideNext WebSocket