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.