Overview
Postmark is a transactional email API focused on deliverability and minimal latency. The Automize connector covers send (single, batch, template, batch-template), templates CRUD, bounces, suppressions, message search, and engagement (opens / clicks) metadata.
- Regions: Single global API at api.postmarkapp.com. SOC 2 Type II certified. Servers can be tagged with a region preference but sending IPs are US-based.
- Plans: Pay-as-you-go pricing tied to monthly volume. No free tier – the 100-email developer credit covers a sandbox-style trial. Dedicated IPs are an add-on.
Setting up the connection
Auth type: API Key.
- In Postmark, create a Server (one per transactional 'stream' you want to keep separate – e.g. one for 'app', one for 'marketing').
- On the server's API Tokens tab, copy the Server API Token.
- Paste it as the API key. Connector sends X-Postmark-Server-Token on every request.
- Account API Token (for account-wide ops like creating servers) is separate – not used by this connector.
Find your credentials at https://account.postmarkapp.com/servers.
Rate limits
No documented per-second cap on send; in practice the API handles 300+ req/sec per server cleanly. Send Batch / Send Batch Template accept up to 500 messages/request – use these instead of looping Send Email for bulk runs.
Data model
Postmark organises sending into Servers and Message Streams:
Account
├─ Servers (one Server API Token each)
│ ├─ Message Streams
│ │ ├─ outbound (transactional, default)
│ │ ├─ broadcast (marketing / bulk)
│ │ └─ inbound (parsing incoming mail)
│ ├─ Templates (HTML + Mustache, per-server)
│ ├─ Bounces / Suppressions
│ └─ Messages (queryable for 45 days)
├─ Sender Signatures (verified From: addresses)
└─ Domains (DKIM-signed for SPF/DKIM/return-path)
Each Server has its own templates, suppressions, and webhooks –
cross-server reads return 404. The token in this credential is the
Server API Token (32-char GUID, shown on the server's API Tokens
tab). The Account Token (account-wide ops) is separate and not used.
Suppression vs Bounce semantics:
Bounces are individual delivery failures (HardBounce, SoftBounce,
Transient, Unsubscribe, SpamComplaint, AutoResponder, ...). Hard
bounces, spam complaints, and unsubscribes auto-create a
Suppression – Postmark refuses to send to suppressed addresses
with HTTP 406. Activate Bounce removes the suppression.
Identifiers:
MessageID UUID, returned on every send
TemplateId integer; TemplateAlias is the human-friendly name
Tag single string per message
Metadata dict, up to 25 keys, 50 chars value eachAvailable operations
16 operations available. Click any row to jump to its detail.
| Operation | Category | What it does |
|---|---|---|
| Activate Bounce | General | Reactivate a bounced address so it can receive mail again |
| Create Template | General | Create a new template |
| Get Outbound Message | General | Get details for a sent message |
| Get Message Clicks | General | List click events for a message |
| Get Message Opens | General | List open events for a message |
| Get Outbound Stats | General | Get outbound delivery statistics |
| Get Template | General | Get a template by id or alias |
| List Bounces | General | List bounced emails |
| List Outbound Messages | General | Search/list outbound messages |
| List Suppressions | General | List suppressed addresses for a stream |
| List Templates | General | List available templates |
| Send Batch | General | Send up to 500 emails in one call |
| Send Batch With Template | General | Send a batch of templated emails |
| Send Email | General | Send a single transactional email |
| Send With Template | General | Send an email using a Postmark template |
| Update Template | General | Update a template |
Operations
Activate Bounce
Reactivate a bounced address so it can receive mail again
| Parameter | Required | Type | Description |
|---|---|---|---|
Bounce Id bounce_id | Yes | text |
Tips
- Removes a recipient from the suppression list. ONLY use when you've confirmed (e.g. the user fixed their inbox) – re-suppression on next bounce is automatic.
Create Template
Create a new template
| Parameter | Required | Type | Description |
|---|---|---|---|
Name Name | No | text | |
Subject Subject | No | text | |
Htmlbody HtmlBody | No | text | |
Textbody TextBody | No | text | |
Alias Alias | No | text | |
Templatetype TemplateType | No | text | |
Layouttemplate LayoutTemplate | No | text |
Tips
- POST /templates – body: Name, Alias (slug, 100 char max), Subject, HtmlBody/TextBody (Mustachio templating), TemplateType, LayoutTemplate (alias of a Layout, if you're using Layouts).
- Aliases must be unique within the server. Duplicate alias returns 422; pick a different one or update the existing template.
Get Outbound Message
Get details for a sent message
| Parameter | Required | Type | Description |
|---|---|---|---|
Message Id message_id | Yes | text |
Tips
- GET /messages/outbound/{messageid}/details – full sent-message detail including recipients, status (sent|queued|deferred|failed), and Postmark's processing trace.
- Available for 45 days; older messages return 404.
Get Message Clicks
List click events for a message
| Parameter | Required | Type | Description |
|---|---|---|---|
Message Id message_id | Yes | text |
Tips
- Click events for a specific MessageID. Each entry has the original_link, click_location (HTML|Text), platform, and timestamp.
- Click tracking must be enabled on the template/send (TrackLinks='HtmlAndText'|'HtmlOnly') – without it, opens still record but clicks don't.
Get Message Opens
List open events for a message
| Parameter | Required | Type | Description |
|---|---|---|---|
Message Id message_id | Yes | text |
Tips
- Returns open events for a specific message. Counts are cookie-pixel based – Apple Mail Privacy Protection pre-loads pixels and inflates opens; treat as directional, not exact.
Get Outbound Stats
Get outbound delivery statistics
No input parameters.
Tips
- GET /stats/outbound – aggregate counters for sent / bounced / clicks / opens / spam complaints per fromdate-todate range.
- Filter by tag= for cost / campaign attribution. messagestream= scopes to a specific stream (default: outbound).
Get Template
Get a template by id or alias
| Parameter | Required | Type | Description |
|---|---|---|---|
Template Id template_id | Yes | text |
Tips
- GET /templates/{id_or_alias} – full body. Returned fields include Subject + HtmlBody + TextBody + AssociatedServerId.
- Alias is preferred for cross-server portability; ID is server-specific.
List Bounces
List bounced emails
No input parameters.
Tips
- type=HardBounce | Transient | Unsubscribe | SpamComplaint. Hard bounces auto-suppress (recipient is 'Inactive'); transients don't.
- fromdate/todate in YYYY-MM-DD UTC. Default returns recent 500.
List Outbound Messages
Search/list outbound messages
No input parameters.
Tips
- GET /messages/outbound – search by recipient, fromemail, tag, subject, status, fromdate/todate.
- Default count=50, max 500. Pagination via offset.
List Suppressions
List suppressed addresses for a stream
| Parameter | Required | Type | Description |
|---|---|---|---|
Stream Id stream_id | Yes | text |
Tips
- POST /message-streams/{stream}/suppressions/dump – returns suppressions for the stream.
- SuppressionReasons: HardBounce, SpamComplaint, ManualSuppression, CustomerService. Manual suppressions are CSV-uploaded entries; CustomerService are Postmark-team-added.
- Add via POST .../suppressions and remove (delete suppression) via POST .../suppressions/delete – separate endpoints, not in this connector. Activate Bounce covers the bounce-suppression-removal case.
List Templates
List available templates
No input parameters.
Tips
- GET /templates – paginated. count + offset. TemplateType filter (Standard|Layout). LayoutTemplate templates can be referenced by Standard templates via LayoutTemplate field.
Send Batch
Send up to 500 emails in one call
No input parameters.
Tips
- Up to 500 messages/request. Each entry is a full Send Email payload.
- Response is per-message: each entry has a Status (Sent / queued / Error). Always inspect – a 200 OK on the batch does NOT mean every message succeeded.
Send Batch With Template
Send a batch of templated emails
No input parameters.
Tips
- Send up to 500 templated emails in one call. Each batch entry has its own TemplateAlias|TemplateId + TemplateModel + To + (optional) MessageStream override.
- Same per-entry response shape as Send Batch – inspect Status per entry, a 200 OK on the call does NOT mean every entry sent.
Send Email
Send a single transactional email
| Parameter | Required | Type | Description |
|---|---|---|---|
From From | No | text | |
To To | No | text | |
Cc Cc | No | text | |
Bcc Bcc | No | text | |
Subject Subject | No | text | |
Tag Tag | No | text | |
Htmlbody HtmlBody | No | text | |
Textbody TextBody | No | text | |
Replyto ReplyTo | No | text | |
Headers Headers | No | text | |
Trackopens TrackOpens | No | text | |
Tracklinks TrackLinks | No | text | |
Attachments Attachments | No | text | |
Messagestream MessageStream | No | text | |
Metadata Metadata | No | text |
Tips
- Required: From (verified Sender Signature or domain), To, Subject, plus TextBody OR HtmlBody.
- MessageStream defaults to 'outbound'. If you've split streams per server, set this explicitly – Postmark routes the message accordingly.
- Tag (single string) and Metadata (object) show up in webhooks + search. Use them for cost/event attribution.
Errors
300– Invalid From – the sender isn't verified. Verify the Sender Signature or DKIM-sign the domain.406– Inactive recipient – recipient is on the suppression list (hard bounce or manual block). Reactivate via Activate Bounce after confirming it's safe.422– Subject or body missing, or both bodies empty.
Send With Template
Send an email using a Postmark template
| Parameter | Required | Type | Description |
|---|---|---|---|
From From | No | text | |
To To | No | text | |
Templateid TemplateId | No | text | |
Templatealias TemplateAlias | No | text | |
Templatemodel TemplateModel | No | text | |
Tag Tag | No | text | |
Messagestream MessageStream | No | text | |
Attachments Attachments | No | text |
Tips
- TemplateAlias or TemplateId + TemplateModel (variable bag). Mustache-syntax: {{name}}, {{#each items}}{{/each}}.
- InlineCss=true (default) inlines CSS at send time – needed for client compatibility (Outlook strips <style>).
Update Template
Update a template
| Parameter | Required | Type | Description |
|---|---|---|---|
Template Id template_id | Yes | text | |
Name Name | No | text | |
Subject Subject | No | text | |
Htmlbody HtmlBody | No | text | |
Textbody TextBody | No | text | |
Alias Alias | No | text |
Tips
- PUT /templates/{id_or_alias} – replaces specified fields. Send only the keys you want to change; omitted keys are left untouched.
- Updating a Layout template invalidates the cached compilation of every template that references it – next send re-compiles.
FAQ
- Why is my email going to spam from a verified domain?
- DKIM/SPF + content + IP reputation. Run the Postmark spam-check on each template. Shared IPs benefit from Postmark's reputation, but content (spammy words, image-heavy, link shorteners) still bins messages. Dedicated IP = warm-up required.
- Bounces vs Suppressions – are they the same list?
- Closely related. Hard bounces auto-suppress (added to inactive list). You list+manage them via Bounces (with Inactive=true filter) or Suppressions (cleaner UI for the list itself). Manual unsubscribes show up in Suppressions only.
- Server vs Stream – do I need both?
- Server is a sending namespace (token-scoped, has its own templates/webhooks). Streams (outbound, broadcast, inbound) live INSIDE a server. Use multiple servers for hard isolation; use streams within a server for soft separation of transactional vs broadcast.
- Inbound – supported here?
- Not in this connector. Postmark inbound (parsing incoming mail) is a separate API; if you need it, set up the InboundWebhook on the server and consume on your side.