Postmark

Postmark

This connector uses the Postmark API (https://api.postmarkapp.com) for transactional and broadcast email: sending single, batch and templated emails, templates, searching sent and received messages with opens and clicks, bounces, sending statistics, suppressions, message streams and webhooks of one Postmark server. With an optional account token it also reads the account's servers, domains and sender signatures.

Setup (2 minutes)

1. In Postmark open the server, then API Tokens, and copy a Server API token into POSTMARK_SERVER_TOKEN. It is sent as the X-Postmark-Server-Token header and gives access to that server only.
2. Optional: for the account tools (postmark_list_servers, postmark_get_server_by_id, postmark_list_domains, postmark_get_domain, postmark_verify_domain_dkim, postmark_verify_domain_return_path, postmark_list_sender_signatures, postmark_get_sender_signature) an account owner or admin copies the Account API token from Account, API Tokens into POSTMARK_ACCOUNT_TOKEN. It is sent as X-Postmark-Account-Token on those tools only. Without it they answer 401; the other tools work.
3. Run postmark_get_server to check the token.

Sending

• postmark_send_email for one email, postmark_send_batch for up to 500 different emails, postmark_send_email_with_template and postmark_send_batch_with_templates for stored templates with a TemplateModel.
• From must be a confirmed sender signature or an address on a verified domain. New accounts are in test mode until Postmark approves them and can only send to addresses on their own domain.
• Transactional email goes through the outbound stream (the default). Bulk or marketing email must use a Broadcasts stream (MessageStream), which adds unsubscribe handling.
• Every send reaches real inboxes: show the user the recipients, subject and content and wait for a yes. Batch calls answer 200 even when single messages fail: check ErrorCode (0 = accepted) and Message of each result.

Templates: postmark_list_templates, postmark_get_template, postmark_validate_template (check syntax and render a preview), postmark_create_template, postmark_update_template, postmark_delete_template. Variables use Mustachio, e.g. {{name}}; a Layout wraps standard templates with {{{@content}}}.

Finding what happened to an email

1. postmark_search_outbound_messages by recipient, tag, subject or date, or postmark_search_inbound_messages for received mail; postmark_retry_inbound_message reposts a failed inbound message to the webhook.
2. postmark_get_outbound_message (or postmark_get_inbound_message) shows the details and the MessageEvents timeline (Delivered, Bounced, Opened, LinkClicked, SubscriptionChanged).
3. Opens and clicks: postmark_list_message_opens, postmark_get_message_opens, postmark_list_message_clicks, postmark_get_message_clicks.
4. Bounces: postmark_get_delivery_stats, postmark_list_bounces, postmark_get_bounce, postmark_get_bounce_dump (raw SMTP answer). postmark_activate_bounce reactivates an address when CanActivate is true.
5. Suppressions per stream: postmark_list_suppressions, postmark_create_suppressions, postmark_delete_suppressions (spam complaints cannot be removed).

Statistics: postmark_get_outbound_overview for totals and rates of a period, postmark_get_outbound_stats with metric for daily counts (sends, bounces, spam, tracked, opens, clicks, platforms, email clients, browsers, locations).

Server setup: postmark_get_server; streams with postmark_list_message_streams, postmark_get_message_stream, postmark_create_message_stream, postmark_update_message_stream, postmark_archive_message_stream, postmark_unarchive_message_stream; webhooks with postmark_list_webhooks, postmark_get_webhook, postmark_create_webhook, postmark_update_webhook, postmark_delete_webhook. Domain DNS checks need the account token (see Setup).

Reading the answers: field names are PascalCase (MessageID, SubmittedAt, TotalCount). Search dates (fromdate, todate) are US Eastern Time; returned timestamps carry their offset. Statistics dates are YYYY-MM-DD. Messages and their events are kept for the server's retention period (45 days by default).

Paging: list and search tools take count (default 50, at most 500) and offset; count + offset may not exceed 10,000. Narrow the date range to go further back. Compare TotalCount with what you received to know whether more pages exist.

Errors: 401 means a missing or wrong token (or a server token on an account tool), 422 an invalid request: read ErrorCode and Message (300 send validation such as an invalid address or missing body, 406 inactive or suppressed recipient, 410 more than 500 messages in a batch, 412 recipients outside the From domain while the account awaits approval, 1101 template not found, 1235 unknown message stream). 429 means too many requests; 500 a Postmark problem, retry later.

Switched off at install: postmark_delete_template, postmark_delete_suppressions, postmark_delete_webhook and postmark_archive_message_stream; an admin switches them on when the team needs them.