API reference Base URL https://api.postilio.eu. Every request needs an API key: Authorization: Bearer pk_live_… (or pk_test_…), see Authentication . Errors are described in Errors and limits .
This page is generated from the OpenAPI document, which you can also download for a client generator.
Emails
Send an email POST /v1/emails
Needs the emails:send scope. Stores one message per recipient and answers 202 with their ids, in the order of to. A recipient on the suppression list is accepted but not sent, and listed in suppressed. The sender's domain must be verified. A test key (pk_test_) never sends: its messages get simulated events. In the sandbox, live mail goes only to the organization's members and verified domains (422 sandbox_recipient_not_allowed), within a daily and a per-minute limit (429 with Retry-After).
Parameters Name In Type Required Description Idempotency-Keyheader string no 1 to 256 characters. A repeat within 24 hours answers as the first request did, without sending again.
Request body SendEmailRequest
Field Type Required Description fromstring yes An address on a verified domain of the key's project, optionally with a display name (without '@' or ','). toarray of string yes 1 to 50 bare addresses, without display names; each gets a message of its own. subjectstring yes At most 998 characters, without control characters. textstring no The plain-text body; text, html or both. htmlstring no The HTML body; text, html or both. tagstring no Optional; at most 64 letters, digits, '-' or '_'. replyTostring no Optional; one address, with or without a display name. attachmentsarray of EmailAttachment no Optional; one with a contentId is inline, for cid: references in the HTML.
Responses Get an email and its events GET /v1/emails/{id}
Needs the emails:read scope. A test key finds only test messages and a live key only live ones; the other mode's are 404.
Parameters Name In Type Required Description idpath string (uuid) yes
Responses Domains
Add a sending domain POST /v1/domains
Needs the domains:manage scope. Answers the domain as pending, with the two CNAME records to create in its DNS. postilio.eu and names under it cannot be added. 409 domain_exists when the project has it already.
Request body CreateDomainRequest
Field Type Required Description namestring yes A host name of at least two labels, such as mail.example.com; not an IP address, not under postilio.eu.
Responses List sending domains GET /v1/domains
Needs the domains:manage scope.
Responses Get a sending domain GET /v1/domains/{id}
Needs the domains:manage scope.
Parameters Name In Type Required Description idpath string (uuid) yes
Responses Remove a sending domain DELETE /v1/domains/{id}
Needs the domains:manage scope. Mail from the domain stops at once.
Parameters Name In Type Required Description idpath string (uuid) yes
Responses Status Meaning Body 204No Content — 404Not Found —
Check a domain's DNS records now POST /v1/domains/{id}/check
Needs the domains:manage scope. Checks now instead of at the next periodic check (every 10 minutes) and answers the domain's new state. Once a minute per domain: 429 too_many_checks with Retry-After. 503 dns_unavailable when DNS gave no answer.
Parameters Name In Type Required Description idpath string (uuid) yes
Responses Suppressions
List suppressed addresses GET /v1/suppressions
Needs the suppressions:manage scope. Newest first; pass next as before for the next page.
Parameters Name In Type Required Description qquery string no Part of an address. reasonquery string no hard_bounce, complaint or manual.beforequery string (uuid) no The next of the previous page. limitquery integer (int32) no 1 to 100; 50 when left out.
Responses Suppress an address POST /v1/suppressions
Needs the suppressions:manage scope. Adds the address with reason manual. 409 address_already_suppressed when it is on the list already.
Request body CreateSuppressionRequest
Field Type Required Description addressstring yes One bare address, at most 254 characters.
Responses Remove a suppressed address DELETE /v1/suppressions/{id}
Needs the suppressions:manage scope. A complaint is removed only with a reason, {"reason": "…"} of 10 to 500 characters; without one the answer is 422 reason_required. A hard bounce or manual entry needs no body.
Parameters Name In Type Required Description idpath string (uuid) yes
Request body (optional) RemoveSuppressionRequest
Field Type Required Description reasonstring no Required, at least 10 characters, when the entry is a complaint; kept with the removal.
Responses Webhooks
List webhook endpoints GET /v1/webhooks
Needs the webhooks:manage scope.
Responses Add a webhook endpoint POST /v1/webhooks
Needs the webhooks:manage scope. The answer holds the signing secret, the only time it is shown. At most 10 endpoints per project: 409 webhook_endpoint_limit_reached.
Request body CreateWebhookEndpointRequest
Field Type Required Description urlstring yes An absolute https:// URL on a public address, at most 2048 characters, without credentials or a fragment. eventsarray of string yes One or more of: accepted, queued, delivered, deferred, bounced, expired, complained, suppressed. descriptionstring no Optional; at most 200 characters. modestring no live (the default) or test.
Responses Get a webhook endpoint GET /v1/webhooks/{id}
Needs the webhooks:manage scope.
Parameters Name In Type Required Description idpath string (uuid) yes
Responses Change a webhook endpoint PATCH /v1/webhooks/{id}
Needs the webhooks:manage scope. Only the fields you send change. paused: false resumes a paused endpoint.
Parameters Name In Type Required Description idpath string (uuid) yes
Request body UpdateWebhookEndpointRequest
Field Type Required Description urlstring no eventsarray of string no descriptionstring no An empty string removes it. pausedboolean no true pauses the endpoint, false resumes it.
Responses Remove a webhook endpoint DELETE /v1/webhooks/{id}
Needs the webhooks:manage scope.
Parameters Name In Type Required Description idpath string (uuid) yes
Responses Status Meaning Body 204No Content — 404Not Found —
Rotate the signing secret POST /v1/webhooks/{id}/secret
Needs the webhooks:manage scope. Answers the new secret once. The old one keeps signing as well for 24 hours.
Parameters Name In Type Required Description idpath string (uuid) yes
Responses Send a test event POST /v1/webhooks/{id}/test
Needs the webhooks:manage scope. One webhook.test.v1 delivery, tried once without retries, also to a paused endpoint.
Parameters Name In Type Required Description idpath string (uuid) yes
Responses List an endpoint's deliveries GET /v1/webhooks/{id}/deliveries
Needs the webhooks:manage scope. Newest first; pass next as before for the next page.
Parameters Name In Type Required Description idpath string (uuid) yes statusquery string no pending, delivered or failed.beforequery string (uuid) no The next of the previous page. limitquery integer (int32) no 1 to 100; 50 when left out.
Responses Retry a delivery POST /v1/webhooks/{id}/deliveries/{deliveryId}/retry
Needs the webhooks:manage scope. One more attempt now, with the same id and payload. 409 delivery_still_pending while it is still being retried, endpoint_paused while the endpoint is paused.
Parameters Name In Type Required Description idpath string (uuid) yes deliveryIdpath string (uuid) yes
Responses Status Meaning Body 202Accepted — 404Not Found — 409Conflict ErrorResponse
Schemas
CreateDomainRequest
Field Type Required Description namestring yes A host name of at least two labels, such as mail.example.com; not an IP address, not under postilio.eu.
CreatedWebhookEndpoint
Field Type Required Description endpointWebhookEndpointResponse yes secretstring yes The signing secret (whsec_…). Shown once: it is stored encrypted and never returned again.
CreateSuppressionRequest
Field Type Required Description addressstring yes One bare address, at most 254 characters.
CreateWebhookEndpointRequest
Field Type Required Description urlstring yes An absolute https:// URL on a public address, at most 2048 characters, without credentials or a fragment. eventsarray of string yes One or more of: accepted, queued, delivered, deferred, bounced, expired, complained, suppressed. descriptionstring no Optional; at most 200 characters. modestring no live (the default) or test.
DnsRecord
Field Type Required Description typestring yes namestring yes valuestring yes statusstring yes found, missing, or unknown until the first check.
DomainList
A list in an object, so paging can be added without breaking clients.
DomainResponse
Field Type Required Description idstring (uuid) yes namestring yes statusstring yes pending, verified or failing. checkedAtstring (date-time) or null yes recordsarray of DnsRecord yes createdAtstring (date-time) yes addedBystring or null yes The name of the dashboard user who added it; null when it was added with an API key. failingSincestring (date-time) or null yes Since when its records are missing, while it is failing. sent30dinteger (int32) yes Live messages sent from it today and the 29 days before (UTC); test and suppressed ones not.
EmailAttachment
Field Type Required Description fileNamestring yes contentTypestring yes A MIME type such as application/pdf, optionally with parameters. contentstring yes The file, base64-encoded. contentIdstring no Makes the attachment inline; the HTML refers to it as cid: plus this value.
EmailDetails
Field Type Required Description idstring (uuid) yes statusstring yes fromstring yes tostring yes subjectstring or null yes tagstring or null yes acceptedAtstring (date-time) yes testboolean yes eventsarray of EmailEvent yes viastring yes api or smtp: how the message was submitted.
EmailEvent
Field Type Required Description typestring yes occurredAtstring (date-time) yes smtpCodeinteger (int16) or null yes responsestring or null yes attemptinteger (int16) or null no remoteHoststring or null no enhancedCodestring or null no classificationstring or null no
ErrorResponse
Field Type Required Description errorstring yes
HttpValidationProblemDetails
Field Type Required Description typestring or null no titlestring or null no statusinteger (int32) or null no detailstring or null no instancestring or null no errorsmap of array of string no
RemoveSuppressionRequest
Field Type Required Description reasonstring no Required, at least 10 characters, when the entry is a complaint; kept with the removal.
RotatedWebhookSecret
Field Type Required Description secretstring yes The new signing secret, shown once. previousSecretExpiresAtstring (date-time) yes Until then deliveries are signed with the old secret as well.
SendEmailRequest
Field Type Required Description fromstring yes An address on a verified domain of the key's project, optionally with a display name (without '@' or ','). toarray of string yes 1 to 50 bare addresses, without display names; each gets a message of its own. subjectstring yes At most 998 characters, without control characters. textstring no The plain-text body; text, html or both. htmlstring no The HTML body; text, html or both. tagstring no Optional; at most 64 letters, digits, '-' or '_'. replyTostring no Optional; one address, with or without a display name. attachmentsarray of EmailAttachment no Optional; one with a contentId is inline, for cid: references in the HTML.
SendEmailResponse
Field Type Required Description idsarray of string (uuid) yes One message per recipient, in the order of to. suppressedarray of string yes Recipients on the project's suppression list: accepted with status suppressed, not sent.
SuppressionList
Field Type Required Description dataarray of SuppressionResponse yes nextstring (uuid) or null yes Pass as before for the next page; null on the last page.
SuppressionResponse
Field Type Required Description idstring (uuid) yes addressstring yes reasonstring yes hard_bounce, complaint or manual.detailstring or null yes The remote server's answer for a bounce, or who added it. sourceMessageIdstring (uuid) or null yes The message that caused it; it may already be gone from the log. createdAtstring (date-time) yes
UpdateWebhookEndpointRequest
Every field is optional; what is left out stays as it is.
Field Type Required Description urlstring no eventsarray of string no descriptionstring no An empty string removes it. pausedboolean no true pauses the endpoint, false resumes it.
WebhookDeliveryList
Field Type Required Description dataarray of WebhookDeliveryResponse yes nextstring (uuid) or null yes Pass as before for the next page; null on the last page.
WebhookDeliveryResponse
Field Type Required Description idstring (uuid) yes eventIdstring (uuid) yes The webhook-id header: the same for every attempt. typestring yes The payload type, e.g. email.delivered.v1. emailIdstring (uuid) or null yes tostring or null yes statusstring yes pending, delivered or failed.attemptsinteger (int32) yes lastAttemptAtstring (date-time) or null yes lastStatusCodeinteger (int32) or null yes lastErrorstring or null yes lastDurationMsinteger (int32) or null yes responseSnippetstring or null yes The start of the last response body, at most 256 characters. nextAttemptAtstring (date-time) or null yes Set while pending. createdAtstring (date-time) yes
WebhookEndpointResponse
Field Type Required Description idstring (uuid) yes urlstring yes descriptionstring or null yes eventsarray of string yes The message events it gets: accepted, queued, delivered, deferred, bounced, expired, complained, suppressed. modestring yes live, or test: a test endpoint gets the events of test-key messages only.pausedboolean yes pauseReasonstring or null yes pausedAtstring (date-time) or null yes failingSincestring (date-time) or null yes Every attempt since then failed; after 72 hours of that the endpoint is paused. secretHintstring yes The last characters of the signing secret. previousSecretExpiresAtstring (date-time) or null yes Until then the secret from before the last rotation still signs as well. createdAtstring (date-time) yes lastDeliveryany yes
WebhookLastDelivery
Field Type Required Description atstring (date-time) yes When the attempt was made. statusCodeinteger (int32) or null yes The receiver's HTTP status; null when no answer came (timeout, refused, blocked address). statusstring yes The delivery's status now: pending (to be retried), delivered or failed.