Postmark Integration

Postmark is a transactional email service known for its exceptional deliverability and detailed analytics. Broadcast provides full integration with Postmark, including API delivery and webhook tracking.

Features

Guided Setup (Recommended)

The fastest way to get started with Postmark is the Guided Setup wizard, which automatically configures API delivery, sender verification, and webhooks in three steps:

1. Navigate to Settings → Email Servers
2. Click Add email server → Guided Setup
3. Select Postmark
4. Enter your Postmark Account API Token
5. Broadcast will automatically:
   • Configure API delivery
   • Verify your sender signature
   • Set up DKIM DNS records (if needed)
   • Configure webhook tracking

Step 4 wants the Account-level token, not a Server token: find it in Postmark under Account → API Tokens. An account token is what lets Broadcast discover your servers, domains, and senders; a server token only reaches one server and the wizard will not get past this step with one.

Reconnecting, or adding a second server

Once a channel already sends through Postmark, the wizard asks what this run is for before it asks for anything else:

• Reconnect an existing server re-runs setup for a server you already have. Use this to refresh its credentials or re-check its senders. It never creates anything in Postmark.
• Add another server creates a second Postmark server for the same channel, and asks what to call it. Give it a name that says what it carries (Acme Invoices), because the name is how you will tell your servers apart in both Broadcast and Postmark.

A channel can run as many Postmark servers as you need. That is worth doing when one channel sends genuinely different kinds of mail: a server’s reputation is its own, so putting invoices on a separate server from your newsletter means a bad week for one cannot drag down the other. Bind each server to the email types it should carry in the server’s settings, and pin a sequence to a specific server from the sequence’s own settings.

If you prefer manual control or need SMTP delivery, follow the manual setup instructions below.

Delivery Methods

Broadcast supports two delivery methods for Postmark:

API Delivery (Recommended)

API delivery uses Postmark’s REST API for sending emails. Benefits include:

• Faster sending: Direct API calls without SMTP overhead
• Better error handling: Detailed error messages from Postmark
• Message streams: Full support for transactional and broadcast streams
• Reduced infrastructure: No need to open SMTP ports

SMTP Delivery

Traditional SMTP delivery for maximum compatibility with existing infrastructure.

Both methods support full webhook integration for tracking email events.

Setting Up Postmark

Prerequisites

Before you begin, ensure you have:

1. A Postmark account
2. A verified sender signature (domain or email address)
3. A server created in Postmark

Finding Your Credentials

Server API Token

1. Log into your Postmark account
2. Select your server
3. Go to Settings → API Tokens
4. Copy your Server API Token

SMTP Credentials

1. In your Postmark server, go to Settings → SMTP
2. Note the following:
   • Server: smtp.postmarkapp.com
   • Port: 587 (or 25, 2525)
   • Username: Your Server API Token
   • Password: Your Server API Token

Configuring Email Delivery

API Delivery Setup

To use API delivery (recommended):

1. In Broadcast, go to Settings → Email Servers
2. Click New Email Server
3. Configure:
   • Label: A descriptive name (e.g., “Postmark Production”)
   • Vendor: Postmark
   • Delivery Method: API
   • Postmark Server API Token: Your server’s API token
4. Select which email types to send:
   • ✅ Broadcasts
   • ✅ Sequences
   • ✅ Transactional Emails
5. Click Create Email Server

SMTP Delivery Setup

For SMTP delivery:

1. In Broadcast, go to Settings → Email Servers
2. Click New Email Server
3. Configure:
   • Label: A descriptive name
   • Vendor: Postmark
   • Delivery Method: SMTP
   • SMTP Address: smtp.postmarkapp.com
   • SMTP Port: 587
   • SMTP Username: Your Server API Token
   • SMTP Password: Your Server API Token
   • SMTP Authentication: Login
   • Enable STARTTLS: Yes
4. Click Test SMTP settings to verify connectivity
5. Select which email types to send
6. Click Create Email Server

Webhook Setup

Postmark webhooks allow Broadcast to receive real-time notifications about email events. This enables accurate tracking of deliveries, bounces, opens, and clicks.

Finding Your Webhook URL

1. In Broadcast, go to Settings → Email Servers
2. Find the Postmark section
3. Copy your webhook URL (e.g., https://broadcast.yourdomain.com/wh/postmark)

Configuring Webhooks in Postmark

1. Log into your Postmark account
2. Select your server
3. Go to Settings → Webhooks
4. Click Add webhook
5. Configure the webhook:

Webhook URL: Your Broadcast webhook URL

Events to send: - ✅ Delivery - ✅ Bounce - ✅ Spam Complaint - ✅ Open (if using Postmark’s open tracking) - ✅ Click (if using Postmark’s link tracking)

1. Click Save webhook

Webhook Password (Optional)

Broadcast uses a webhook password to verify incoming requests from Postmark:

1. In Broadcast, go to Settings → Email Servers
2. Find the Postmark section
3. Note the webhook password displayed
4. You can click Refresh Password to generate a new one

When configuring your webhook in Postmark, append the password to your webhook URL:

https://broadcast.yourdomain.com/wh/postmark?password=YOUR_PASSWORD

Message Streams

Postmark uses message streams to separate different types of email. This helps maintain deliverability by keeping transactional emails separate from marketing emails.

Default Streams

Postmark provides two default streams:

Using Message Streams with Broadcast

When using API delivery, Broadcast sends each email on the stream that matches what it is:

Sequences default to the transactional stream: a sequence step goes to one person and is triggered by something that person did, which is how Postmark describes transactional mail.

A sequence whose content is marketing, an onboarding series or a re-engagement campaign, is better placed on the bulk stream, so its unsubscribes and spam complaints cannot damage the reputation carrying your receipts and password resets. Open the sequence’s Settings and change Message Stream to Bulk (broadcast). The setting only appears for channels that have a Postmark server, since no other provider separates streams this way.

You can also configure different Postmark servers for different email types. See Reconnecting, or adding a second server.

Tracking Features

With Postmark webhooks enabled, Broadcast automatically tracks:

Delivery Events

• Delivered: Email successfully delivered to recipient’s mailbox
• Bounced: Email bounced (hard or soft)
• Spam Complaint: Recipient marked email as spam

Engagement Events

• Opened: Recipient opened the email
• Clicked: Recipient clicked a link

Automatic Actions

When certain events occur, Broadcast takes automatic action:

Open and Click Tracking

Postmark offers its own open and click tracking, or you can use Broadcast’s native tracking.

Using Postmark’s Tracking

1. In Postmark, enable Open Tracking and Link Tracking in your server settings
2. Configure your webhook to include Open and Click events
3. Broadcast will receive and record these events

Using Broadcast’s Native Tracking

1. When creating broadcasts or sequences, enable Track opens and Track clicks
2. Broadcast will insert tracking pixels and rewrite links
3. Tracking works independently of Postmark webhooks

Which Should I Use?

For best results, you can use both: Broadcast deduplicates events automatically.

Testing the Integration

Sending a Test Email

1. Create a test subscriber with your own email address
2. Create a test broadcast
3. Send to your test subscriber
4. Verify in Postmark’s activity feed that the email was sent
5. Check your inbox for the email
6. In Broadcast, verify delivery events appear on the broadcast detail page

Testing Webhook Events

1. Open the test email to trigger an open event
2. Click any links to trigger click events
3. In Broadcast, check the subscriber’s activity log
4. Verify events are recorded with correct timestamps

Testing Bounces

To test bounce handling:

1. Add a test subscriber with an invalid email format
2. Send a test broadcast
3. Postmark will return a bounce
4. Verify:
   • Bounce event appears in Broadcast
   • Subscriber is deactivated
   • Email is added to suppression list

Webhook Events

Postmark sends the following webhook events:

Troubleshooting

Common Issues

“Invalid API Token” error

• Verify you’re using a Server API Token, not an Account API Token
• Check that the token hasn’t been rotated or deleted
• Ensure there are no extra spaces in the token

Webhooks not being received

• Verify the webhook URL is correct and includes HTTPS
• Check that your Broadcast instance is publicly accessible
• Verify the webhook is enabled in Postmark
• Check Postmark’s webhook logs for delivery failures

Emails not sending

• Verify your sender signature is verified in Postmark
• Check that the “From” address matches your verified signature
• Review Postmark’s activity feed for rejection reasons
• Ensure your Postmark account isn’t in sandbox mode (for production)

Open/click tracking not working

• If using Postmark tracking: Verify tracking is enabled in server settings
• If using Broadcast tracking: Ensure tracking is enabled on the broadcast
• Check that webhooks include Open and Click events

Viewing Postmark Activity

1. Log into Postmark
2. Go to your server’s Activity feed
3. Search for specific emails by recipient or subject
4. Click on an email to see detailed delivery information

Webhook Debugging

In Postmark:

1. Go to Settings → Webhooks
2. Click on your webhook
3. View Recent deliveries for success/failure status
4. Check response codes and any error messages

Getting Help

If you’re experiencing issues:

1. Check Postmark’s status page for service issues
2. Review Postmark’s activity logs for detailed error messages
3. Verify all configuration steps were completed
4. Contact support at simon@sendbroadcast.net

Best Practices

Sender Signatures

• Verify your sending domain (not just an email address) for better deliverability
• Set up SPF, DKIM, and DMARC records as recommended by Postmark
• Use a consistent “From” address across all emails

Message Streams

• Use the broadcast stream for newsletters and marketing
• Keep transactional emails in the transactional stream
• Don’t mix marketing content in transactional emails

Monitoring

• Regularly check your Postmark reputation score
• Monitor bounce rates and address issues promptly
• Review spam complaints and adjust content if needed

Webhook Reliability

• Use the webhook password for security
• Monitor webhook delivery in Postmark’s dashboard
• Set up alerts for webhook failures