sales-postmark

What this skill does

# Postmark Platform Help

Help the user with Postmark (ActiveCampaign) platform questions — from transactional email via the REST API and SMTP relay through Message Streams, Handlebars Templates, Inbound Email, Webhooks, DMARC Monitoring, Bounce Management, Suppressions, Statistics, and integrations. Postmark is laser-focused on transactional email with best-in-class deliverability (98.7% inbox placement), originally built by Wildbit (Natalie & Chris Nagele) and acquired by ActiveCampaign in 2022.

## Step 1 — Gather context


If `references/learnings.md` exists, read it first for accumulated knowledge.

Ask the user:

1. **What area of Postmark do you need help with?**
   - A) Email API — sending transactional email via REST API (`POST /email`, `POST /email/batch`), SDKs
   - B) SMTP relay — traditional SMTP integration for frameworks that don't support API
   - C) Message Streams — separating transactional and broadcast (newsletters/announcements) infrastructure
   - D) Templates — server-side Handlebars templates, layout inheritance, cross-server pushing
   - E) Inbound Email — receiving and parsing incoming emails via webhook
   - F) Webhooks — bounce, delivery, open, click, spam complaint, subscription change, inbound events
   - G) DMARC Monitoring — free weekly DMARC reports, paid detailed monitoring
   - H) Bounce Management / Suppressions — automatic bounce processing, suppression lists
   - I) Statistics — opens, clicks, delivery rates, bounce rates, spam complaints
   - J) Sender Signatures — verified sender addresses and domains
   - K) Account / Billing — plans, pricing, servers, API tokens
   - L) Something else — describe it

2. **What's your role?**
   - A) Developer / engineer
   - B) DevOps / infrastructure
   - C) Admin / account owner
   - D) Founder / solo operator
   - E) Agency / freelancer
   - F) Other

3. **What are you trying to accomplish?** (describe your specific goal or question)

**If the user's request already provides most of this context, skip directly to the relevant step.** Lead with your best-effort answer using reasonable assumptions (stated explicitly), then ask only the most critical 1-2 clarifying questions at the end — don't gate your response behind gathering complete context.

Note: If the user needs a specialized skill, route them there with a brief explanation of why that skill is a better fit.

## Step 2 — Route or answer directly

If the request maps to a specialized skill, route:
- General email marketing strategy / best practices -> `/sales-email-marketing`
- Cross-platform email deliverability (not Postmark-specific) -> `/sales-deliverability`
- Email open/click tracking strategy -> `/sales-email-tracking`
- SendGrid-specific questions -> `/sales-sendgrid`
- Connecting Postmark to other tools via Zapier or middleware -> `/sales-integration`
- Funnel strategy / conversion optimization -> `/sales-funnel`

Otherwise, answer directly from platform knowledge using the reference below.

## Step 3 — Postmark platform reference

**Read `references/platform-guide.md`** for detailed module documentation, pricing, integrations, and data model.

*You no longer need the platform guide details — focus on the user's specific situation.*

## Step 4 — Actionable guidance

Based on the user's specific question:

1. **Sending transactional email via the API**:
   1. Create a server in the Postmark UI (or use the default server)
   2. Copy the Server API Token from the server's credentials page
   3. Add and verify a Sender Signature — either a single email address or an entire domain (add DKIM and Return-Path CNAME records to DNS)
   4. Install the SDK for your language (e.g., `npm install postmark` for Node.js)
   5. Initialize the client: `const client = new postmark.ServerClient("YOUR_SERVER_TOKEN")`
   6. Send an email: set `From`, `To`, `Subject`, `HtmlBody`/`TextBody` (or use `TemplateId` + `TemplateModel`)
   7. Handle the response — check for `ErrorCode: 0` (success) or specific error codes
   8. Use `POSTMARK_API_TEST` as the server token during development to test without sending real email

2. **Setting up Message Streams for transactional and broadcast**:
   1. Navigate to your server in the Postmark UI
   2. The default transactional stream already exists — use it for password resets, receipts, alerts
   3. Create a new broadcast stream: Servers > [Your Server] > Message Streams > Add Stream > Broadcast
   4. Name the stream (e.g., "Newsletter", "Product Updates")
   5. In your API calls, pass `"MessageStream": "your-broadcast-stream-id"` to route to the broadcast stream
   6. Configure separate webhooks per stream if needed
   7. Monitor each stream's statistics independently to track reputation health

3. **Setting up Handlebars templates with layout inheritance**:
   1. Create a layout template first: Templates > Add Template > Layout
   2. Define the layout with `{{{@content}}}` placeholder where content templates will be injected
   3. Include shared elements in the layout: header, footer, styles, unsubscribe links
   4. Create content templates that reference the layout via the `LayoutTemplate` field
   5. Use Handlebars syntax in content templates: `{{variable}}`, `{{#if condition}}`, `{{#each items}}`
   6. Validate templates via the API (`POST /templates/{id}/validate`) with sample data
   7. Push templates between servers (staging to production) via the Template Push API

4. **Processing inbound email**:
   1. Upgrade to Pro plan or above (inbound email is not available on Developer or Basic plans)
   2. Add an MX record for your receiving domain: `10 inbound.postmarkapp.com`
   3. Configure the inbound webhook URL in the Postmark UI under your server's Inbound settings
   4. Optionally set up inbound rules to filter which recipient addresses trigger webhooks
   5. Implement your webhook endpoint to receive JSON payloads with parsed fields (From, To, Subject, HtmlBody, TextBody, Attachments)
   6. Handle attachments — they arrive as base64-encoded content in the JSON payload
   7. Return a 200 status code from your endpoint to acknowledge receipt

5. **Setting up DMARC monitoring**:
   1. Add a DMARC DNS record for your domain: `v=DMARC1; p=none; rua=mailto:[email protected]`
   2. Free weekly digests start arriving automatically — summarize who is sending email as your domain
   3. For detailed monitoring ($14/mo/domain), sign up at dmarc.postmarkapp.com
   4. Review reports to identify unauthorized senders and SPF/DKIM alignment failures
   5. Gradually tighten your DMARC policy: `p=none` -> `p=quarantine` -> `p=reject` as you confirm all legitimate senders are authenticated

## Gotchas

> Best-effort from research — verify details against current Postmark documentation.

1. **Dedicated IPs require a minimum sending volume of 300K emails/month.** Unlike SendGrid or Mailchimp where you can buy a dedicated IP at lower volumes, Postmark requires sustained high volume to maintain IP reputation. If you send fewer than 300K/month, Postmark's shared IP pools actually deliver better results — their sender vetting process keeps shared IP reputation exceptionally high. Don't assume dedicated = better.
2. **Inbound Email is only available on Pro plan and above.** If you need to receive and parse incoming email (reply processing, support tickets, email-to-app workflows), the Developer and Basic plans will not work. Budget for at least Pro ($16.50/mo) if inbound email is part of your architecture.
3. **Transactional and broadcast streams have separate suppression lists but share a single bill.** While Message Streams isolate sending reputation, suppressions are per-stream — an address suppressed in your broadcast stream can still receive transactional email, and vice versa. This is intentional (a user unsubscribing from your newsletter should still get password resets) but can surprise teams expecting a single global suppression list.
4. **Postmark has a sender vetting process — you can