Sending API
Checked November 9, 2026 against the provider's API reference.
- Auth:
X-Server-API-Keywith an API credential of the mail server. Requests are JSON POSTs; the legacy API answers HTTP 200 withstatussuccess, error or parameter-error. - Send:
POST {server}/api/v1/send/messagewithto,cc,bcc(up to 50 each),from,sender,reply_to,subject,plain_body,html_body,tag,headers,attachments(name,content_type,database64),bounce.send/rawtakes a whole RFC 2822 message. - Response:
data: { message_id, messages: { "<rcpt>": { id, token } } }. Error codes: NoRecipients, NoContent, TooManyToAddresses, FromAddressMissing, UnauthenticatedFromAddress, AttachmentMissingName, AttachmentMissingData, InvalidServerAPIKey, AccessDenied, ServerSuspended. - Status:
POST /api/v1/messages/deliverieswith the messageid: deliveries withstatusSent, SoftFail, HardFail, Held or Bounced,detailsandoutput. - Webhooks:
{ event, timestamp, payload, uuid }; events MessageSent, MessageDelayed, MessageDeliveryFailed, MessageHeld, MessageBounced, MessageLinkClicked, MessageLoaded, DomainDNSError. Signed with the server key:X-Postal-Signature-256(RSA SHA-256, base64, over the raw body) and the legacyX-Postal-Signature(SHA-1). - No suppression list API in the legacy HTTP API.
Using Postal (self-hosted) with OneSend
Connect it under Sending providers with the postal adapter and add it to a routing policy. See Sending providers.
Sources
Checked November 9, 2026.
- https://docs.postalserver.io/developer/api
- https://docs.postalserver.io/developer/webhooks
- https://github.com/postalserver/postal/blob/main/app/controllers/legacy_api/send_controller.rb
- https://github.com/postalserver/postal/blob/main/app/controllers/legacy_api/messages_controller.rb
- https://github.com/postalserver/postal/blob/main/lib/postal/http.rb
- https://github.com/postalserver/postal/blob/main/lib/postal/message_db/delivery.rb
Suggested citation
OneSend. "Postal (self-hosted)." Updated November 9, 2026. https://onesend.email/research/providers/postal/
Figures on this page are generated from the dataset and copied here unchanged.