Postal Setup Guide

Overview & scope

This guide covers the Postal-side setup needed to connect your BuildYourMailer / Postal server to MailWizz through the built-in Postal Web Api delivery driver — the recommended way to connect the two (see the MailWizz Setup Guide, which this doc is the companion to).

It assumes Postal is already installed and running (the one-line BuildYourMailer installer) and does not repeat that setup. Four things happen here: decide how to structure Mail Servers and domains, generate an API credential, verify your sending domain(s), and wire up the bounce webhook back to MailWizz.

1. Mail Server & domain architecture

Postal's object model, top to bottom:

• Organization — the top-level container. Can hold one or more Mail Servers.
• Mail Server — its own boundary for credentials (SMTP/API keys), webhooks, message retention and domains.
• Domain — verified per Mail Server (or shared at the Organization level if the same domain needs to send from more than one Mail Server — uncommon for a single-brand setup).

A single Mail Server can hold multiple verified domains, and the API credential is scoped to the Mail Server, not to one domain — Postal signs DKIM by matching whichever domain is in the message's From header against the domains verified on that Mail Server, regardless of which credential made the API call.

That has a direct, practical consequence for how you connect MailWizz, since one MailWizz "Postal Web Api" delivery server = one API key = one Mail Server:

• Domains that should share reputation, quota and warm-up curve → verify them all under the same Mail Server, use one API key / one MailWizz delivery server, and set MailWizz's "Force FROM email" to Never so each campaign's own From address passes through.
• Domains that need isolated reputation, independent warm-up, or belong to different clients/tenants → give each its own Mail Server, its own API key, and its own MailWizz delivery server (Force FROM email = Always on each).
• Default recommendation: one Mail Server per domain unless you have a specific reason to combine them — combining is supported, not required, and since MailWizz's quotas/warmup are per delivery server, domains sharing a Mail Server also ramp together rather than independently.

Create a Mail Server from inside an Organization: Servers → Add Server.

2. Generate the API credential

1. Open the Mail Server you decided on in step 1.
2. Credentials → Add new Credentials.
3. Set Type = API (not SMTP — SMTP credentials are for the older SMTP-relay approach this integration replaces).
4. Save. Postal generates a random string unique to that Mail Server — this is the value that goes in MailWizz's Api key field.

The Postal host itself (e.g. postal.yourdomain.com, no path suffix) is what goes in MailWizz's Hostname field — MailWizz's driver builds the API path itself.

This one credential covers every domain verified on that Mail Server, not just one — you don't need a new credential per domain, only per Mail Server. You also don't need a separate credential for the webhook in step 4; that's configured independently.

3. Add & verify the sending domain

BuildYourMailer ships its own DNS records manager (in the installer menu) that generates and verifies the exact SPF/DKIM/DMARC/return-path records for a domain, reading the DKIM key straight out of Postal. This step is the one thing that has to happen first, in Postal's web UI, before that tool has anything to generate:

1. On the Mail Server, Domains → Add domain — enter the sending domain. This creates the domain record in Postal and generates its DKIM keypair.
2. Run the DNS records manager from the installer menu for that domain — it pulls the real DKIM key from Postal and prints the exact records to publish.
3. Publish those records at your DNS provider and wait for propagation.
4. Back on that domain's page in Postal, run its verification check — Postal independently confirms MX/SPF/DKIM/return-path against what it expects.

If you're combining multiple domains under one Mail Server (step 1), repeat step 1 above for each domain — DKIM keys and verification status are tracked per domain even though they share a Mail Server and API credential.

4. Configure the bounce webhook

This is the Postal-side half of the MailWizz guide's bounce-handling step. On the Mail Server: Webhooks → Add Endpoint.

• URL — the address MailWizz displays after you save its Postal Web Api delivery server:

  https://your-mailwizz-install.com/index.php/dswh/postal

• Events — Postal offers several event types; MailWizz only acts on four of them: MessageDeliveryFailed, MessageDelayed, MessageHeld, MessageBounced. You can subscribe to everything and let MailWizz ignore the rest, or select just those four to keep the payload volume down.

Debugging: Postal keeps the last 7 days of webhook request attempts for exactly this purpose. If bounces aren't reaching MailWizz, check this log before anything else — a redirect response confirms the gotcha above, a connection failure points at firewall/DNS between the two servers, and a clean 200 response means the problem is on MailWizz's processing side, not Postal's delivery.

How Postal actually detects a bounce

Useful background, not something you configure: every message Postal sends carries a unique return-path address, so bounce/auto-reply mail from the recipient's server comes back to Postal, not your real mailbox. When Postal recognizes an incoming message there as a bounce of something it sent, it updates that message's status and fires the MessageBounced webhook — that's what reaches MailWizz. (Genuine non-bounce replies to that same system can optionally be routed to an HTTP endpoint via a route named __returnpath__ on the Mail Server, if you ever want to capture those separately — not needed for MailWizz bounce suppression.)

5. Send limits & IP pools

Set the Mail Server's own send limit (its Settings page) at or above whatever MailWizz's delivery-server quota — or active Warmup Plan step — currently is. If Postal's limit is lower, messages queue or get held on the Postal side even though MailWizz already shows the campaign as sent.

If you're spreading sends across multiple IPs:

1. Enable IP Pools: add use_ip_pools: true under the postal: section of postal.yml, then postal stop && postal start.
2. Create pools from the web UI's IP Pools menu and add the actual IP addresses to each.
3. Assign a pool to an Organization (Organization → IPs) or to a specific Mail Server (its Settings page).

If you set up one Mail Server per IP (mirroring "one Mail Server per domain" from step 1), that's also one API credential and one MailWizz delivery server per IP — consistent with the MailWizz guide's warm-up recommendation to warm each IP independently. One thing worth testing rather than assuming: Daily quotas from an active MailWizz Warmup Plan are exactly the kind of thing that makes MailWizz's Probability-based rotation between servers unpredictable — verify actual per-IP volume in the logs on both sides.

6. Troubleshooting

Support

Need a hand? Contact us and we'll be glad to help.