intermediate ⏱ 5 minutes

Developer API Quickstart

Get started with the Pokemail REST API in 5 minutes. Create temp addresses, read emails, and set up webhooks programmatically.

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

To own an email, sign up by becoming a member. Choose the API when you register, or add it from your dashboard. Make your key on the dashboard and save it - 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": "m4x8qt+a91c07e2b5d3f@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
  }
}

The list holds up to 20 emails; count is how many the inbox holds, and ?offset=20 gives the next 20.

Step 4: Read an Email

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

curl "https://pokemail.app/api/v1/email/em_abc123?address=rjxwhgf%40pokemail.app" \
  -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}?address=${encodeURIComponent(address)}`,
    { 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']}",
        params={"address": address},
        headers=HEADERS,
    ).json()
    print(f"From: {email['data']['email']['from']}")
    print(f"Subject: {email['data']['email']['subject']}")

Setting Up Webhooks (Premium and Pro)

Instead of polling, a key with the Premium or Pro add-on 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 - it is shown only once; use it to verify webhook signatures.

Rate Limits

Each add-on has a daily call allowance: every request counts as one call, whatever it does, and the count starts again at 00:00 UTC. A per-minute limit also applies, and Pro’s is higher. Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining) are included in every response, and GET /api/v1/usage shows today’s calls.

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 EMAIL_NOT_FOUND on an address whose hour has passed by creating a new address.

Next Steps

Your key, today’s calls and your add-on are on your dashboard; GET /api/v1/usage and GET /api/v1/domains give today’s calls and the domains your key can use.