API Reference

The Postscale API is organized around REST. Our API accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

Base URL

All API requests should be made to:

https://api.postscale.io/v1

Authentication

Authenticate your API requests by including your API key in the Authorization header:

Authorization: Bearer ps_live_your_api_key

See Authentication for more details on API keys.

Content Type

All requests must include the Content-Type header:

Content-Type: application/json

Response Format

Successful responses return JSON directly:

{
  "message_id": "a1b2c3d4@yourapp.com",
  "status": "queued"
}

Error responses include an error message:

{
  "error": "the 'to' field is required"
}

HTTP Status Codes

Status	Description
`200`	Success
`201`	Created
`202`	Accepted (email queued)
`400`	Bad Request — Invalid parameters
`401`	Unauthorized — Invalid or missing API key
`403`	Forbidden — Insufficient permissions or plan limit reached
`404`	Not Found — Resource doesn't exist
`409`	Conflict — Resource already exists
`422`	Unprocessable Entity — All recipients suppressed
`429`	Too Many Requests — Rate limit exceeded
`500`	Internal Server Error

Pagination

List endpoints support pagination via query parameters:

Parameter	Type	Description
`limit`	integer	Number of items per page (default: 50, max: 100)
`offset`	integer	Number of items to skip

Example:

GET /v1/emails?limit=50&offset=100

Rate Limits

Sending rate limits are managed through the domain warming system. See Warming for details on sending limits per warming phase.

Rate limit errors include details about the limit:

{
  "error": "rate_limit_exceeded",
  "message": "daily sending limit exceeded",
  "limit_type": "daily",
  "limit": 1500,
  "used": 1500,
  "retry_after_seconds": 3600,
  "warming_phase": "phase_1"
}

API Endpoints

The Postscale API is organized into these resource groups:

Emails (Send)

Method	Endpoint	Description
`POST`	`/v1/send`	Send an email
`POST`	`/v1/send/batch`	Send up to 100 emails
`GET`	`/v1/emails`	List sent emails
`GET`	`/v1/emails/:id`	Get email details

Inbound

Method	Endpoint	Description
`GET`	`/v1/inbound-emails`	List inbound emails
`GET`	`/v1/inbound-emails/:id`	Get inbound email

Shield Aliases

Method	Endpoint	Description
`POST`	`/v1/shield/aliases`	Create a Shield alias
`GET`	`/v1/shield/aliases`	List Shield aliases
`GET`	`/v1/shield/aliases/:id`	Get Shield alias details
`PUT`	`/v1/shield/aliases/:id`	Update a Shield alias
`DELETE`	`/v1/shield/aliases/:id`	Delete a Shield alias

Domain Aliases

Method	Endpoint	Description
`POST`	`/v1/domains/:id/aliases`	Create an alias for a domain
`GET`	`/v1/domains/:id/aliases`	List aliases for a domain
`GET`	`/v1/aliases/:id`	Get alias details
`PUT`	`/v1/aliases/:id`	Update an alias
`DELETE`	`/v1/aliases/:id`	Delete an alias

Domains

Method	Endpoint	Description
`POST`	`/v1/domains`	Add a domain
`GET`	`/v1/domains`	List domains
`GET`	`/v1/domains/:id`	Get domain details
`PUT`	`/v1/domains/:id`	Update a domain
`POST`	`/v1/domains/:id/verify`	Verify domain DNS
`GET`	`/v1/domains/:id/dns`	Get DNS records
`DELETE`	`/v1/domains/:id`	Remove a domain

Templates

Method	Endpoint	Description
`POST`	`/v1/templates`	Create a template
`GET`	`/v1/templates`	List templates
`GET`	`/v1/templates/:id`	Get template (by UUID or slug)
`PUT`	`/v1/templates/:id`	Update a template
`DELETE`	`/v1/templates/:id`	Delete a template
`POST`	`/v1/templates/:id/preview`	Preview rendered template

Webhooks

Method	Endpoint	Description
`POST`	`/v1/webhooks`	Create webhook endpoint
`GET`	`/v1/webhooks`	List webhook endpoints
`DELETE`	`/v1/webhooks/:id`	Delete webhook endpoint

DKIM

Method	Endpoint	Description
`POST`	`/v1/domains/:id/dkim`	Generate DKIM key
`GET`	`/v1/domains/:id/dkim`	Get DKIM records
`POST`	`/v1/domains/:id/dkim/rotate`	Rotate DKIM key
`POST`	`/v1/domains/:id/dkim/verify`	Verify DKIM DNS
`DELETE`	`/v1/domains/:id/dkim/:selector`	Deactivate DKIM key

DMARC

Method	Endpoint	Description
`GET`	`/v1/domains/:id/dmarc/summary`	Get DMARC summary stats
`GET`	`/v1/domains/:id/dmarc/sources`	Get source IP breakdown
`GET`	`/v1/domains/:id/dmarc/daily`	Get daily alignment data
`GET`	`/v1/domains/:id/dmarc/reports`	List aggregate reports
`GET`	`/v1/domains/:id/dmarc/reports/:reportId`	Get report with records
`GET`	`/v1/domains/:id/dmarc/address`	Get DMARC report address

Stats

Method	Endpoint	Description
`GET`	`/v1/domains/:id/stats`	Get aggregated statistics
`GET`	`/v1/domains/:id/stats/daily`	Get daily statistics
`GET`	`/v1/domains/:id/stats/hourly`	Get hourly statistics
`GET`	`/v1/domains/:id/stats/isp`	Get per-ISP statistics

Warming

Method	Endpoint	Description
`GET`	`/v1/domains/:id/warming`	Get warming status
`GET`	`/v1/domains/:id/warming/history`	Get warming history
`POST`	`/v1/domains/:id/warming/start`	Start warming
`POST`	`/v1/domains/:id/warming/pause`	Pause warming
`POST`	`/v1/domains/:id/warming/resume`	Resume warming

Suppressions

Method	Endpoint	Description
`GET`	`/v1/suppressions`	List suppression entries
`GET`	`/v1/suppressions/check`	Check if email is suppressed
`POST`	`/v1/suppressions`	Add to suppression list
`DELETE`	`/v1/suppressions/:email`	Remove from suppression list

API Keys

Method	Endpoint	Description
`POST`	`/v1/api-keys`	Create API key
`GET`	`/v1/api-keys`	List API keys
`GET`	`/v1/api-keys/:id`	Get API key
`PUT`	`/v1/api-keys/:id`	Update API key
`DELETE`	`/v1/api-keys/:id`	Revoke API key

SDKs

We provide official SDKs for popular languages. See SDKs & Libraries for installation and usage.