Postmark Webhooks

Postmark Webhooks receives bounce, spam complaint and delivery notifications from Postmark and suppresses outbound Drupal mail to addresses that bounced or complained. It does not send mail; pair it with the Postmark module or another backend using Drupal's mail manager.

Features

• HTTP Basic Auth with a timing-safe password comparison. An unconfigured endpoint returns 503; missing or incorrect credentials return 401.
• Hard-bounce suppression without a time window, soft-bounce suppression for 30 days by default, and configurable spam-complaint windows.
• Case-insensitive recipient matching, MessageID retry acknowledgement, and mailbox-redacted watchdog messages.
• Event history with no raw JSON payload storage and configurable cron retention, defaulting to 90 days.
• Settings form and drush postmark-webhooks:status [email protected].
• Listed in the Chronicle package group on Drupal's Extend page.

Post-installation

Install with composer require drupal/postmark_webhooks:^1.0@alpha and enable Postmark Webhooks. Put the secret in settings.php, not exported configuration:

$settings['postmark_webhooks.webhook_secret'] = getenv('POSTMARK_WEBHOOK_SECRET') ?: '';

In your Postmark server's message stream, configure bounce, spam complaint and delivery webhooks using https://postmark:[email protected]/api/webhooks/postmark. Replace the example host and encoded password. Postmark sends the password through HTTP Basic Auth; the admin UI never displays it.

Use HTTPS and an edge IP allowlist using Postmark's current webhook IP addresses. Preserve the Authorization header through proxies. Postmark does not provide X-Postmark-Signature or HMAC signatures; see its webhook documentation.

Visit /admin/config/services/postmark-webhook to configure suppression and retention. HardBounce, BadEmailAddress, ManuallyDeactivated and Unsubscribe bounce types suppress without a time window. Transient, SoftBounce, DnsError, MailboxFull and MessageTooLarge use the soft-bounce window (0 disables it). SpamComplaint and SpamNotification use the complaint window (0 means no time limit). Delivery, Open, Click, Subscribe and unknown events are log-only.

Requirements

PHP 8.3 or later, Drupal 10.3 or 11, and a Postmark account configured to send webhooks. No mail-sending module is required merely to receive events.

Similar projects

Postmark provides outbound sending. Postmark Webhooks provides receiving and Drupal-side suppression. Mail System can select a backend that uses Drupal's mail manager.

Known limitations

• Native Symfony Mailer transports can bypass hook_mail_alter and are not suppressed. This release has no Symfony Mailer event subscriber.
• Retention deletes hard bounces and complaints too. A purged event cannot suppress mail, even when its suppression window is called permanent. Set retention to 0 to keep history indefinitely.
• MessageID deduplication is global across event types and covers sequential retries. Later events with an already recorded MessageID are ignored; concurrent retries have no unique database constraint.
• Suppression handles one recipient, optionally with a display name. Multi-recipient To, Cc and Bcc lists are not individually filtered.
• This is not an inbound email parser and does not synchronize Postmark's server-side suppression list.

Supporting organizations

Maintained by Jeremy Michael Cerda. Development sponsored by Wilkes & Liberty, LLC. Licensed under GPL-2.0-or-later.