Temply API

Base URL

All API requests should be made to:

https://temply.fun/

Authentication

All requests require one header:

Authorization: Bearer <your api key>

Find your API key in the Dashboard → Overview. Keep it secret.

DNS Records for Custom Domains

When adding your own domain, you need to add three DNS records at your registrar or DNS provider (Cloudflare, etc.). All mail is receive-only — we never send from your domain. These records are also shown in the Dashboard → Domains → DNS Setup modal after you add a domain.

The DKIM signature is unique to your domain and is generated automatically when you add it. The exact value is displayed in the Dashboard DNS Setup modal.

/api/v1/generate

Generates (and registers) a new inbox address. If the address already exists it is returned as-is. You can use any Temply system domain or one of your own verified domains as the target.

Python Example:

import requests

url = "https://temply.fun/api/v1/generate"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

# System domain
r1 = requests.get(url, headers=headers, params={"user": "alice", "domain": "temply.fun"})
print(r1.json()['email'])  # alice@temply.fun

# Your own verified domain
r2 = requests.get(url, headers=headers, params={"user": "signup", "domain": "yourdomain.com"})
print(r2.json()['email'])  # signup@yourdomain.com

# With subdomain
r3 = requests.get(url, headers=headers, params={"domain": "yourdomain.com", "subdomain": "test"})
print(r3.json()['email'])  # <random>@test.yourdomain.com

Response:

{
  "success": true,
  "email": "signup@yourdomain.com"
}

/api/v1/messages

Returns all messages for an inbox — works for system domains and your own verified domains equally.

Python Example:

import requests

url = "https://temply.fun/api/v1/messages"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
params = {"email": "signup@yourdomain.com"}

response = requests.get(url, headers=headers, params=params)
for msg in response.json().get('messages', []):
    print(f"From: {msg['sender_email']} | Subject: {msg['subject']}")

Response:

{
  "success": true,
  "messages": [
    {
      "id": 42,
      "sender_email": "noreply@example.com",
      "recipient_email": "signup@yourdomain.com",
      "subject": "Welcome!",
      "body": "Hello there...",
      "created_at": "2025-01-01T12:00:00.000Z"
    }
  ]
}

/api/v1/wait

Blocks until a new message arrives, then returns it immediately. Max wait is 120 seconds. Ideal for catching verification emails in automation flows.

Python Example:

import requests

url = "https://temply.fun/api/v1/wait"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
params = {"email": "signup@yourdomain.com", "timeout": 90}

response = requests.get(url, headers=headers, params=params)
if response.status_code == 200:
    print(f"Got: {response.json()['message']['subject']}")
elif response.status_code == 408:
    print("Timed out — no email received")

Success Response:

{
  "success": true,
  "message": {
    "id": 42,
    "sender_email": "verify@example.com",
    "recipient_email": "signup@yourdomain.com",
    "subject": "Your verification code",
    "body": "Your code is 123456",
    "created_at": "2025-01-01T12:00:00.000Z"
  }
}

Timeout Response (408):

{ "error": "Timeout: no message received within the specified wait time" }

/api/v1/inbox

Deletes all messages for a given address. Works on both system and your own domains. The inbox address itself stays registered.

Python Example:

import requests

url = "https://temply.fun/api/v1/inbox"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
params = {"email": "signup@yourdomain.com"}

response = requests.delete(url, headers=headers, params=params)
print(response.json())  # {"success": true}

/api/v1/domains

Returns all domains you can generate inboxes on: Temply system domains, public domains added by other users, and your own verified domains. Your own domains are marked with "is_mine": true.

Python Example:

import requests

url = "https://temply.fun/api/v1/domains"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.get(url, headers=headers)
for d in response.json()['domains']:
    tag = " ★ yours" if d.get('is_mine') else ""
    print(f"{d['domain']}{tag}")

Response:

{
  "success": true,
  "domains": [
    {
      "domain": "temply.fun",
      "force_subdomain": false,
      "allowed_subdomains": null,
      "is_mine": false
    },
    {
      "domain": "yourdomain.com",
      "force_subdomain": false,
      "allowed_subdomains": null,
      "is_mine": true
    }
  ]
}

Pass any domain value from this list (including your own) to the /generate endpoint.