API reference
API keys
Create, list and revoke API keys. Needs a full-access key.
All requests go to https://api.padimail.app with Authorization: Bearer <your key>. Try these in the interactive reference with a pm_test_ key.
Create an API key (the token is shown once)
POST/v1/api-keys
Body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | |
mode | "live" | "test" | No | live sends real email; test never does. Default "live". |
permission | "full_access" | "sending_access" | No | full_access or sending_access (send, read and cancel emails only). full_access when left out, or sending_access when domain_id is set. |
domain_id | string | null | No | Restrict the key to sending from one domain. Restrict a sending_access key to one domain. Not allowed with full_access. |
Send an Idempotency-Key header to make retries safe. The Node SDK adds one for you.
Example
import { PadiMail } from "@padimail/node";
const pm = new PadiMail(process.env.PADIMAIL_API_KEY);
const result = await pm.apiKeys.create({ name: "Production server", permission: "sending_access" });Response 200
{
"id": "key_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S",
"object": "api_key",
"name": "string",
"mode": "live",
"permission": "full_access",
"domain_id": "dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S",
"prefix": "pm_live_7Hq2",
"last_used_at": "2026-10-27T13:05:09Z",
"created_by": "string",
"created_at": "2026-10-27T13:05:09Z",
"revoked_at": "2026-10-27T13:05:09Z",
"token": "pm_live_7Hq2…"
}List API keys
GET/v1/api-keys
Query parameters
| Field | Type | Required | Notes |
|---|---|---|---|
limit | integer | No | Page size, 1 to 100. Default 50. |
after | string | No | Return items after this ID (the next value of the previous page). |
before | string | No | Return items before this ID. |
Example
import { PadiMail } from "@padimail/node";
const pm = new PadiMail(process.env.PADIMAIL_API_KEY);
const result = await pm.apiKeys.list();Response 200
{
"data": [
{
"id": "key_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S",
"object": "api_key",
"name": "string",
"mode": "live",
"permission": "full_access",
"domain_id": "dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S",
"prefix": "pm_live_7Hq2",
"last_used_at": "2026-10-27T13:05:09Z",
"created_by": "string",
"created_at": "2026-10-27T13:05:09Z",
"revoked_at": "2026-10-27T13:05:09Z"
}
],
"has_more": false,
"next": "string"
}Revoke an API key (stops working within 60 s)
DELETE/v1/api-keys/{id}
Path parameters
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | Yes |
Example
import { PadiMail } from "@padimail/node";
const pm = new PadiMail(process.env.PADIMAIL_API_KEY);
const result = await pm.apiKeys.remove("key_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S");Response 200
{ "id": "string", "object": "string", "deleted": true }Was this page helpful?