# Postmark bounce notifications on your phone

> Get a push notification when an email you sent through Postmark hard-bounces or is blocked, with the address and whether Postmark deactivated it.

- Company: Postmark (https://www.justpush.io/recipes/postmark)
- Event: `Bounce` (Bounce)
- Tags: Email delivery, Email deliverability
- Install: https://studio.justpush.io/recipes/postmark/bounce
- Web page: https://www.justpush.io/recipes/postmark/bounce

## Setup

1. Click Install in Studio and sign in. The recipe is added to your account and you get a personal webhook URL.
2. In Postmark, open your Server, pick the Message Stream (for example Default Transactional Stream) and go to its Webhooks tab.
3. Click Add webhook and paste your webhook URL (shown in Studio after install) as the Webhook URL.
4. Tick Bounce and save. Postmark checks that the endpoint answers before it starts sending.
5. Webhooks in Postmark belong to one **Message Stream** of one **Server**, so add this webhook to each stream you want to watch (for example your transactional and your broadcast stream).
6. These bounce types always push:
7. **Hard bounce**, **Invalid email address** and **Spam notification**: Normal priority.
8. **ISP block**, **DMARC policy**, **Template rendering failed** and **SMTP API error**: High priority, because they usually affect more than one recipient.
9. Other types (soft bounces, transient delays, DNS errors, auto-responders, …) only push when Postmark deactivated the address because of them. Add `?all=1` to the webhook URL to get every bounce:
10. ```
11. your webhook URL (shown in Studio after install)?all=1
12. ```
13. Postmark doesn't sign webhooks. It supports HTTP basic auth in the URL and custom headers, but JustPush doesn't check either yet, so keep your endpoint URL private. When you save the webhook, Postmark checks that the endpoint answers for each event type; that check may produce one test push.

## Code

Studio calls `handleRequest(request)` with the incoming webhook (`{ method, headers, body, query, raw }`) and sends the message object it returns. Returning `null` sends nothing.

```js
// Postmark → Bounce webhook
// Fires when Postmark processes a bounce for an email you sent. Hard bounces, blocks and
// other failures push by default; soft bounces, auto-replies and the like only push when
// Postmark deactivated the address, or with ?all=1.
// Docs: https://postmarkapp.com/developer/webhooks/bounce-webhook

// Bounce types (the "Type" field) that always push, and how loud to be.
const LOUD = {
    HardBounce: 0, // the address is dead; worth knowing, not urgent
    BadEmailAddress: 0,
    SpamNotification: 0,
    Blocked: 1, // High: an inbox provider is blocking you, which hits many recipients
    DMARCPolicy: 1, // High: your domain's authentication is failing
    TemplateRenderingFailed: 1, // High: your template is broken
    SMTPApiError: 1,
}

// Look a key up without tripping over inherited names like "toString".
function pick(table, key, fallback) {
    return Object.prototype.hasOwnProperty.call(table, key) ? table[key] : fallback
}

// A trimmed string, or null.
function text(value) {
    return typeof value === "string" && value.trim() ? value.trim() : null
}

function handleRequest(request) {
    const body = request.body && typeof request.body === "object" ? request.body : {}

    // Guard: only bounces. Spam complaints and subscription changes have their own RecordType.
    if (body.RecordType !== "Bounce") {
        console.log(`Ignoring Postmark "${body.RecordType ?? "unknown"}" webhook`)
        return null
    }

    // ?all=1 on the webhook URL also pushes soft bounces, auto-replies and other noise.
    const all = ["1", "true", "yes"].includes(String(request.query?.all ?? "").toLowerCase())
    const loud = pick(LOUD, body.Type, null)
    const inactive = body.Inactive === true

    if (loud === null && !inactive && !all) {
        console.log(`Skipping Postmark bounce type "${body.Type ?? "unknown"}"`)
        return null
    }

    // "Hard bounce" from Postmark's Name, else the Type split into words ("SoftBounce" → "Soft Bounce").
    const name = text(body.Name) ?? text(body.Type)?.replace(/([a-z])([A-Z])/g, "$1 $2") ?? "Bounce"
    const subject = text(body.Subject)

    return {
        title: `↩️ ${name}`,
        message: [
            text(body.Email) ?? "A recipient",
            subject ? `"${subject}"` : null,
            inactive ? "address deactivated" : null,
        ]
            .filter(Boolean)
            .join(" · "),
        topic: "Postmark",
        // Loud types use their own priority. Others: Normal when the address was deactivated, else Low.
        priority: loud ?? (inactive ? 0 : -1),
    }
}
```

## Postmark Bounce webhook payload (sample)

```json
{
  "ID": 692560173,
  "Tag": "welcome-email",
  "From": "hello@example.com",
  "Name": "Hard bounce",
  "Type": "HardBounce",
  "Email": "sam@example.com",
  "Details": "smtp;550 5.1.1 The email account that you tried to reach does not exist.",
  "Subject": "Welcome to Acme",
  "Inactive": true,
  "Metadata": {
    "customer_id": "cus_1234"
  },
  "ServerID": 23,
  "TypeCode": 1,
  "BouncedAt": "2026-09-29T08:33:54.9070259Z",
  "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
  "RecordType": "Bounce",
  "CanActivate": true,
  "Description": "The server was unable to deliver your message (ex: unknown user, mailbox not found).",
  "DumpAvailable": true,
  "MessageStream": "outbound"
}
```

## FAQ

### Does this work on iPhone and Android?

Yes. Install the JustPush app from the App Store or Google Play and sign in. Every phone signed in to your account gets the notification.

### Do I need to write code?

No. Install the recipe in Studio, paste your webhook URL into Postmark and you are done. The code is there if you want to change the text, the sound or the buttons.

### Can I change what the notification says?

Yes. After install the recipe's code is yours. Edit it in Studio and test it against the sample payload before you save.

### What does it cost?

JustPush is free for 30 days. After that it's $19.99 a year, or $39.99 once. There is no extra charge for recipes.