postmark

# Postmark Skills

Postmark is a transactional email platform built for developers, with 15+ years of deliverability expertise. These skills teach AI agents how to use the Postmark API effectively.

## Sub-Skills

| Feature | Skill | Use When |
|---------|-------|----------|
| **Sending emails** | `postmark-send-email` | Sending transactional or broadcast emails — single, batch, bulk, or with templates |
| **Inbound processing** | `postmark-inbound` | Processing incoming emails via webhooks, building reply-by-email, email-to-ticket, or document extraction |
| **Template management** | `postmark-templates` | Creating, editing, or sending with Postmark's server-side Handlebars templates and layouts |
| **Webhooks** | `postmark-webhooks` | Setting up webhooks for delivery, bounce, open, click, spam complaint, and subscription change events |
| **Best practices** | `postmark-email-best-practices` | Deliverability setup, compliance (CAN-SPAM/GDPR/CASL), email design, list management, testing, and sending reliability |

## Quick Routing

- **"Send an email"** → `postmark-send-email`
- **"Send a batch of emails"** → `postmark-send-email`
- **"Send using a template"** → `postmark-send-email` (template section) or `postmark-templates` (to create/manage templates)
- **"Handle incoming email"** → `postmark-inbound`
- **"Process inbound webhooks"** → `postmark-inbound`
- **"Create an email template"** → `postmark-templates`
- **"Track deliveries/bounces/opens"** → `postmark-webhooks`
- **"Set up bounce handling"** → `postmark-webhooks`
- **"Set up SPF/DKIM/DMARC"** → `postmark-email-best-practices`
- **"Email compliance / GDPR / CAN-SPAM"** → `postmark-email-best-practices`
- **"Domain warm-up"** → `postmark-email-best-practices`
- **"List hygiene / suppression management"** → `postmark-email-best-practices`
- **"Design a transactional email"** → `postmark-email-best-practices`
- **"Test email safely"** → `postmark-email-best-practices`

## Common Setup

### Authentication

Postmark uses two types of API tokens:

| Token | Header | Scope |
|-------|--------|-------|
| **Server Token** | `X-Postmark-Server-Token` | Sending emails, templates, bounces, webhooks, message streams |
| **Account Token** | `X-Postmark-Account-Token` | Managing servers, domains, sender signatures |

Get your Server API Token from [Postmark Servers](https://account.postmarkapp.com/servers).

### SDK Installation

Detect the project language and install the appropriate SDK:

| File | Language | Install Command |
|------|----------|----------------|
| `package.json` | Node.js / TypeScript | `npm install postmark` |
| `requirements.txt` / `pyproject.toml` | Python | `pip install postmarker` |
| `Gemfile` | Ruby | `gem install postmark` |
| `composer.json` | PHP | `composer require wildbit/postmark-php` |
| `*.csproj` / `*.sln` | .NET | `dotnet add package Postmark` |

### Message Streams

Postmark separates email by intent into **Message Streams**:

| Stream | Value | Purpose |
|--------|-------|---------|
| **Transactional** | `outbound` | 1:1 triggered emails (welcome, password reset, receipts) — **default** |
| **Broadcast** | `broadcast` | Marketing, newsletters, announcements |

Never mix transactional and broadcast email in the same stream — it damages deliverability.

## Resources

- [Postmark Developer Docs](https://postmarkapp.com/developer)
- [API Reference](https://postmarkapp.com/developer/api/overview)
- [Postmark API for LLMs](https://postmarkapp.com/llms.txt)
- [Postmark Dashboard](https://account.postmarkapp.com)

/node_modules
.claude
.DS_Store

# Contributing to Postmark Skills

Thank you for helping improve the Postmark Skills library. This guide covers how skills are structured, how to add or update content, and the standards each contribution should meet.

## Repository Structure

```
postmark-skills/
├── SKILL.md                          # Root skill — routes to sub-skills
├── README.md                         # Repository overview and installation
├── CONTRIBUTING.md                   # This file
├── postmark-send-email/
│   ├── SKILL.md                      # Sub-skill entry point
│   └── references/                   # Detailed reference documentation
│       ├── installation.md
│       └── ...
├── postmark-inbound/
│   ├── SKILL.md
│   └── references/
│       └── ...
├── postmark-templates/
│   ├── SKILL.md
│   └── references/
│       └── ...
├── postmark-webhooks/
│   ├── SKILL.md
│   └── references/
│       └── ...
└── postmark-email-best-practices/
    ├── SKILL.md
    └── references/
        └── ...
```

Each skill is a directory containing a `SKILL.md` entry point and a `references/` folder with detailed documentation. The `SKILL.md` is what AI agents load first — it must be concise and actionable.

---

## SKILL.md Format

Every `SKILL.md` must begin with YAML frontmatter:

```yaml
---
name: postmark-skill-name
description: One or two sentences describing when an AI agent should load this skill. Start with "Use when..." or similar trigger language.
license: MIT
metadata:
  author: postmark
  version: "1.0.0"
---
```

### Frontmatter Fields

| Field | Required | Value |
|-------|----------|-------|
| `name` | Yes | Matches directory name exactly |
| `description` | Yes | Trigger language for the agent skills router |
| `license` | Yes | `MIT` |
| `metadata.author` | Yes | `postmark` |
| `metadata.version` | Yes | Semantic version string, quoted |

### SKILL.md Content Guidelines

- **Keep it short** — target 100–200 lines. If it exceeds this, move detail to `references/`.
- **Lead with a Quick Reference table** — what topics are covered, what to use each for.
- **Include at least one working code example** — the most common use case, ready to copy.
- **Link to reference files** — don't repeat content that lives in `references/`.
- **List Common Mistakes** — things developers frequently get wrong with this feature.
- **End with a Notes section** — key constraints, limits, and gotchas.

### Example SKILL.md Structure

```markdown
---
name: postmark-example
description: Use when...
license: MIT
metadata:
  author: postmark
  version: "1.0.0"
---

# Feature Name

One paragraph description.

## Quick Reference

| Topic | Use When |
|-------|----------|
| ... | ... |

## Quick Start

[Minimal working code example]

## [Topic 1]

[Short overview, key points, link to references/topic1.md for details]

## Common Mistakes

- [Specific mistake]: [Why it's wrong and what to do instead]

## Notes

- [Key constraint or gotcha]
```

---

## Reference File Guidelines

Reference files in `references/` contain detail that doesn't belong in the main `SKILL.md`. Each file should cover one topic thoroughly.

### File Naming

Use lowercase kebab-case matching the topic:

```
references/
├── payload-structure.md      # Good
├── handler-examples.md       # Good
├── PayloadStructure.md       # Bad — wrong case
├── handlers.md               # Too vague — be specific
```

### Reference File Content Standards

- **Start with a clear heading** — `# Topic Name`
- **Use tables** for API fields, parameters, options, and comparisons
- **Use working code examples** — every example should be copy-paste ready
- **Show multiple languages** when relevant — Node.js first, then Python, cURL
- **Link to Postmark docs** for anything that may change (rate limits, error codes, API endpoints)
- **Don't duplicate** content that exists in another reference file — link to it instead

### Code Example Standards

All code examples must:

- Use real Postmark API field names (correct casing: `From`, `To`, `HtmlBody`, not `from`, `to`, `htmlBody`)
- Use environment variables for credentials: `process.env.POSTMARK_SERVER_TOKEN`
- Be syntactically correct and runnable
- Show the install command or import at the top of the first example in each file
- Prefer async/await over callbacks

```javascript
// Good
const postmark = require('postmark');
const client = new postmark.ServerClient(process.env.POSTMARK_SERVER_TOKEN);

const result = await client.sendEmail({
  From: '[email protected]',
  To: '[email protected]',
  Subject: 'Hello',
  TextBody: 'Hello world.',
  MessageStream: 'outbound'
});
```

---

## Adding a New Skill

1. Create a directory: `postmark-new-feature/`
2. Create `postmark-new-feature/SKILL.md` with frontmatter and content following the format above
3. Create `postmark-new-feature/references/` with at least one reference file
4. Add the skill to the root `SKILL.md` Sub-Skills table and Quick Routing section
5. Add the skill to `README.md` Available Skills table and add a usage example prompt

---

## Updating an Existing Skill

When Postmark updates its API:

1. Update the relevant reference file(s) in `references/`
2. If it's a breaking change or significant addition, update the `SKILL.md` Quick Start example
3. Bump `metadata.version` in the skill's frontmatter (e.g., `1.0.0` → `1.1.0`)
4. Note the change in your PR description

---

## Pull Request Checklist

- [ ] Frontmatter is complete and correctly formatted on all modified `SKILL.md` files
- [ ] `SKILL.md` is under 200 lines
- [ ] All code examples use `process.env.POSTMARK_SERVER_TOKEN` (not hardcoded tokens)
- [ ] All code examples use correct Postmark API field casing (`From`, not `from`)
- [ ] Reference files linked from `SKILL.md` actually exist
- [ ] New skills are added to root `SKILL.md` and `README.md`
- [ ] No duplicate content — detail lives in `references/`, overview in `SKILL.md`

MIT License

Copyright (c) 2025 ActiveCampaign, LLC

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

```
 ____           _                        _       ____  _    _ _ _
|  _ \ ___  ___| |_ _ __ ___   __ _ _ __| | __  / ___|| | _(_) | |___
| |_) / _ \/ __| __| '_ ` _ \ / _` | '__| |/ /  \___ \| |/ / | | / __|
|  __/ (_) \__ \ |_| | | | | | (_| | |  |   <    ___) |   <| | | \__ \
|_|   \___/|___/\__|_| |_| |_|\__,_|_|  |_|\_\  |____/|_|\_\_|_|_|___/
```

# Postmark Skills

[Agent Skills](https://github.com/anthropics/skills) for the [Postmark](https://postmarkapp.com) email platform. Teach AI coding agents how to send transactional email, process inbound messages, manage templates, and configure webhooks using the Postmark API. Check out this [blog post](https://postmarkapp.com/blog/teach-your-ai-coding-agent-how-to-send-email-with-postmark-skills?utm_source=ActiveCampaign&utm_medium=github) we wrote for more info.

## Available Skills

| Skill | Description |
|-------|-------------|
| [`postmark-send-email`](./postmark-send-email/) | Send emails via Postmark API — single, batch, bulk, and template-based. Supports transactional and broadcast message streams. |
| [`postmark-inbound`](./postmark-inbound/) | Process incoming emails with Postmark inbound webhooks. Build reply-by-email, email-to-ticket, and document extraction workflows. |
| [`postmark-templates`](./postmark-templates/) | Create and manage server-side email templates with Handlebars syntax. Supports layouts, template validation, and cross-server pushing. |
| [`postmark-webhooks`](./postmark-webhooks/) | Configure webhooks for delivery, bounce, open, click, spam complaint, and subscription change events. |
| [`postmark-email-best-practices`](./postmark-email-best-practices/) | Deliverability, compliance (CAN-SPAM, GDPR, CASL), transactional email design, list management, testing safely, and sending reliability. |

## Installation

```bash
npx skills add ActiveCampaign/postmark-skills
```

Install a specific skill:

```bash
npx skills add ActiveCampaign/postmark-skills --skill postmark-send-email
```

## Usage

Once installed, your AI coding agent will automatically use these skills when relevant. Example prompts:

- "Send a welcome email using Postmark"
- "Set up inbound email processing for a support ticket system"
- "Create a Postmark template for order confirmation emails"
- "Add bounce and delivery webhooks to track email status"
- "Send a batch of 200 notification emails through Postmark"
- "How do I set up SPF, DKIM, and DMARC for Postmark?"
- "What are the CAN-SPAM and GDPR requirements for my email list?"
- "Help me design a password reset email"

## Postmark & Community SDKs

- **Node.js / TypeScript** — [`postmark`](https://www.npmjs.com/package/postmark)
- **Python** — [`postmarker`](https://pypi.org/project/postmarker/)*
- **Ruby** — [`postmark`](https://rubygems.org/gems/postmark)
- **PHP** — [`wildbit/postmark-php`](https://packagist.org/packages/wildbit/postmark-php)
- **.NET** — [`Postmark`](https://www.nuget.org/packages/Postmark)

<small>* Disclaimer: Third-party SDKs are provided "as is" without warranty of any kind. Postmark disclaims all liability for any damages or issues arising from their use.</small>

## Prerequisites

1. A [Postmark account](https://account.postmarkapp.com/sign_up)
2. A verified sender domain or sender signature
3. Your Server API Token (from [Postmark Servers](https://account.postmarkapp.com/servers))
4. Set your token as an environment variable: `POSTMARK_SERVER_TOKEN`

## Why Postmark?

- **Message Streams** — Separate transactional and broadcast email for better deliverability
- **500 emails per batch** — 5x more than alternatives
- **Batch attachments** — Attach files in batch sends
- **Server-side templates** — Handlebars templates with layout inheritance, no client-side rendering needed
- **Full inbound processing** — Parse and route incoming emails with webhook delivery
- **15+ years deliverability expertise** — Trusted by 100,000+ developers

## License

MIT