API reference
Overview
Base URL, authentication, pagination, idempotency, rate limits and errors.
Interactive reference
Try every endpoint with your test key.
Emails
Send, batch, look up, reschedule and cancel.
Domains
Add domains and check their DNS records.
Webhooks
Endpoints, secrets and deliveries.
Base URL and authentication
curl https://api.padimail.app/v1/account -H "Authorization: Bearer $PADIMAIL_API_KEY"const account = await new PadiMail(process.env.PADIMAIL_API_KEY).account.get();Use a pm_test_ key while you build: it behaves the same but never sends real email. See API keys.
Conventions
| Topic | Rule |
|---|---|
| Format | JSON in and out, snake_case, UTF-8 |
| Times | ISO 8601 with an offset (2026-10-27T14:05:00+01:00). Responses are in UTC (Z) |
| IDs | Prefixed strings (em_…, dom_…). Treat them as opaque |
| Pagination | ?limit=50 (up to 100) with after=<id> or before=<id>. Lists return { data, has_more, next }; pass next as after for the next page |
| Idempotency | Send Idempotency-Key on any POST. See Retries and idempotency |
| Rate limits | 10 requests a second per key, bursts to 20. Headers RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset; 429 adds Retry-After |
| Request IDs | Every response has X-Request-Id. Quote it to support |
| Versioning | /v1 only gains optional fields and new endpoints. Breaking changes would come as /v2, with 12 months' notice |
Errors
Every error has the same body, with a code from a fixed list. Each code's cause and fix are on the Errors page, which the doc_url in each error links to.
{ "error": { "type": "not_found", "code": "email_not_found", "message": "We couldn't find that email.", "doc_url": "https://padimail.dev/errors#email_not_found", "request_id": "req_01JB…" } }OpenAPI
The full description is at /openapi.json, for generating clients or importing into tools like Postman or Insomnia.
Was this page helpful?