Getting Started

Authentication

PostMTA uses bearer token authentication. All API requests must include a valid API key in the Authorization header.

API Keys

Key Types

Prefix	Environment	Description
`pmta_test_`	Sandbox	Emails validated but not delivered. No billing.
`pmta_live_`	Production	Real email delivery. All sends are billable.

Key Scopes

Scope	Description
`messages:send`	Send transactional emails
`messages:read`	Read message status and details
`domains:manage`	Add, verify, and delete sending domains
`webhooks:manage`	Create and delete webhook endpoints
`ip-pools:manage`	Configure IP pools and warm-up
`analytics:read`	Read delivery and engagement analytics
`account:read`	Read account and billing information

Using API Keys

Authorization: Bearer pmta_live_xxxxxxxxxxxxxxxxxxxx

Never expose API keys in client-side code, public repositories, or logs. Rotate keys immediately if compromised.

IP Allowlisting

curl -X PUT https://api.postmta.com/v1/settings/security -H "Authorization: Bearer pmta_live_xxxx" -H "Content-Type: application/json" -d '{"allowed_ips":["203.0.113.0/24","198.51.100.14"]}'

Webhook Signature Verification

Every webhook request is signed using HMAC-SHA256. The signature is sent in the PostMTA-Signature header.