# Postmark (send email)

Send transactional email through Postmark.

URL: https://docs.qaldy.com/connectors/postmark/

- **Status:** [[Available]]
- **Shelf:** Email
- **How you connect:** API key
- **Regions:** global (not available to Kazakhstan-only workspaces)
- **The service’s own API reference:** https://postmarkapp.com/developer/api/email-api

Apps send transactional email through **Postmark**. It is reached through the HTTP API connector
with a preset: the gate calls only `api.postmarkapp.com`, only with `POST`, only under `/email`.
The Server API token is sealed to the gate and apps never see it.

> **Status: Available through the HTTP API preset.** The preset follows Postmark's Email API
> reference (checked 2026-10-16). It has not been run against a live Postmark server; the first
> real send is the first real test.

## Connect it

1. In Postmark, open your **server** → **API Tokens** and copy the **Server API token**
   ([account.postmarkapp.com/servers](https://account.postmarkapp.com/servers)). A server token
   can send only through that server.
2. Confirm the sender signature or domain you will send from. Postmark refuses a `From` address it
   doesn't know.
3. Qaldy → **Connectors** → Postmark → **Connect Postmark** → paste the token → **Seal and
   connect**.

**Test connection** only checks that the sealed token opens. The only call the gate allows is a
send, so a test would have to send an email; it does not.

To send from your own domain, see send-from-your-domain.md: the records to
add, and a check in Settings, Domains that reads your DNS and says which are in place.

## What the gate allows

| | |
|---|---|
| Host | `api.postmarkapp.com` (pinned, every resolved address public) |
| Methods | `POST` |
| Paths | `/email` and below (`/email`, `/email/batch`, `/email/withTemplate`) |
| Key | `X-Postmark-Server-Token: <token>`, added by the gate; an app-supplied one is dropped |
| Fixed header | `Accept: application/json` |

## Use it from an app

```json
{ "id": "http", "actions": ["request"], "scope": "conn_k3v9…" }
```

```ts
const api = ctx.connectors.http('conn_k3v9…')
await api.post('/email', {
  json: {
    From: 'orders@mossember.example',
    To: 'aigerim@example.com',
    Subject: 'Beans are below 5 kg',
    TextBody: 'Reorder before Friday.',
    MessageStream: 'outbound',
  },
})
```

Postmark reports a problem with an `ErrorCode` and a `Message` in the reply (a `422` for most of
them, `401` for a bad token); the connector throws it as an `upstream_error` carrying that message.
With `throwOnError: false`, read `res.body.ErrorCode` yourself (`0` is success).

## When it breaks

| You see | Why | Do |
|---|---|---|
| `ErrorCode` 400 | The sender signature or domain isn't confirmed | Confirm it in Postmark |
| `ErrorCode` 406 | The recipient is inactive (a past bounce or complaint) | Reactivate it in Postmark, or send elsewhere |
| `401` | The token was revoked or mistyped | Replace the token |
| Blocked: `path_not_allowed` | The app called a path outside `/email` | The preset only allows sending |