How Mautic email delivery and bounce tracking fit together
Sending email and learning what happened to it are two separate jobs in a self-hosted Mautic installation. The configured transport hands messages to a mail provider, and a separate mechanism reports bounces and unsubscribe requests back to Mautic. A team that has set up reliable sending but not bounce reporting will keep mailing addresses that have already failed, and its suppression data will drift from what the provider knows. Choose the transport and the reporting path together, before the first production campaign goes out, and record which path covers each sending provider.
The Mautic emails documentation lists Elastic Email, SparkPost, Mandrill, Mailjet, SendGrid and Amazon SES as supporting webhook callbacks for bounce management. Since Mautic 5, all email transports use the same callback URL, which sits under the /mailer/callback path on your Mautic host. Confirm that your chosen provider appears on that list, configure the callback in the provider's own console, and check that the host name in the URL matches your public Mautic address. The provider must be able to reach that endpoint, so review firewall rules and the reverse proxy in front of Mautic as part of the same change.
IMAP monitoring is the other reporting path. Mautic can watch an IMAP mailbox for bounces and unsubscribe requests by reading return-path addresses that the sending system appends to each message. This only works if the sending path leaves that return-path header intact. The Mautic docs note that services which overwrite the return-path header, such as Gmail and Amazon SES, stop IMAP bounce monitoring from working. Amazon SES appears on the webhook list, but that does not make IMAP usable for SES traffic. Confirm the behavior of your provider and your Mautic version before you depend on either path.
Plan for failure in both directions. If the webhook callback is unreachable or the IMAP mailbox stops receiving messages, bounces and unsubscribes go unrecorded, and campaigns keep mailing suppressed contacts. Mautic relies on cron jobs and a messenger consumer when emails are queued, so confirm that those processes run and are monitored alongside the transport. Test the chain with a controlled send to a known bounce address and a test unsubscribe, check that Mautic records both, and repeat the test after each Mautic upgrade or provider change.
What a Mautic email delivery setup needs before configuration
Six decisions shape how Mautic sends email and receives bounce and unsubscribe events, and each one should be settled before you configure a transport. Together they determine which release you run, where it runs, and how provider events reach it. Confirm current provider-side requirements with each vendor, since those can change independently of Mautic.
Choose the Mautic release line
The release line you pick sets your PHP version, your support window and your upgrade path. Mautic 7.2 supports PHP 8.2 to 8.5 and receives active and security support until 30 September 2026. Mautic 7.3 is planned as the long-term support release with security support through 31 December 2027. Check the Mautic releases page before you commit, because support dates are published per release and can change.
Hosting on a VPS or dedicated server
The Mautic project states that it should not be installed on shared hosting and recommends a VPS or dedicated server. Cron jobs, queue workers and provider callbacks all depend on background processes and outbound connections that a shared plan may restrict. Ask your team or partner to confirm that the target host allows long-running processes, outbound calls to each provider's API, and the scheduling tools you plan to use before you select a plan.
Database and web server stack
Mautic 7.0 requires PHP 8.2, 8.3, 8.4 or 8.5, MySQL 5.7 or higher with InnoDB, or MariaDB 10.2 or higher, and runs on Apache, Nginx or IIS. From Mautic 5.0 onward, npm is also required. Check each component against the release line you chose, and record exact versions in your configuration standard so the database, PHP runtime and web server are patched on a schedule that matches Mautic.
Public HTTPS endpoint for callbacks
Provider webhooks send bounce, complaint and unsubscribe events to your Mautic instance, so the site must be reachable from the internet over HTTPS with a valid certificate. Since Mautic 5, all email transports use the same callback path under your Mautic domain, so one endpoint serves every provider. Confirm that your firewall, reverse proxy and load balancer pass callback traffic through, and that no login page or IP allowlist blocks the provider's sending addresses.
Cron jobs and the messenger consumer
Mautic depends on cron jobs for segment updates, campaign updates and campaign triggers, and the docs say these jobs should be staggered. Segment emails need the broadcasts command, and queued email needs a messenger consumer running as a managed service. If the consumer stops, mail waits in the queue while campaigns appear to run, so set alerts on queue depth and consumer health from the start.
Provider account and authentication records
Create the provider account before configuration, verify your sending domain at the provider, and publish the DNS records it issues. Authentication records, including SPF, DKIM and DMARC, must match the sending domain and the return path your provider uses. The return path also decides whether IMAP bounce monitoring is possible, because some providers overwrite it. Ask each vendor for its current sending, account review and callback requirements in writing.
Webhooks or IMAP: which bounce path fits your sender
Use provider webhooks when your sending service is on Mautic's documented list of bounce callback providers. Use IMAP monitoring only when the sender keeps the return-path header intact from send to delivery. The two methods differ in where the bounce data comes from. Webhooks receive bounce and related events from the provider's own system, while IMAP reads messages that land in a mailbox you control. Make this choice before go-live, because it decides which return-path address your sender uses, what your mail infrastructure must accept, and where Mautic learns about bounces and unsubscribes.
Mautic lists Elastic Email, SparkPost, Mandrill, Mailjet, SendGrid and Amazon SES as supporting webhook callbacks for bounce management. Since Mautic 5, every email transport posts to the same callback path, mailer/callback, on your Mautic hostname. Your team needs to make that endpoint reachable over HTTPS from each provider, then register it in each provider's console under the event types you want. Webhooks need no mailbox and no polling schedule, which keeps the bounce path independent of your mail routing. Confirm that the endpoint is reachable from outside your network before you rely on it.
IMAP monitoring depends on the return-path address appended to each outbound message. Mautic reads a mailbox that receives those bounces and unsubscribe requests. That chain breaks when any service in the path overwrites the return-path header. The Mautic documentation names Gmail and Amazon SES as services that do this, and once the header is overwritten, bounces stop arriving in the monitored mailbox without an obvious error. Teams sending through Gmail or Amazon SES should therefore plan for webhooks. If you keep IMAP as a fallback, send a test message through the full path and inspect the received headers to confirm the return-path survives.
For each provider in your stack, confirm its current event support in the vendor documentation before you choose the method. Check whether hard bounces, soft bounces, complaints and unsubscribe events are all delivered, and whether the provider requires a verification step for the callback. Event coverage and payload formats change over time, and Mautic's list describes which providers support callbacks, not which events each one sends. Ask each provider to confirm these points in writing, and record the answers in your sending runbook so the next reviewer can see what was verified and when.
Plan the operational side as part of the decision. Test each webhook with the provider's test event and check that Mautic records the bounce against the correct contact. If you run both methods during a transition, decide which one is authoritative for each sender so that one bounce is not handled twice or missed. Keep unused IMAP mailbox credentials out of your configuration and remove them once IMAP is retired. Provider fees for sending and for event features come from the provider's own pricing, so request that figure from each provider as part of your quote comparison.
How provider bounce and unsubscribe events map to Mautic contacts
This table maps the main provider event types to the effect Mautic should record on a contact and to the team that reviews each category. Read each effect as a point to confirm for your chosen release, because exact contact fields and do-not-contact behavior are defined in the Mautic emails documentation. Build a version per provider during scoping, since webhook payloads and IMAP limits differ by sending service.
| Event | Effect to confirm on the Mautic contact | Owner who reviews it | Check during scoping |
|---|---|---|---|
| Hard bounce | Address is permanently undeliverable. Confirm whether the contact is flagged and further email sends are blocked. | Marketing operations, list hygiene | Confirm the provider sends permanent failure codes through its webhook |
| Soft bounce | Temporary failure such as a full mailbox. Confirm retry behavior and when repeated failures lead to suppression. | Email operations | Confirm retry thresholds for your release and provider |
| Spam complaint | Recipient marked a message as spam. Confirm whether the contact moves to do-not-contact for email. | Privacy or compliance lead with the marketing owner | Confirm the provider forwards complaint events to Mautic |
| Unsubscribe | Recipient opted out. Confirm the preference or channel state updates and the contact leaves active segments. | Marketing owner and privacy lead | Confirm how unsubscribe requests reach Mautic from each provider |
| Bounce data through IMAP | Return-path monitoring may receive nothing from services that overwrite the return-path header. | Email operations | Decide the webhook path before go-live for Gmail or Amazon SES |
| Missing or failed callback | Events never reach Mautic, so contacts stay mailable. Confirm failed callbacks are logged and retried. | Platform engineering | Set monitoring for callback failures and provider retry settings |
How to configure the Mautic webhook callback in order
This sequence connects your email provider's bounce and unsubscribe notifications to Mautic contact records, so a hard bounce or opt-out affects future sends. Each step closes with a check you can run before moving on. The callback path format follows the Mautic emails documentation for Mautic 5 and later.
Confirm the Mautic release and transport
Record your Mautic version from the administration panel and check it against the Mautic releases page to confirm it sits on a supported release line. Then choose the transport you will use, such as Amazon SES, SendGrid or Mailjet, and confirm that Mautic supports webhook callbacks for that transport. Your Mautic administrator owns this step, and the output is a short written note listing the release, the transport and the named owner of the callback. The step is complete when that note exists and the provider's documentation confirms the bounce and unsubscribe event types you need.
Expose the callback path on your domain
Route the shared callback path, /mailer/callback, on your own domain to the Mautic web server over HTTPS. Since Mautic 5, every email transport uses this same path, so one route serves all providers. Your web or platform team configures the reverse proxy and confirms the path resolves to the Mautic application. Confirm the exact path format in the Mautic emails documentation for your release before publishing it. The check: a request sent from outside your network appears in the Mautic application log, while an unrelated path still returns your normal error page.
Register the callback URL with each provider
In each provider's console, add the full callback address built from your domain and the /mailer/callback path. Subscribe to every bounce and unsubscribe event type the provider offers, because Mautic needs both to update contacts. Your messaging operations owner performs this step. If a provider does not expose one of these event types, confirm that gap in its documentation before assuming Mautic will learn of it another way. The check is the provider's own test event or delivery log, which should show the event reached your endpoint successfully.
Configure transport credentials in Mautic
Enter the credentials the provider issued, such as an API key or SMTP login, in Mautic's email transport settings. Keep the secret values in your secrets manager and out of configuration notes. Confirm that the email queue setting matches your deployment, because queued email requires the messenger consumer to be running. Schedule the cron jobs your release requires, staggered as the Mautic cron documentation describes. The check: the configuration saves and the transport test completes without authentication errors.
Send a test message through the transport
Send a single test email from Mautic to a mailbox your organization controls and confirm the provider accepted it. If your provider offers a bounce simulator, use it, or use an address on a domain you own that is known to reject mail. Use only addresses your organization controls. The check: the message appears in the provider's sending log with a delivered status, and Mautic's email statistics record it as sent. If the message is missing, review the messenger consumer and the transport error log before changing provider settings.
Verify a test bounce updates the contact
Trigger a bounce with the provider's simulator or a test address that hard-bounces, then open the contact in Mautic. Check that the contact's do-not-contact status and timeline entry reflect the bounce, and that the contact is excluded from a later send to that address. Repeat the test with an unsubscribe event. If the contact does not change, compare the provider's webhook delivery log with the Mautic application log for the callback request to find which side failed.
Why Mautic bounce handling stops working and how to fix it
This table lists five common ways Mautic bounce handling stops after a working setup, with the likely cause, the check and the fix for each. Work through the rows in order, because a stalled queue or blocked callback can look like a bounce fault. Confirm every fix against the provider's own event logs, since Mautic only shows bounces that reached it.
| Failure | Likely cause | Check | Fix |
|---|---|---|---|
| IMAP monitoring stops silently | The sender overwrites the return-path header, so appended bounce addresses never reach the monitored mailbox | Send a test to a known invalid address and confirm the bounce arrives in the monitored inbox | Confirm whether your sender preserves the return-path, then move bounce handling to provider webhooks if it does not |
| Callbacks never reach Mautic | A DNS record, TLS certificate chain or firewall rule blocks the provider's request to the callback path | Request the callback URL from outside your network and check the certificate, DNS answer and firewall logs | Correct the DNS record, fix the certificate chain and allow the provider's published source addresses |
| Queued emails never send | The messenger consumer is not running, or cron jobs for campaigns and broadcasts are missing or overlapping | Check the consumer process status, the cron schedule and whether messages sit waiting in the queue | Run the consumer under a process supervisor, stagger cron jobs as the docs describe, then clear the backlog |
| Webhook URL copied from an older guide | Older guides used per-transport callback paths, which Mautic 5 replaced with one shared callback path | Compare the URL saved at each provider with the single callback path under your Mautic domain | Replace the URL at every provider with the current path and remove endpoints for transports you no longer use |
| Provider events not reflected in Mautic | Bounce or complaint events are sent by the provider, but Mautic does not process them | Compare bounce and complaint entries in the provider's event log with the matching contact records in Mautic | Fix the callback or consumer first, then agree with your team how to reconcile contacts that were missed |
Securing provider credentials and callback endpoints
Email transport settings hold the keys that send mail and the endpoint that receives bounce and unsubscribe events. The controls below cover who holds those keys, where they are stored, how the callback is exposed and what happens when a request is rejected. Work through them together, because a weak point in any one of them can stop bounce handling or let forged events change contact records.
Least-privilege provider credentials
Create a separate API key or sending identity for each Mautic instance in each provider, scoped to sending mail and reading the event data that bounce handling needs. Avoid the account owner key, and avoid any key that can manage billing, users or sending domains. For Amazon SES, check whether the IAM policy can be limited to the sending and event actions Mautic calls. Confirm in each provider's documentation which permissions the webhook setup requires, and record which key belongs to which instance so one can be revoked without stopping the others.
Transport secrets outside shared configuration
Transport credentials often reach Mautic through its local configuration file, where they can end up in backups, version control or support tickets. Keep them in a secrets store or in environment variables injected by your orchestration, and limit read access to the web and worker service accounts. Confirm how your Mautic version reads each transport credential, then test that a rotated secret takes effect after a restart and that the old one stops working at the provider.
TLS-only callback endpoint
The mailer callback path should answer only over HTTPS with a valid certificate chain. Refuse or redirect plain HTTP requests at the reverse proxy before they reach Mautic. Set the public site URL in Mautic to the HTTPS address the providers call, so the callback address you register matches what Mautic expects. Track certificate renewal as an operational task, because an expired certificate can stop bounce events from arriving without any visible error in Mautic.
Provider signature verification
Some providers sign webhook payloads so the receiver can confirm that a request came from them. Where the vendor offers signing, verify the signature before any event changes a contact and reject payloads that fail the check. Confirm in the provider's documentation and in your Mautic version whether verification happens inside Mautic, at the proxy or not at all. Also confirm how signing keys are rotated and whether old and new keys can overlap during the change.
Logging rejected callbacks
Record every callback that fails authentication, has a malformed body or references an unknown message. Include the timestamp, provider, source address and rejection reason. Keep these entries apart from routine delivery logs so a rise in rejections stands out. Set retention and access according to your data policy, since the entries contain recipient addresses. Review them on a schedule, because rejected events that go unnoticed mean bounces and unsubscribes stop updating contact records.
Limiting who changes transport settings
Transport settings decide which provider sends mail and which credentials it uses, so changes should be limited to a small, named group. Grant transport access only through the Mautic user roles that need it, and confirm how those roles map to permissions in the version you run, since permission names can change between releases. Keep changes under your change control with a record of who changed what. Review role membership on a schedule and remove access promptly when people leave the team.
How to test bounces and unsubscribes before you send to real lists
Run a written end-to-end test of bounce and unsubscribe handling before any campaign goes to a live list. The test should prove four things in order: the provider emits the event, the event reaches Mautic's callback, Mautic changes the contact record correctly, and the unsubscribe link stops future marketing email. Each step can fail independently, so test each one and record what you saw rather than assuming the chain works because the transport sends mail. Start with the provider's own test addresses. Most providers in the Mautic callback list, including Amazon SES, SendGrid and Mailjet, publish mailbox addresses that simulate a hard bounce, a soft bounce and a complaint. Confirm the exact addresses in the current provider documentation before you rely on them, because they change. Send one message to each address through the transport you plan to use in production, then check the provider's event log to confirm it recorded the outcome you expected. Next, confirm the event arrives at the callback. Your configured callback URL should be the one Mautic documents for all email transports, https://mautic.example.com/mailer/callback, with your own domain in place of the example. Check the web server access log for the POST request and the HTTP status Mautic returned. A request that is blocked by a proxy, a firewall rule or a signature check will look like a provider failure unless you inspect the server side. Then open the test contact in Mautic and confirm the bounce or complaint is reflected on the record and that the contact no longer receives sends from the affected segment or campaign. Repeat the check for any contact field or tag your team uses to flag bounces. Test the unsubscribe link as a contact would. Send a message containing the link to a test contact, click it from a browser that has no active Mautic session, and confirm the preference change is saved. Send a campaign or broadcast to that segment afterwards and confirm the contact is excluded. If you rely on IMAP monitoring instead of webhooks, do not expect return-path bounces to appear for transports that overwrite the header, such as Amazon SES or Gmail. Test that path separately and treat a silent result as a failure to investigate, not a pass. Repeat the full plan after every Mautic upgrade and after any change to the transport, the callback URL, the web server or the provider account. Keep the dated results, the provider event IDs, the callback log excerpts and screenshots of the contact record together. Attach them to the team's change record so that an auditor or a future engineer can see what was tested, when, and against which Mautic release.
Questions teams ask before outsourcing Mautic email delivery
How does the number of email providers change the effort of outsourcing Mautic delivery?
Each provider adds its own work, so the number of providers is one of the largest effort drivers. Every transport needs credentials, a sending identity, and a bounce or event setup that matches how that provider reports results. Since Mautic 5, all email transports use the same callback path, mailer/callback, on your Mautic domain. That removes one variable but not the provider-side configuration. Teams sending through two or three services usually need separate tests for each path, plus a check that suppression works the same way across all of them. Ask any partner to list each provider in the written scope, with the account type and access level for each one.
Does IMAP bounce monitoring make the delivery work harder?
Yes, IMAP monitoring usually creates a separate track of work. Mautic can read bounces and unsubscribe requests from an IMAP mailbox using appended return-path addresses. The Mautic docs note that services which overwrite the return-path header stop this from working, and they name Gmail and Amazon SES as examples. If your senders overwrite return paths, IMAP monitoring will miss those events, so bounce handling must move to provider webhooks or accept gaps in the data. Check which senders your organization uses, whether any mailbox still receives returns, and whether your DNS and mailbox access support the routing you need before setting the scope.
Which bounce and complaint volumes should we give a partner before asking for a quote?
Give monthly counts of bounces, complaints and unsubscribes for each provider, taken from current logs or provider dashboards. These figures shape how much testing, event reconciliation and suppression logic the build needs, and how much ongoing monitoring a retainer should cover. Include the segments and campaigns that send most often, because high-frequency sends expose handling gaps faster. If you cannot export events yet, say so in the request and state the period you can reconstruct. A quote follows from the written scope, so ask the partner to state which volumes they assumed and how they will test at that load.
How do cron jobs and queue workers affect email delivery work?
Email delivery depends on scheduled jobs running correctly. Mautic relies on cron jobs for segment updates, campaign updates and campaign triggers, and the docs say these should be staggered. Segment emails also need the broadcasts command, and queued emails need a messenger consumer running. If the current host runs these from a single crontab with no monitoring, expect time spent on process supervision, logging and overlap control before bounce handling works reliably. Document how each job runs today, who restarts them and what happens when a worker stops. These checks belong in the written scope because they affect both the build and the handover to your team.
Can our own team set up Mautic email delivery without an outside partner?
Often yes, if the team has the skills and access. A capable internal team can configure a transport, set up provider webhooks and verify bounce events. The work gets harder when several providers are involved, when IMAP and webhook monitoring must run side by side, or when DNS, mail identities and cron supervision belong to different owners. Assess skills in PHP and Symfony-based applications, DNS administration, mail authentication settings, Linux service management and provider console access. Map who owns each access item before deciding. Many teams split the work, with internal staff keeping provider accounts and DNS while an outside partner designs and tests the bounce handling.
What must we provide before work starts on email delivery?
Provide provider access, DNS control and a test list, along with a current inventory of your setup. Provider access means console or API credentials with rights to create or review sending identities, webhooks and event destinations, ideally with a named owner for each account. DNS control means someone who can publish or change the records your sending domains need. The test list should include internal mailboxes and seed addresses you control, so bounces and unsubscribes can be tested safely. Also provide your Mautic version, hosting layout, cron and queue configuration and the list of Mautic instances. Confirm each item in writing before the scope is final.
How long does outsourcing Mautic email delivery take?
Duration depends on the written scope, so ask for the work in phases with named deliverables and dependencies. The biggest variables are the number of providers, whether IMAP monitoring must be retired or kept, the volume and quality of current bounce data, how many Mautic instances share the setup and how quickly your team grants access and makes DNS changes. Approval steps and testing windows also affect the calendar. Ask for milestones linked to each deliverable, with the assumptions behind them listed in the scope. Any end date should appear in the signed scope, not in a verbal estimate.
Does running several Mautic instances multiply the delivery work?
It can, because each instance has its own transport settings, cron jobs, queue workers, callback configuration and bounce data. Work repeats per instance unless the instances share a deliberate configuration. Shared components such as provider accounts and sending domains reduce duplicate effort only when they are designed to be shared. Tell the partner how many instances exist, which ones send through the same providers and whether they share a database or mail identity. Ask the written scope to state which settings are configured once and which must be repeated and tested for each instance.
How DeployOpen scopes and supports Mautic email delivery
DeployOpen plans, implements, documents and supports self-hosted Mautic inside your own infrastructure. For email delivery and bounce handling, the work starts with your sending transport and how bounces and unsubscribes will reach Mautic, then moves through configuration, testing and handover. Engagements are fixed-scope, and the written scope is agreed before work starts.
How we scope
- The written scope names your sending transport, such as Amazon SES, SendGrid, Mailjet or another supported provider.
- It records whether bounces and unsubscribes will arrive through provider webhooks or IMAP monitoring, and why.
- Scope also covers sending domains, return-path handling, the cron and messenger workers, and who owns provider account changes.
How we build
- Configure the chosen transport in Mautic and register the provider's bounce and complaint notifications against your Mautic domain.
- Set up cron jobs and the messenger consumer for queued email, staggered as Mautic documentation advises.
- Test sends, simulated bounces and unsubscribe handling in a staging environment before any live traffic is switched on.
How we hand over
- Document the transport settings, webhook endpoints, IMAP mailbox settings if used, and the failure modes we tested.
- Hand over runbooks for rotating provider credentials, checking callback delivery and clearing suppression lists.
- Walk your operations team through the evidence trail for bounces and unsubscribes that compliance reviewers may request.
How we support
- Ongoing support is available as a retainer, covering provider changes, Mautic upgrades and bounce handling checks.
- Revisit the transport choice when a provider changes its return-path behavior or a Mautic release changes mail handling.
- Confirm each provider's current webhook and return-path support with the vendor before you commit to a design.
