tools/integrations/postmark.md

# Postmark

Transactional email delivery service with fast delivery, templates, bounce management, and detailed analytics.

## Capabilities

| Integration | Available | Notes |
|-------------|-----------|-------|
| API | ✓ | REST API for email sending, templates, bounces, stats |
| MCP | - | Not available |
| CLI | ✓ | [postmark.js](../clis/postmark.js) |
| SDK | ✓ | Node.js, Ruby, Python, PHP, Java, .NET, Go |

## Authentication

- **Type**: Server Token (or Account Token for account-level ops)
- **Header**: `X-Postmark-Server-Token: {server_token}` (server-level)
- **Header**: `X-Postmark-Account-Token: {account_token}` (account-level)
- **Get key**: API Tokens tab at https://account.postmarkapp.com/servers
- **Note**: Server tokens are per-server; account tokens apply across all servers

## Common Agent Operations

### Send single email

```bash
POST https://api.postmarkapp.com/email

{
  "From": "sender@example.com",
  "To": "recipient@example.com",
  "Subject": "Welcome!",
  "HtmlBody": "<html><body><p>Hello!</p></body></html>",
  "TextBody": "Hello!",
  "MessageStream": "outbound",
  "TrackOpens": true,
  "TrackLinks": "HtmlAndText"
}
```

### Send with template

```bash
POST https://api.postmarkapp.com/email/withTemplate

{
  "From": "sender@example.com",
  "To": "recipient@example.com",
  "TemplateId": 12345,
  "TemplateModel": {
    "name": "Jane",
    "action_url": "https://example.com/verify"
  },
  "MessageStream": "outbound"
}
```

### Send batch emails

```bash
POST https://api.postmarkapp.com/email/batch

[
  {
    "From": "sender@example.com",
    "To": "user1@example.com",
    "Subject": "Notification",
    "TextBody": "Hello user 1"
  },
  {
    "From": "sender@example.com",
    "To": "user2@example.com",
    "Subject": "Notification",
    "TextBody": "Hello user 2"
  }
]
```

### List templates

```bash
GET https://api.postmarkapp.com/templates?Count=100&Offset=0
```

### Get template

```bash
GET https://api.postmarkapp.com/templates/{templateIdOrAlias}
```

### Create template

```bash
POST https://api.postmarkapp.com/templates

{
  "Name": "Welcome Email",
  "Alias": "welcome",
  "Subject": "Welcome {{name}}!",
  "HtmlBody": "<html><body><p>Hello {{name}}</p></body></html>",
  "TextBody": "Hello {{name}}"
}
```

### Get delivery stats

```bash
GET https://api.postmarkapp.com/deliverystats
```

### List bounces

```bash
GET https://api.postmarkapp.com/bounces?count=50&offset=0&type=HardBounce
```

### Activate bounce (reactivate recipient)

```bash
PUT https://api.postmarkapp.com/bounces/{bounceId}/activate
```

### Search outbound messages

```bash
GET https://api.postmarkapp.com/messages/outbound?count=50&offset=0&recipient=user@example.com
```

### Get outbound stats overview

```bash
GET https://api.postmarkapp.com/stats/outbound?fromdate=2025-01-01&todate=2025-01-31
```

### Get open stats

```bash
GET https://api.postmarkapp.com/stats/outbound/opens?fromdate=2025-01-01&todate=2025-01-31
```

### Get click stats

```bash
GET https://api.postmarkapp.com/stats/outbound/clicks?fromdate=2025-01-01&todate=2025-01-31
```

### Get server info

```bash
GET https://api.postmarkapp.com/server
```

### List suppressions

```bash
GET https://api.postmarkapp.com/message-streams/outbound/suppressions/dump
```

### Create suppression

```bash
POST https://api.postmarkapp.com/message-streams/outbound/suppressions

{
  "Suppressions": [
    { "EmailAddress": "user@example.com" }
  ]
}
```

## API Pattern

Postmark uses simple REST endpoints with PascalCase field names in request/response bodies. Authentication is via custom headers rather than Authorization. Pagination uses `Count` and `Offset` parameters. Email sending is synchronous with immediate delivery confirmation.

## Key Metrics

### Delivery Metrics
- `Sent` - Total emails sent
- `Bounced` - Bounce count by type (hard, soft, transient)
- `SpamComplaints` - Spam complaint count
- `Opens` - Open count and unique opens
- `Clicks` - Click count and unique clicks

### Bounce Types
- `HardBounce` - Permanent delivery failure
- `SoftBounce` - Temporary delivery failure
- `Transient` - Temporary issue (retry)
- `SpamNotification` - Marked as spam

### Message Fields
- `MessageID` - Unique message identifier
- `SubmittedAt` - Submission timestamp
- `Status` - Delivery status
- `Recipients` - Recipient list

## Parameters

### Email Parameters
- `From` - Sender address (must be verified)
- `To` - Recipient (comma-separated for multiple)
- `Subject` - Email subject
- `HtmlBody` / `TextBody` - Email content
- `MessageStream` - outbound (transactional) or broadcast
- `TrackOpens` - Enable open tracking (boolean)
- `TrackLinks` - None, HtmlAndText, HtmlOnly, TextOnly
- `Tag` - Custom tag for categorization

### Stats Parameters
- `fromdate` - Start date (YYYY-MM-DD)
- `todate` - End date (YYYY-MM-DD)
- `tag` - Filter by tag

## When to Use

- Transactional emails (password resets, order confirmations, notifications)
- Template-based email sending with dynamic variables
- Monitoring email deliverability and bounce rates
- Tracking email engagement (opens, clicks)
- Managing email suppressions and bounces
- High-reliability email delivery with fast performance

## Rate Limits

- 500 messages per batch request
- 10 MB max per single message (including attachments)
- 50 MB max per batch request
- API rate limits vary by plan

## Relevant Skills

- emails
- transactional-email
- email-deliverability
- onboarding-email
feat: add 23 new CLI tools and integration guides 2026-02-17 11:28:41 -08:00			`# Postmark`

			`Transactional email delivery service with fast delivery, templates, bounce management, and detailed analytics.`

			`## Capabilities`

			`\| Integration \| Available \| Notes \|`
			`\|-------------\|-----------\|-------\|`
			`\| API \| ✓ \| REST API for email sending, templates, bounces, stats \|`
			`\| MCP \| - \| Not available \|`
			`\| CLI \| ✓ \| [postmark.js](../clis/postmark.js) \|`
			`\| SDK \| ✓ \| Node.js, Ruby, Python, PHP, Java, .NET, Go \|`

			`## Authentication`

			`- Type: Server Token (or Account Token for account-level ops)`
			- Header: `X-Postmark-Server-Token: {server_token}` (server-level)
			- Header: `X-Postmark-Account-Token: {account_token}` (account-level)
			`- Get key: API Tokens tab at https://account.postmarkapp.com/servers`
			`- Note: Server tokens are per-server; account tokens apply across all servers`

			`## Common Agent Operations`

			`### Send single email`

			```bash
			`POST https://api.postmarkapp.com/email`

			`{`
			`"From": "sender@example.com",`
			`"To": "recipient@example.com",`
			`"Subject": "Welcome!",`
			`"HtmlBody": "<html><body><p>Hello!</p></body></html>",`
			`"TextBody": "Hello!",`
			`"MessageStream": "outbound",`
			`"TrackOpens": true,`
			`"TrackLinks": "HtmlAndText"`
			`}`
			```

			`### Send with template`

			```bash
			`POST https://api.postmarkapp.com/email/withTemplate`

			`{`
			`"From": "sender@example.com",`
			`"To": "recipient@example.com",`
			`"TemplateId": 12345,`
			`"TemplateModel": {`
			`"name": "Jane",`
			`"action_url": "https://example.com/verify"`
			`},`
			`"MessageStream": "outbound"`
			`}`
			```

			`### Send batch emails`

			```bash
			`POST https://api.postmarkapp.com/email/batch`

			`[`
			`{`
			`"From": "sender@example.com",`
			`"To": "user1@example.com",`
			`"Subject": "Notification",`
			`"TextBody": "Hello user 1"`
			`},`
			`{`
			`"From": "sender@example.com",`
			`"To": "user2@example.com",`
			`"Subject": "Notification",`
			`"TextBody": "Hello user 2"`
			`}`
			`]`
			```

			`### List templates`

			```bash
			`GET https://api.postmarkapp.com/templates?Count=100&Offset=0`
			```

			`### Get template`

			```bash
			`GET https://api.postmarkapp.com/templates/{templateIdOrAlias}`
			```

			`### Create template`

			```bash
			`POST https://api.postmarkapp.com/templates`

			`{`
			`"Name": "Welcome Email",`
			`"Alias": "welcome",`
			`"Subject": "Welcome {{name}}!",`
			`"HtmlBody": "<html><body><p>Hello {{name}}</p></body></html>",`
			`"TextBody": "Hello {{name}}"`
			`}`
			```

			`### Get delivery stats`

			```bash
			`GET https://api.postmarkapp.com/deliverystats`
			```

			`### List bounces`

			```bash
			`GET https://api.postmarkapp.com/bounces?count=50&offset=0&type=HardBounce`
			```

			`### Activate bounce (reactivate recipient)`

			```bash
			`PUT https://api.postmarkapp.com/bounces/{bounceId}/activate`
			```

			`### Search outbound messages`

			```bash
			`GET https://api.postmarkapp.com/messages/outbound?count=50&offset=0&recipient=user@example.com`
			```

			`### Get outbound stats overview`

			```bash
			`GET https://api.postmarkapp.com/stats/outbound?fromdate=2025-01-01&todate=2025-01-31`
			```

			`### Get open stats`

			```bash
			`GET https://api.postmarkapp.com/stats/outbound/opens?fromdate=2025-01-01&todate=2025-01-31`
			```

			`### Get click stats`

			```bash
			`GET https://api.postmarkapp.com/stats/outbound/clicks?fromdate=2025-01-01&todate=2025-01-31`
			```

			`### Get server info`

			```bash
			`GET https://api.postmarkapp.com/server`
			```

			`### List suppressions`

			```bash
			`GET https://api.postmarkapp.com/message-streams/outbound/suppressions/dump`
			```

			`### Create suppression`

			```bash
			`POST https://api.postmarkapp.com/message-streams/outbound/suppressions`

			`{`
			`"Suppressions": [`
			`{ "EmailAddress": "user@example.com" }`
			`]`
			`}`
			```

			`## API Pattern`

			Postmark uses simple REST endpoints with PascalCase field names in request/response bodies. Authentication is via custom headers rather than Authorization. Pagination uses `Count` and `Offset` parameters. Email sending is synchronous with immediate delivery confirmation.

			`## Key Metrics`

			`### Delivery Metrics`
			- `Sent` - Total emails sent
			- `Bounced` - Bounce count by type (hard, soft, transient)
			- `SpamComplaints` - Spam complaint count
			- `Opens` - Open count and unique opens
			- `Clicks` - Click count and unique clicks

			`### Bounce Types`
			- `HardBounce` - Permanent delivery failure
			- `SoftBounce` - Temporary delivery failure
			- `Transient` - Temporary issue (retry)
			- `SpamNotification` - Marked as spam

			`### Message Fields`
			- `MessageID` - Unique message identifier
			- `SubmittedAt` - Submission timestamp
			- `Status` - Delivery status
			- `Recipients` - Recipient list

			`## Parameters`

			`### Email Parameters`
			- `From` - Sender address (must be verified)
			- `To` - Recipient (comma-separated for multiple)
			- `Subject` - Email subject
			- `HtmlBody` / `TextBody` - Email content
			- `MessageStream` - outbound (transactional) or broadcast
			- `TrackOpens` - Enable open tracking (boolean)
			- `TrackLinks` - None, HtmlAndText, HtmlOnly, TextOnly
			- `Tag` - Custom tag for categorization

			`### Stats Parameters`
			- `fromdate` - Start date (YYYY-MM-DD)
			- `todate` - End date (YYYY-MM-DD)
			- `tag` - Filter by tag

			`## When to Use`

			`- Transactional emails (password resets, order confirmations, notifications)`
			`- Template-based email sending with dynamic variables`
			`- Monitoring email deliverability and bounce rates`
			`- Tracking email engagement (opens, clicks)`
			`- Managing email suppressions and bounces`
			`- High-reliability email delivery with fast performance`

			`## Rate Limits`

			`- 500 messages per batch request`
			`- 10 MB max per single message (including attachments)`
			`- 50 MB max per batch request`
			`- API rate limits vary by plan`

			`## Relevant Skills`

feat: v2.0 skill renames and CRO consolidation (#291 ) 2026-05-13 22:05:15 -07:00			`- emails`
feat: add 23 new CLI tools and integration guides 2026-02-17 11:28:41 -08:00			`- transactional-email`
			`- email-deliverability`
			`- onboarding-email`