API reference
Domains
Add your own domains, read their DNS records and check them.
All requests go to https://api.padimail.app with Authorization: Bearer <your key>. Try these in the interactive reference with a pm_test_ key.
Add a domain
POST/v1/domains
Body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | The domain or subdomain you'll send from, like acme.ng or mail.acme.ng. |
region | string | No | Default "default". |
open_tracking | boolean | No | Track opens with a pixel. |
click_tracking | boolean | No | Rewrite links to track clicks. |
mail_from_subdomain | string | No | The bounce subdomain. Default bounce. |
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.domains.create({ name: "acme.ng" });Response 200
{
"id": "dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S",
"object": "domain",
"name": "string",
"status": "pending",
"region": "string",
"mail_from_subdomain": "string",
"tracking_subdomain": "string",
"open_tracking": false,
"click_tracking": false,
"created_at": "2026-10-27T13:05:09Z",
"verified_at": "2026-10-27T13:05:09Z",
"last_checked_at": "2026-10-27T13:05:09Z",
"records": [
{
"purpose": "dkim",
"type": "TXT",
"host": "string",
"value": "string",
"priority": 0,
"required": false,
"status": "not_found",
"found_value": "string",
"checked_at": "2026-10-27T13:05:09Z"
}
]
}List domains
GET/v1/domains
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.domains.list();Response 200
{
"data": [
{
"id": "dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S",
"object": "domain",
"name": "string",
"status": "pending",
"region": "string",
"mail_from_subdomain": "string",
"tracking_subdomain": "string",
"open_tracking": false,
"click_tracking": false,
"created_at": "2026-10-27T13:05:09Z",
"verified_at": "2026-10-27T13:05:09Z",
"last_checked_at": "2026-10-27T13:05:09Z",
"records": [
{
"purpose": "dkim",
"type": "TXT",
"host": "string",
"value": "string",
"priority": 0,
"required": false,
"status": "not_found",
"found_value": "string",
"checked_at": "2026-10-27T13:05:09Z"
}
]
}
],
"has_more": false,
"next": "string"
}Get a domain with its DNS records
GET/v1/domains/{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.domains.get("dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S");Response 200
{
"id": "dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S",
"object": "domain",
"name": "string",
"status": "pending",
"region": "string",
"mail_from_subdomain": "string",
"tracking_subdomain": "string",
"open_tracking": false,
"click_tracking": false,
"created_at": "2026-10-27T13:05:09Z",
"verified_at": "2026-10-27T13:05:09Z",
"last_checked_at": "2026-10-27T13:05:09Z",
"records": [
{
"purpose": "dkim",
"type": "TXT",
"host": "string",
"value": "string",
"priority": 0,
"required": false,
"status": "not_found",
"found_value": "string",
"checked_at": "2026-10-27T13:05:09Z"
}
]
}Change tracking settings
PATCH/v1/domains/{id}
Path parameters
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | Yes |
Body
| Field | Type | Required | Notes |
|---|---|---|---|
open_tracking | boolean | No | |
click_tracking | boolean | No | |
tracking_subdomain | string | null | No |
Example
import { PadiMail } from "@padimail/node";
const pm = new PadiMail(process.env.PADIMAIL_API_KEY);
const result = await pm.domains.update("dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S", { open_tracking: true, click_tracking: true });Response 200
{
"id": "dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S",
"object": "domain",
"name": "string",
"status": "pending",
"region": "string",
"mail_from_subdomain": "string",
"tracking_subdomain": "string",
"open_tracking": false,
"click_tracking": false,
"created_at": "2026-10-27T13:05:09Z",
"verified_at": "2026-10-27T13:05:09Z",
"last_checked_at": "2026-10-27T13:05:09Z",
"records": [
{
"purpose": "dkim",
"type": "TXT",
"host": "string",
"value": "string",
"priority": 0,
"required": false,
"status": "not_found",
"found_value": "string",
"checked_at": "2026-10-27T13:05:09Z"
}
]
}Delete a domain; its scheduled emails are canceled
DELETE/v1/domains/{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.domains.remove("dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S");Response 200
{ "id": "string", "object": "string", "deleted": true }Check the DNS records now (at most once a minute)
POST/v1/domains/{id}/verify
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.domains.verify("dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S");Response 200
{
"id": "dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S",
"object": "domain",
"name": "string",
"status": "pending",
"region": "string",
"mail_from_subdomain": "string",
"tracking_subdomain": "string",
"open_tracking": false,
"click_tracking": false,
"created_at": "2026-10-27T13:05:09Z",
"verified_at": "2026-10-27T13:05:09Z",
"last_checked_at": "2026-10-27T13:05:09Z",
"records": [
{
"purpose": "dkim",
"type": "TXT",
"host": "string",
"value": "string",
"priority": 0,
"required": false,
"status": "not_found",
"found_value": "string",
"checked_at": "2026-10-27T13:05:09Z"
}
]
}Was this page helpful?