API Documentation

Base URL: https://tempmail.jp

API Key: Authorization: Bearer tmj_xxx — required for external scripts. Enables usage tracking (Free: 100/mo, Pro: 10,000/mo).

Mailbox Auth: Password required for mailbox operations (POST body)

API Key Authentication

Generate an API key from the API Dashboard (Google login required). Attach the key to requests to enable per-account usage tracking and monthly limits. The key is optional — browser users can call the API without one.

# Pass via Authorization header (recommended)
curl https://tempmail.jp/api/new-address \
  -H "Authorization: Bearer tmj_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Note: Authorization header only. The legacy ?api_key= query parameter
# is no longer supported (it leaks into browser history and proxy logs).

# Invalid / disabled key response
{ "success": false, "error": "Invalid or inactive API key" }

# Monthly limit exceeded (HTTP 429)
{ "success": false, "error": "Monthly API limit exceeded" }

Endpoints

GET /api/new-address

Create a new temporary email address. Supports ?domain= query param for plan-based domain selection.

# Free plan (default: @tempmail.jp)
curl https://tempmail.jp/api/new-address \
  -H "Authorization: Bearer tmj_xxxx"

# Free plan: use @sutemeado.com
curl "https://tempmail.jp/api/new-address?domain=sutemeado.com" \
  -H "Authorization: Bearer tmj_xxxx"

# Pro plan: pro-only domain
curl "https://tempmail.jp/api/new-address?domain=sutemail.com" \
  -H "Authorization: Bearer tmj_xxxx"

// Response
{
  "success": true,
  "address": "abc123@sutemeado.com",
  "password": "xyz789pass",
  "domain": "sutemeado.com"
}

GET /api/domains

Get available domains with plan-based access info.

curl https://tempmail.jp/api/domains \
  -H "Authorization: Bearer tmj_xxxx"

// Response
{
  "success": true,
  "currentPlan": "pro",
  "domains": [
    { "domain": "tempmail.jp",   "accessible": true, "requiredPlan": null  },
    { "domain": "sutemeado.com", "accessible": true, "requiredPlan": null  },
    { "domain": "sutemail.com",  "accessible": true, "requiredPlan": "pro" },
    { "domain": "ai-debate.jp",  "accessible": true, "requiredPlan": "pro" },
    { "domain": "gdte.site",     "accessible": true, "requiredPlan": "pro" }
  ]
}

POST /api/login

curl -X POST https://tempmail.jp/api/login \
  -H "Content-Type: application/json" \
  -d '{"address":"abc123@tempmail.jp","password":"xyz789pass"}'

// Response
{
  "success": true,
  "address": "abc123@tempmail.jp",
  "mails": [...]
}

POST /api/mailbox/:address

Get mail list for an address

curl -X POST "https://tempmail.jp/api/mailbox/abc123@tempmail.jp" \
  -H "Content-Type: application/json" \
  -d '{"password":"xyz789pass"}'

// Response
{
  "success": true,
  "address": "abc123@tempmail.jp",
  "mails": [
    {
      "id": "mail_xxx",
      "from": "sender@example.com",
      "subject": "Hello",
      "body": "Message text...",
      "html": "<p>HTML version...</p>",
      "receivedAt": 1711234567890
    }
  ]
}

POST /api/mailbox/:address/:mailId

Get a specific email

curl -X POST "https://tempmail.jp/api/mailbox/abc123@tempmail.jp/mail_xxx" \
  -H "Content-Type: application/json" \
  -d '{"password":"xyz789pass"}'

DELETE /api/mailbox/:address/:mailId

Delete a specific email

curl -X DELETE "https://tempmail.jp/api/mailbox/abc123@tempmail.jp/mail_xxx" \
  -H "Content-Type: application/json" \
  -d '{"password":"xyz789pass"}'

DELETE /api/mailbox/:address

Delete all emails in an address

curl -X DELETE "https://tempmail.jp/api/mailbox/abc123@tempmail.jp" \
  -H "Content-Type: application/json" \
  -d '{"password":"xyz789pass"}'

DELETE /api/address/:address

Delete an address (all emails will be deleted)

curl -X DELETE "https://tempmail.jp/api/address/abc123@tempmail.jp" \
  -H "Content-Type: application/json" \
  -d '{"password":"xyz789pass"}'

PUT /api/address/:address/password

Change password

curl -X PUT "https://tempmail.jp/api/address/abc123@tempmail.jp/password" \
  -H "Content-Type: application/json" \
  -d '{"currentPassword":"xyz789pass","newPassword":"newpass123"}'

GET /api/mailbox/:address/otp

Extract OTP (One-Time Password) from recent emails

curl "https://tempmail.jp/api/mailbox/abc123@tempmail.jp/otp?password=xyz789pass&limit=5"

// Response
{
  "success": true,
  "found": true,
  "otp": "123456",
  "mailId": "mail_xxx",
  "from": "sender@example.com",
  "subject": "Your verification code",
  "receivedAt": 1711234567890
}

Note: All API endpoints return JSON. For POST/DELETE/PUT requests, the password must be included in the request body. The OTP extraction endpoint uses query parameters for the password.