Sending Email

The core of PostMTA: delivering your emails to recipients inboxes with high deliverability.

Send a Message

curl -X POST https://api.postmta.com/v1/messages/send -H "Authorization: Bearer pmta_live_xxxx" -H "Content-Type: application/json" -d '{"from":{"address":"hello@mail.example.com","name":"Example Inc"},"to":[{"address":"alice@example.com","name":"Alice"}],"subject":"Your order confirmation","html":"
Order Confirmed
Hi Alice, your order #12345 has shipped.
","headers":{"X-Order-ID":"12345"}}'

Batch Send

Send to multiple recipients in a single API call (up to 1,000 per call):

{"from":{"address":"newsletter@mail.example.com"},"to":[{"address":"alice@example.com","substitutions":{"name":"Alice"}},{"address":"bob@example.com","substitutions":{"name":"Bob"}}],"subject":"Your monthly update","html":"
Hi {name}, here is your monthly update.
"}

Priority and Queuing

Messages are processed in priority order (1-10, highest first). Default is 5. Higher priority messages skip ahead in the queue.

Scheduled Sending

{"from":{"address":"hello@mail.example.com"},"to":[{"address":"alice@example.com"}],"subject":"Scheduled email","html":"...","send_at":"2026-01-20T09:00:00Z"}

Attachments

Attach files up to 25 MB each (10 attachments max):

{"from":{"address":"docs@company.com"},"to":[{"address":"alice@example.com"}],"subject":"Your invoice","html":"Please find your invoice attached.","attachments":[{"filename":"invoice-12345.pdf","content":"JVBERi0...","content_type":"application/pdf"}]}

Idempotency

Include an idempotency key to safely retry sends without duplicating:

curl -X POST https://api.postmta.com/v1/messages/send -H "Authorization: Bearer pmta_live_xxxx" -H "Idempotency-Key: order-12345-confirmation" -H "Content-Type: application/json" ...

If the same key is used within 24 hours, the original response is returned without creating a new message.