API reference
The base URL is https://api.postilon.com. Requests and responses are JSON, times are RFC 3339 in UTC, and IDs carry a prefix that says what they are (msg_ for emails, dom_ for domains). Authenticate every request with Authorization: Bearer <API key>; see Errors and limits for error codes.
API keys have one of two scopes: full access (every endpoint below) or sending access (only the /v1/emails endpoints).
Lists and deletes
Every list takes limit (default 100, at most 1000; request logs default to 50, at most 200) and offset, newest first, and answers with the same envelope:
{ "object": "list", "data": [ … ], "count": 100, "total": 1240, "has_more": true }
count is the number of items in this page and total the number that match; ask for the next page with offset increased by count while has_more is true. A DELETE answers {"deleted": true}, or 404 not_found when the id does not exist in the workspace.
Emails
| Method | Path | Description |
|---|---|---|
POST |
/v1/emails |
Send an email. See Send email. |
POST |
/v1/emails/batch |
Send up to 100 emails in one request. |
GET |
/v1/emails |
List emails, newest first. |
GET |
/v1/emails/{id} |
Get one email with its events. |
POST |
/v1/emails/{id}/cancel |
Cancel a queued or scheduled email. |
GET |
/v1/emails/export.csv |
Download emails as CSV. |
GET /v1/emails takes these query parameters:
| Parameter | Description |
|---|---|
limit, offset |
Page through results, such as ?limit=50&offset=100 (see Lists and deletes). |
status |
Only emails with this status, such as bounced. |
q |
Search the subject, ID, sender and recipients. |
source |
api or smtp. |
days |
Only emails created in the last N days. |
An email has these fields:
| Field | Description |
|---|---|
id |
msg_… |
from, to, cc, bcc, reply_to, subject |
As sent. |
html, text, attachments, variables, headers |
The content. Deleted 30 days after the email was created; content_purged_at then says when. |
template_id, tags |
As sent. |
status |
See Email status. |
environment |
live or test. |
transport |
rest_api, rest_api_batch or smtp_relay. |
credits_used |
Credits charged for it. |
dkim_signed |
Whether it was signed with your domain's DKIM key. |
events |
Its events: event_type, recipient, metadata, occurred_at. |
scheduled_at, sent_at, delivered_at, created_at |
Times. |
Emails, with their events, are deleted 90 days after they were created.
Domains
| Method | Path | Description |
|---|---|---|
POST |
/v1/domains |
Add a domain: {"domain_name": "acme.com"}. |
GET |
/v1/domains |
List domains. |
GET |
/v1/domains/{id} |
Get a domain with its DNS records. |
POST |
/v1/domains/{id}/verify |
Check its DNS records. |
PATCH |
/v1/domains/{id} |
Change open_tracking_enabled or click_tracking_enabled. |
DELETE |
/v1/domains/{id} |
Remove a domain. |
A domain has id, domain_name, status (pending or verified), dns_records (each with type, name, value, purpose and status), the tracking settings, verified_at and created_at. See Domains.
Templates
| Method | Path | Description |
|---|---|---|
POST |
/v1/templates |
Create a template. |
GET |
/v1/templates |
List templates. |
GET |
/v1/templates/{id} |
Get a template. |
PATCH |
/v1/templates/{id} |
Change a template. |
DELETE |
/v1/templates/{id} |
Delete a template. |
A template has name (required), subject_template, html_template, text_template and variables (the names it uses, for reference). See Templates.
Files
| Method | Path | Description |
|---|---|---|
POST |
/v1/files |
Upload an attachment: {"filename", "content_type", "content"} with Base64 content. |
GET |
/v1/files |
List files. |
DELETE |
/v1/files/{id} |
Delete a file. |
Attach an uploaded file to an email with {"file_id": "file_…"}.
Suppressions
Postilon does not send to suppressed addresses. Addresses are added when they hard-bounce (hard_bounce), mark an email as spam (complaint) or unsubscribe (unsubscribe), and you can add your own (manual).
| Method | Path | Description |
|---|---|---|
GET |
/v1/suppressions |
List suppressed addresses. |
POST |
/v1/suppressions |
Suppress an address: {"email_address": "jane@example.com"}. |
DELETE |
/v1/suppressions/{id} |
Remove a suppression (sup_…), so the address can be sent to again. |
Webhooks
| Method | Path | Description |
|---|---|---|
POST |
/v1/webhooks |
Add an endpoint: url, description, subscribed_events. |
GET |
/v1/webhooks |
List endpoints. |
GET |
/v1/webhooks/events |
List the event types. |
GET |
/v1/webhooks/{id} |
Get an endpoint. |
PATCH |
/v1/webhooks/{id} |
Change url, description, subscribed_events or is_active. |
DELETE |
/v1/webhooks/{id} |
Remove an endpoint. |
POST |
/v1/webhooks/{id}/test |
Send a webhook.test event. |
GET |
/v1/webhooks/deliveries |
Recent deliveries; filter with ?webhook_id=. |
POST |
/v1/webhooks/deliveries/{id}/replay |
Send a delivery again. |
See Webhooks for payloads and signatures.
API keys
| Method | Path | Description |
|---|---|---|
POST |
/v1/api-keys |
Create a key. |
GET |
/v1/api-keys |
List keys (without their secret). |
POST |
/v1/api-keys/{id}/revoke |
Revoke a key at once. |
DELETE |
/v1/api-keys/{id} |
Delete a key. |
Create a key with name (required), environment (live or test, default live), scope (full_access or sending_access, default full_access), and optionally expires_in_days and domain_id. A key with a domain_id can only send from that domain, through the API and the SMTP relay alike, and stops sending if the domain is removed. The response's token is the key itself; it is shown only once.
Credits
GET /v1/credits returns the workspace's credit balance, the next expiry and the live recipients sent in the last 24 hours. Credits are bought in the dashboard.