Skip to content

Postmark

Postmark works with pg_relay two ways: over the SMTP transport, or over the webhook transport against its Email API. Both authenticate with the same Server API Token, found on the server's API Tokens tab in Postmark — keep it out of the database with an _env: reference (Keeping Secrets Out of the Database).

Over SMTP

{
  "host": "smtp.postmarkapp.com",
  "port": 587,
  "security": "starttls",
  "auth": "plain",
  "username": "_env:POSTMARK_SERVER_TOKEN",   // the Server API Token…
  "password": "_env:POSTMARK_SERVER_TOKEN",   // …as BOTH username and password
  "from": "[email protected]",            // a confirmed Sender Signature
  "timeout_seconds": 30
}

Postmark's SMTP endpoint takes the Server API Token as both the username and the password — the same _env: variable referenced twice is exactly right (every profile string goes through secret resolution, username included). Port 2525 also works if 587 is blocked on your network. The message block is the standard one from the SMTP chapter.

Over the REST API (webhook)

// profile
{
  "url": "https://api.postmarkapp.com/email",
  "auth": {"style": "custom_header", "header_name": "X-Postmark-Server-Token",
           "secret": "_env:POSTMARK_SERVER_TOKEN"},
  "headers": {"Accept": "application/json"},
  "timeout_seconds": 30
}

// message — Postmark's own request shape, sent verbatim
{
  "From": "[email protected]",
  "To": "[email protected]",
  "Subject": "disk alert",
  "TextBody": "volume is filling",
  "HtmlBody": "<p>volume is filling</p>",
  "MessageStream": "outbound"
}

For Postmark, have classify_webhook_response treat:

  • 200 as sent — the JSON body carries "MessageID", Postmark's id for the sent message; return it as the provider reference.
  • 429, any 5xx, and http_status = 0 (no response) as retry.
  • 422 and other 4xx as failed — Postmark's 422 body carries an ErrorCode and a human-readable Message worth passing back as the detail text (an inactive recipient, an unconfirmed sender, a malformed body).

Things Postmark enforces

From must be a confirmed Sender Signature, or an address on a verified domain, on the server the token belongs to. Postmark also separates traffic into message streams — "outbound" is the default transactional stream, and the right one for pg_relay notifications.

Continue to Mailgun.