canonical: https://jentic.com/apis/postmarkapp.com/postmark-api

# Postmarkapp Postmark API

The Postmark API handles transactional email delivery with 43 endpoints covering sending (single, batch, and templated), bounce management, inbound message processing, outbound message search, delivery statistics, and template management. It tracks opens, clicks, and spam complaints with per-message granularity and supports inbound email processing with bypass and retry controls. Authentication uses a per-server token in the X-Postmark-Server-Token header.

## For AI agents

Send transactional emails, track bounces and delivery events, manage templates, and process inbound messages. Provides per-message open and click tracking with detailed statistics.

## Scope

Does not handle account infrastructure setup, domain verification, or sender signature management - use for email sending and delivery tracking only.

## Capabilities

- Send single emails, batch messages, or template-based emails with variable substitution
- Track delivery statistics including opens, clicks, bounces, and spam complaints per message
- Search and retrieve outbound message details with full header dumps
- Process inbound emails with bypass and retry controls for failed messages
- Manage email templates with validation before deployment
- Monitor bounce rates by type and reactivate deactivated recipients
- Configure inbound processing rules with trigger-based routing

## Use cases

### Transactional Email Delivery

Send order confirmations, password resets, and notification emails through Postmark's high-deliverability infrastructure. The API supports single sends, batch sends of up to 500 messages, and template-based sends with dynamic variable substitution. Each message receives a unique MessageID for tracking through delivery, open, and click events. Average delivery time is under 10 seconds for transactional messages.

Example prompt: Send a templated email using POST /email/withTemplate with template alias 'order-confirmation', recipient 'user@example.com', and template model containing order_id and total fields

### Bounce Management and Deliverability Monitoring

Monitor and manage email bounces to maintain sender reputation and high deliverability. The API provides bounce listing filtered by type (HardBounce, SoftBounce, SpamComplaint, etc.), individual bounce details with diagnostic info, and the ability to reactivate recipients who previously bounced. Delivery stats endpoint provides aggregate counts of sent, bounced, and complained messages for trend analysis.

Example prompt: Retrieve all HardBounce records from GET /bounces with type filter, then reactivate a specific bounced address using PUT /bounces/{bounceid}/activate

### Email Analytics and Engagement Tracking

Track email engagement through open rates, click rates, and platform-specific breakdowns. The API provides aggregate statistics by time period, per-message open and click events, and breakdowns by email client, browser family, and geographic location. This enables data-driven decisions about email timing, content optimization, and audience segmentation based on actual engagement data.

Example prompt: Retrieve outbound open statistics from GET /stats/outbound/opens for the last 30 days and compare against click statistics from GET /stats/outbound/clicks

### AI Agent Email Operations

Enable AI agents to send emails, monitor delivery health, and respond to engagement signals through Jentic. Agents discover sending and tracking operations via intent search, receive operation schemas with required fields, and execute without manual API documentation review. Jentic handles token management so agents focus on composing messages and interpreting delivery feedback.

Example prompt: Search Jentic for 'send a transactional email', load the Postmark batch send schema, and execute to deliver 10 notification emails with unique template variables

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /email | Send a single email message |
| POST | /email/batch | Send a batch of up to 500 emails |
| POST | /email/withTemplate | Send an email using a template |
| GET | /bounces | List bounces filtered by type |
| GET | /stats/outbound | Get aggregate outbound delivery statistics |
| GET | /messages/outbound | Search outbound messages |
| GET | /templates | List all email templates |
| POST | /templates/validate | Validate a template before use |

## Key resources

- **Email** — Send single, batch, and templated emails with tracking
- **Bounces** — List, inspect, and reactivate bounced recipients by type
- **Messages** — Search and retrieve inbound and outbound message details with opens and clicks
- **Stats** — Aggregate delivery, bounce, open, click, and spam statistics
- **Templates** — Create, validate, and manage email templates with variable substitution
- **Triggers** — Configure inbound processing rules for routing incoming email

## Why Jentic

- **Setup:** Wiring the Postmark API by hand means setting up its X-Postmark-Server-Token header auth, pointing at api.postmarkapp.com, and building your own retry and bounce-polling logic. Through Jentic you install once, import the Postmark API from the API Directory, store the server token once, and your agent calls it.
- **Permission scoping:** Postmark takes the send target in the request body rather than the URL path, so scoping is by operation: you limit the agent to the operations it needs, such as sending email or reading outbound stats and bounces. Because you pick that set, template validation or batch sending are only included if you add them.
- **Credential handling:** Your Postmark server token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a transactional email' or 'check recent bounces', and Jentic returns the matching Postmark operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Postmark Account-level API** — Account-level API for managing servers, domains, and sender signatures that underpin email delivery
- **SendGrid Mail API** — High-volume email delivery with marketing campaign features and IP pool management
- **SparkPost API** — Email delivery API with predictive analytics and advanced deliverability tools

## FAQ

### What authentication does the Postmark API use?

The Postmark API uses a Server Token passed in the X-Postmark-Server-Token HTTP header. Each server in your Postmark account has its own token. Through Jentic, this token is stored encrypted in the credential vault and agents receive scoped access without handling the raw token value.

### Can I send batch emails with the Postmark API?

Yes. The POST /email/batch endpoint accepts an array of up to 500 messages in a single request. Each message can have its own recipient, subject, and body. For templated batch sends, use POST /email/batchWithTemplates which supports individual template models per message.

### What are the rate limits for the Postmark API?

Postmark limits batch sends to 500 messages per request. Listing endpoints use count (max 500) and offset parameters for pagination. Overall sending rate depends on your account tier and server configuration. The API returns appropriate error codes when limits are exceeded.

### How do I track email opens and clicks with the Postmark API through Jentic?

Install the SDK with pip install jentic, then search for 'track email open rates'. Jentic returns the GET /stats/outbound/opens operation. For per-message click data, search for 'get email click events' to find GET /messages/outbound/clicks/{messageid}. Execute with date range parameters to retrieve engagement metrics.

### Can I process inbound emails with the Postmark API?

Yes. The API provides GET /messages/inbound to list received messages, GET /messages/inbound/{messageid}/details for full message content, PUT /messages/inbound/{messageid}/retry to reprocess failed messages, and PUT /messages/inbound/{messageid}/bypass to skip inbound rules for a specific message.

### How do I validate a template before sending with it?

Use POST /templates/validate with your template content and a sample model object. The API checks for syntax errors and missing variables, returning validation results before you deploy the template to production. This prevents runtime rendering failures when sending to recipients.

### Can I limit what my agent is allowed to do with the Postmark API?

Yes. Because your Jentic One instance is self-hosted, you set the rules that decide which Postmark operations your agent may call and which server token it uses. Postmark takes the send target in the request body rather than the URL path, so scoping is by operation: you can allow the agent to send email (POST /email) and read outbound stats (GET /stats/outbound) and bounces (GET /bounces) while withholding everything else. Batch sending (POST /email/batch) and template validation (POST /templates/validate) are included only if you add them to the agent's allowed set.