Developer API Quickstart

This guide gets you from zero to reading emails programmatically in under five minutes. You’ll create a temporary address, receive an email at it, and read the contents through the API.

Prerequisites

You’ll need an API key from a Pokemail API Starter ($4.99/mo) or API Pro ($14.99/mo) subscription. Subscribe on the pricing page and save the API key shown after payment — it’s displayed only once.

Step 1: Create an Address

curl -X POST https://pokemail.app/api/v1/addresses \
  -H "Authorization: Bearer pk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"domain": "pokemail.app"}'

Response:

{
  "ok": true,
  "data": {
    "address": "rjxwhgf@pokemail.app",
    "alias": "sxk9m2p@pokemail.app",
    "domain": "pokemail.app",
    "ttl": 3600
  }
}

Save the address value. You’ll use it to check the inbox.

Step 2: Use the Address

Send a test email to the address you just created, or use it to sign up for a website. For testing, you can use any email service to send a message to rjxwhgf@pokemail.app.

Step 3: Read the Inbox

Wait a few seconds for the email to arrive, then fetch the inbox:

curl https://pokemail.app/api/v1/inbox/rjxwhgf%40pokemail.app \
  -H "Authorization: Bearer pk_live_your_key_here"

Response:

{
  "ok": true,
  "data": {
    "address": "rjxwhgf@pokemail.app",
    "emails": [
      {
        "id": "em_abc123",
        "from": "test@example.com",
        "subject": "Test message",
        "receivedAt": 1716478200,
        "platform": null
      }
    ],
    "count": 1,
    "ttl": 3542
  }
}

Step 4: Read an Email

Use the email id from the inbox response to fetch the full content:

curl https://pokemail.app/api/v1/email/em_abc123 \
  -H "Authorization: Bearer pk_live_your_key_here"

The response includes bodyText (plain text) and bodyHtml (sanitized HTML).

JavaScript Example

Here’s a complete example using Node.js:

const API_KEY = process.env.POKEMAIL_API_KEY;
const BASE = "https://pokemail.app/api/v1";

async function createAndReadInbox() {
  // Create address
  const createRes = await fetch(`${BASE}/addresses`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ domain: "pokemail.app" }),
  });
  const { data: { address } } = await createRes.json();
  console.log(`Inbox created: ${address}`);

  // Wait for email (poll every 3 seconds, up to 60s)
  let emails = [];
  for (let i = 0; i < 20; i++) {
    await new Promise(r => setTimeout(r, 3000));
    const inboxRes = await fetch(
      `${BASE}/inbox/${encodeURIComponent(address)}`,
      { headers: { "Authorization": `Bearer ${API_KEY}` } }
    );
    const inbox = await inboxRes.json();
    if (inbox.data.count > 0) {
      emails = inbox.data.emails;
      break;
    }
  }

  if (emails.length === 0) {
    console.log("No emails received within timeout.");
    return;
  }

  // Read first email
  const emailRes = await fetch(
    `${BASE}/email/${emails[0].id}`,
    { headers: { "Authorization": `Bearer ${API_KEY}` } }
  );
  const email = await emailRes.json();
  console.log(`From: ${email.data.email.from}`);
  console.log(`Subject: ${email.data.email.subject}`);
  console.log(`Body: ${email.data.email.bodyText}`);
}

createAndReadInbox();

Python Example

import requests
import time
import os

API_KEY = os.environ["POKEMAIL_API_KEY"]
BASE = "https://pokemail.app/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# Create address
res = requests.post(
    f"{BASE}/addresses",
    headers=HEADERS,
    json={"domain": "pokemail.app"},
)
address = res.json()["data"]["address"]
print(f"Inbox created: {address}")

# Poll for emails
emails = []
for _ in range(20):
    time.sleep(3)
    inbox = requests.get(
        f"{BASE}/inbox/{requests.utils.quote(address)}",
        headers=HEADERS,
    ).json()
    if inbox["data"]["count"] > 0:
        emails = inbox["data"]["emails"]
        break

if not emails:
    print("No emails received within timeout.")
else:
    email = requests.get(
        f"{BASE}/email/{emails[0]['id']}",
        headers=HEADERS,
    ).json()
    print(f"From: {email['data']['email']['from']}")
    print(f"Subject: {email['data']['email']['subject']}")

Setting Up Webhooks (API Pro)

Instead of polling, API Pro subscribers can receive push notifications:

curl -X POST https://pokemail.app/api/v1/webhooks \
  -H "Authorization: Bearer pk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["new_email"]
  }'

Save the secret from the response — use it to verify webhook signatures. See the API docs for the full webhook payload format and signature verification.

Rate Limits

API Starter allows 60 requests per minute and 1,000 addresses per day. API Pro allows 120 requests per minute and 10,000 addresses per day. Rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response.

Error Handling

All error responses follow the same format:

{
  "ok": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Try again in 42 seconds."
  }
}

Always check the ok field before accessing data. Handle RATE_LIMITED errors with exponential backoff, and SESSION_EXPIRED errors by creating a new address.

Next Steps

For the complete endpoint reference, visit the API documentation. For questions or issues, email support@pokemail.app.