canonical: https://jentic.com/apis/postalserver.io/postalserver

# Postalserver Postal API

Postal is an open-source mail delivery platform providing an HTTP API for sending transactional and operational emails. The API supports structured message sending with recipient lists, CC, BCC, attachments, and custom headers, as well as raw RFC 2822 message submission. It also provides message retrieval and delivery tracking endpoints to verify whether emails reached their destination.

## For AI agents

Send transactional emails with attachments and custom headers, submit raw RFC 2822 messages, and track delivery status through a self-hosted mail server.

## Scope

Does not handle email marketing campaigns, contact list management, or template design - use for transactional email sending and delivery tracking only.

## Capabilities

- Send structured emails with multiple recipients, CC, BCC, and file attachments
- Submit pre-crafted RFC 2822 messages for full control over email formatting
- Retrieve sent message details including status, timestamps, and routing metadata
- Track delivery attempts and outcomes for individual messages
- Tag messages for categorization and filtering in delivery reports

## Use cases

### Transactional Email Delivery

Send order confirmations, password resets, and notification emails through a self-hosted mail server. The Postal API accepts structured parameters including recipient lists, HTML and plain text bodies, custom headers, and base64-encoded attachments. Messages are tagged for tracking and return a unique message ID for delivery verification.

Example prompt: Send an email via the `/send/message` endpoint to user@example.com with subject 'Order Confirmed', an HTML body, and tag 'order-confirmation'

### Email Delivery Monitoring

Track whether sent emails reached their destination by querying the deliveries endpoint for a specific message. Postal returns delivery attempt details including SMTP response codes, timestamps, and failure reasons, enabling automated alerting when critical emails bounce or get deferred.

Example prompt: Retrieve the delivery status for message ID 12345 using the `/messages/deliveries` endpoint and check whether delivery succeeded

### Raw Message Submission for Migration

Submit pre-formatted RFC 2822 email messages for scenarios where the full message is already constructed, such as email migration tools, mailing list software, or relay configurations. The raw endpoint accepts base64-encoded message data with explicit MAIL FROM and RCPT TO parameters.

Example prompt: Send a raw RFC 2822 message via the `/send/raw` endpoint with mail_from set to sender@domain.com and rcpt_to containing the recipient address

### AI Agent Email Sending via Jentic

AI agents use Jentic to discover Postal operations by intent, such as 'send a transactional email'. Jentic returns the sendMessage operation schema with required fields (to, from) and optional fields (subject, html_body, attachments), then handles X-Server-API-Key injection so the agent sends emails without managing server credentials.

Example prompt: Search Jentic for 'send a transactional email', load the sendMessage schema, and execute an email delivery to notify@example.com with a plain text body

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/send/message` | Send a structured email with recipients, body, and attachments |
| POST | `/send/raw` | Send a raw RFC 2822 formatted message |
| POST | `/messages/message` | Retrieve details of a sent message by ID |
| POST | `/messages/deliveries` | Get delivery attempts for a specific message |

## Key resources

- **Messages** — Send structured or raw emails, retrieve message details, and track delivery outcomes

## Why Jentic

- **Setup:** Wiring the Postal API by hand means handling its X-Server-API-Key header and pointing requests at your own self-hosted Postal domain yourself. Through Jentic you install once, import the Postal API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Postal takes its message and query inputs in the request body, so you limit the agent to the operations it needs, such as sending a message or checking deliveries. Raw-message sending is included only if you add it.
- **Credential handling:** Your Postal server API key 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 delivery status', and Jentic returns the matching Postal operation with its input schema so the agent calls the right endpoint without browsing the self-hosted documentation.

## Related APIs

- **SendGrid Mail API** — Cloud-hosted email delivery with analytics, templates, and deliverability tools
- **Postmark Server API** — Managed transactional email service focused on delivery speed
- **Mailjet API** — Cloud email delivery with real-time analytics and template management

## FAQ

### What authentication does the Postal API use?

The Postal API authenticates using an X-Server-API-Key header. This key is created through the Postal web interface for each mail server. Through Jentic, the server API key is stored encrypted in the vault and injected into request headers automatically.

### Can I send emails with attachments using the Postal API?

Yes. The `/send/message` endpoint accepts an attachments array where each attachment includes a name, content_type, and base64-encoded data field. You can attach multiple files to a single message.

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

Since Postal is self-hosted, rate limits depend on your server configuration and infrastructure capacity. There are no externally imposed API rate limits. Throughput is determined by your mail server's processing capacity and outbound IP reputation.

### How do I check email delivery status through the Postal API with Jentic?

Install the SDK with pip install jentic, then search for 'check email delivery status'. Jentic returns the getMessageDeliveries operation schema requiring a message id parameter. Execute the call with your message ID to receive delivery attempt details including SMTP response codes.

### What is the difference between `/send/message` and `/send/raw`?

The `/send/message` endpoint accepts structured parameters (to, from, subject, html_body, plain_body, attachments) and Postal constructs the email. The `/send/raw` endpoint accepts a pre-built RFC 2822 message as base64-encoded data, giving full control over headers and formatting for migration or relay use cases.

### Is the Postal API free to use?

Yes. Postal is open-source software that you host on your own infrastructure. There are no per-email fees or API usage charges. Costs are limited to your server hosting and any DNS or IP reputation services you choose to use.

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

Yes. Because you self-host Jentic One, your own rules decide which Postal operations and credentials the agent may use, so you can allow it to send a message and check deliveries while withholding everything else. Postal takes its inputs in the request body, letting you scope the agent to just the endpoints it needs, such as `/send/message` for sending and `/messages/deliveries` for tracking. Raw RFC 2822 submission via `/send/raw` is available only if you explicitly add it. Your Postal server API key is injected at execution time and never enters the agent's prompt or logs.