Configuration

Webhooks

Webhooks deliver real-time event notifications to your server as HTTP POST requests.

Registering a Webhook

curl -X POST https://api.postmta.com/v1/webhooks -H "Authorization: Bearer pmta_live_xxxx" -H "Content-Type: application/json" -d '{"url":"https://yourapp.com/webhooks/postmta","events":["message.delivered","message.bounced","message.complained","message.opened","message.clicked"],"secret":"your_signing_secret"}'

Event Types

EventDescription
message.queuedMessage accepted into the queue
message.sentMessage handed off to the recipient MTA
message.deliveredMessage arrived in recipient inbox
message.bouncedHard or soft bounce received
message.complainedSpam complaint received
message.openedRecipient opened the email
message.clickedRecipient clicked a link

Payload Structure

{"id":"evt_01HXABC123DEF456","event":"message.delivered","timestamp":"2026-01-15T10:31:00Z","data":{"message_id":"msg_01HX5K9P7N3M4Q6R8T2V4W6Y8","to":"alice@example.com","from":"hello@mail.example.com","delivered_at":"2026-01-15T10:31:00Z"}}

Retry Logic

If your endpoint returns a non-2xx or times out, PostMTA retries with exponential backoff: 5 min, 30 min, 2 hr, 8 hr, 24 hr.

Best Practices