Skip to content

// transactional email

Via API

Postmark email verification with pingutil

Postmark is strict about bounces: a hard-bounced recipient can be marked inactive, and later messages to it are not delivered until it is reactivated. Verifying addresses with pingutil before they are saved cuts those hard bounces, and handling Postmark's Bounce webhook lets you ask the affected user for a new address instead of letting their receipts silently stop.

Where it connects: Postmark Bounce webhook, plus your change-email and signup handlers

What goes wrong without it

  • A customer typed hotmial.com once, Postmark marked them inactive, and now they never get their invoices.
  • We can't afford a bounce spike on the stream that carries our password resets.
  • Support spends time on "I never got the reset email" tickets that turn out to be a dead address on file.

What you can do with Postmark and pingutil

  • Verify on signup and on change-email

    Every path that writes an email address (signup, profile edit, invite) calls /v1/verify first, so an address that would hard bounce never becomes a Postmark recipient.

  • Suggest the right address on typos

    did_you_mean catches common provider typos. Offering it before the account exists saves a bounce and an inactive recipient.

  • Turn a Bounce webhook into a fix-your-email prompt

    When Postmark posts a HardBounce for a user, flag their account and show a banner asking for a new address. Verify the new one before saving it.

Set it up

  1. 1

    Store PINGUTIL_KEY with your Postmark server token.

  2. 2

    Wrap every write of a user's email address in a call to POST /v1/verify, rejecting status invalid.

  3. 3

    In Postmark, add a webhook on your message stream with the Bounce event enabled, pointing to your app.

  4. 4

    In the handler, check RecordType is Bounce and Type is HardBounce, then flag the user with that Email.

  5. 5

    When the user submits a replacement address, verify it with pingutil before saving and sending.

Express: Postmark Bounce webhook and a verified change-email route
import express from 'express';

const app = express();
app.use(express.json());

async function verify(email: string) {
  try {
    const res = await fetch('https://pingutil.com/v1/verify', {
      method: 'POST',
      headers: { authorization: 'Bearer ' + process.env.PINGUTIL_KEY, 'content-type': 'application/json' },
      body: JSON.stringify({ email }),
      signal: AbortSignal.timeout(10000),
    });
    return res.ok ? await res.json() : null;
  } catch {
    return null; // fail open
  }
}

// Postmark Bounce webhook (protect it with basic auth in the webhook URL)
app.post('/webhooks/postmark', async (req, res) => {
  const event = req.body;
  if (event.RecordType === 'Bounce' && event.Type === 'HardBounce') {
    await db.users.update({ where: { email: event.Email }, data: { emailBouncing: true } });
  }
  res.sendStatus(200);
});

// User replaces a bouncing address
app.post('/account/email', async (req, res) => {
  const email = String(req.body.email ?? '');
  const v = await verify(email);
  if (v?.status === 'invalid') {
    return res.status(422).json({ error: v.reason, did_you_mean: v.did_you_mean });
  }
  await db.users.update({ where: { id: req.body.userId }, data: { email, emailBouncing: false } });
  res.json({ ok: true, check: v?.status ?? 'unchecked' });
});

declare const db: { users: { update(q: unknown): Promise<unknown> } };
app.listen(3000);

What to do with each result

pingutil resultAction in Postmark
status invalid, reason mailbox_not_foundRefuse to save the address, so Postmark never records a hard bounce for it.
did_you_mean setShow the suggestion in the form before saving.
status risky, reason mailbox_fullSave it, but expect possible soft bounces; check Inactive in the Bounce payload.
status unknownSave and send. If Postmark later posts a HardBounce, your webhook flags the user.

Limits to plan for

  • Postmark's docs treat a hard bounce (TypeCode 1) as an invalid address that should not be emailed again. Reactivation goes through the activate bounce API and depends on the CanActivate field, so preventing the bounce is cheaper than fixing it.
  • Postmark separates transactional and broadcast streams; set up the Bounce webhook on each stream you send from.
  • A pingutil check is a point-in-time answer. Mailboxes can be closed later, so keep the webhook even if every address was verified at signup.

Postmark documentation

Postmark is a trademark of its owner. This integration uses Postmark's documented extension points; it is not an official Postmark app.

Common questions

Should I reactivate a hard-bounced address after pingutil says it is valid?
Only if you have a reason to think the bounce was a one-off and CanActivate is true. A fresh valid result helps that decision but mail servers can change their answer, so a new address from the user is safer.
Does verification slow down the change-email form?
Most checks return quickly, but slow mail servers can take many seconds. Use a timeout of a few seconds and save the address as unchecked if it runs out.

Stop bad addresses in Postmark today

Sign in with your email, create an API key and paste it into the step above. Test on a few real addresses first: the live demo shows exactly what your Postmark setup will receive.