Base URL

https://getcodemail.com/api/v1

Temporary Email API endpoints can be used without authentication — just pass the email address in the URL. Optionally use a token.

Mail API endpoints require a token (returned when creating a mailbox). You can also get the token from the Mailboxes page in your account.

Two ways to pass the token

# Option 1: Authorization header (recommended)
Authorization: Bearer your-token-here

# Option 2: Query parameter
GET /api/v1/inbox?token=your-token-here

List all available domains for creating temporary mailboxes.

Example

curl https://getcodemail.com/api/v1/domains

Response

{
  "success": true,
  "domains": [
    { "id": 1, "domain": "getcodemail.com" }
  ]
}

Create a temporary mailbox with a custom username. Returns email address and API token.

curl -X POST https://getcodemail.com/api/v1/create \
  -H "Content-Type: application/json" \
  -d '{"name": "john", "domain": "getcodemail.com"}'

Response 201

{
  "success": true,
  "email": "john@getcodemail.com",
  "token": "a1b2c3d4e5f6...",
  "created_at": "2026-04-07 12:00:00"
}

Create a mailbox with a random username. No parameters needed.

curl -X POST https://getcodemail.com/api/v1/random

Response 201

{
  "success": true,
  "email": "xkwp4827@getcodemail.com",
  "token": "a1b2c3d4...",
  "created_at": "2026-04-07 12:00:00"
}

Check if a mailbox exists and how many emails it has.

curl https://getcodemail.com/api/v1/check/john@getcodemail.com

Response

{
  "success": true,
  "exists": true,
  "email_count": 3
}

Get inbox emails. Pass email in URL (no auth) or use token.

# By email address (no auth)
curl https://getcodemail.com/api/v1/inbox/john@getcodemail.com

# By token
curl https://getcodemail.com/api/v1/inbox -H "Authorization: Bearer your-token"

Response

{
  "success": true,
  "email": "john@getcodemail.com",
  "count": 1,
  "emails": [{
    "id": 42, "from_name": "GitHub",
    "subject": "Verify your email",
    "is_read": false, "received_at": "2026-04-07 12:05:00"
  }]
}

Read a specific email. Automatically marks as read.

# By email address (no auth)
curl https://getcodemail.com/api/v1/read/john@getcodemail.com/42

# By token
curl https://getcodemail.com/api/v1/read/42 -H "Authorization: Bearer your-token"

Response

{
  "success": true,
  "email": {
    "id": 42, "from_name": "GitHub",
    "subject": "Verify your email",
    "body_text": "Click to verify...",
    "body_html": "<p>Click...</p>",
    "attachments": []
  }
}

Permanently delete an email.

# By email address
curl -X DELETE https://getcodemail.com/api/v1/delete/john@getcodemail.com/42

# By token
curl -X DELETE https://getcodemail.com/api/v1/delete/42 -H "Authorization: Bearer your-token"

Send an email from your mailbox. Queued and delivered via SMTP.

curl -X POST https://getcodemail.com/api/v1/send \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "someone@gmail.com",
    "subject": "Hello from API",
    "body": "<h1>Hi!</h1><p>Sent via GetCodeMail API.</p>"
  }'

Response

{
  "success": true,
  "message": "Email queued for delivery",
  "from": "john@getcodemail.com",
  "to": ["someone@gmail.com"],
  "email_id": 123,
  "queue_id": 45
}

Get inbox emails for your authenticated mailbox.

curl https://getcodemail.com/api/v1/mailbox/inbox \
  -H "Authorization: Bearer your-token"

Response

{
  "success": true,
  "email": "john@getcodemail.com",
  "count": 2,
  "emails": [...]
}

Read a specific email from your authenticated mailbox.

curl https://getcodemail.com/api/v1/mailbox/read/42 \
  -H "Authorization: Bearer your-token"

Response

{
  "success": true,
  "email": {
    "id": 42, "subject": "...",
    "body_text": "...", "body_html": "...",
    "attachments": [...]
  }
}

{
  "success": false,
  "error": "Description of what went wrong"
}

import requests, time

API = "https://getcodemail.com/api/v1"

# 1. Create a temp mailbox
r = requests.post(f"{API}/random").json()
email, token = r["email"], r["token"]
print(f"Mailbox: {email}")

# 2. Poll for new emails
headers = {"Authorization": f"Bearer {token}"}
while True:
    inbox = requests.get(f"{API}/mailbox/inbox", headers=headers).json()
    if inbox["count"] > 0:
        eid = inbox["emails"][0]["id"]
        msg = requests.get(f"{API}/mailbox/read/{eid}", headers=headers).json()
        print(f"Subject: {msg['email']['subject']}")
        break
    time.sleep(5)

# 3. Send a reply
requests.post(f"{API}/send", headers=headers, json={
    "to": "someone@gmail.com",
    "subject": "Hello from API",
    "body": "<p>Sent via GetCodeMail API!</p>"
})