Stop Losing TYPO3 Emails When Your Mail Server Fails

Most of the time your mail server is fine. Every now and then it hiccups: a transient (temporary) SMTP error like Google’s 421 4.7.0 Try again later (the server’s way of saying “busy right now, try again later”), a short maintenance window, or a rate limit (a cap on how many emails a server accepts in a given time) during a newsletter run.

When delivery fails, standard TYPO3 fires the email and forgets it. There’s no retry, no record, and no alert, so you only find out when someone asks where the email went.

That’s exactly what happened at the Technische Akademie Esslingen (TAE), a training provider that runs 800–1,000 events a year on TYPO3. An outside mail server failed repeatedly, and at first nobody noticed:

Only for half of the way. A provider (an email delivery service such as Postmark or SendGrid) retries the second half—from the provider to the recipient, after it has accepted your email.

If your instance (your TYPO3 installation) can’t reach the provider in the first place, the email was never accepted and exists nowhere. That can happen because of a network blip, an API timeout (the provider’s programming interface didn’t answer in time), an HTTP 429 error (“too many requests”), or a provider outage. Mail Queue isn’t an alternative to your provider; it’s the missing half in front of it.

Teams usually try one of three patches, and each has a catch:

• TYPO3’s built-in spool (a holding area for outgoing emails) doesn’t do what people assume. By default, it retries a failed send three times in the same request (the same page load or form submission) and then drops it. There’s no attempt counter and no distinction between a temporary and a permanent failure. All that’s left is a single log line, with no recipient, no content, and no way to resend.
• Extra infrastructure, like a separate mail relay (a server that only forwards emails) or a mail catcher container (a separately run tool that captures emails instead of sending them) on staging (the test copy of the live site), means more moving parts to run, secure, and explain to a client.
• BCC-ing yourself is the classic developer move. When a registration flow looks broken and you want to prove the email left the system, you add your own address as BCC (blind carbon copy: a hidden copy to another address) and wait. That works once, but as a habit it causes problems: you edit sending code just to debug, recipients’ emails land in someone else’s inbox (a problem under the GDPR, the EU’s General Data Protection Regulation), it’s easy to leave on in production (the live site), and you still learn nothing about the emails that failed.

The real gap is simpler: TYPO3 has no built-in way to see whether an email went out and what it contained.

What we wanted instead was to keep emails instant in the normal case, never silently lose one, and make the whole process visible—without new infrastructure or code hacks.

All of them. Mail Queue hooks into TYPO3’s mail transport (the part of TYPO3 that hands emails to the mail server) rather than into application code—core-near, the way we build. That means it covers every email on the instance: your own extensions, the form framework (TYPO3’s built-in form tool), and felogin (TYPO3’s frontend login) password resets.

You don’t need to change any calling code. The one thing to check is whether an extension actually uses the TYPO3 mailer, which almost every maintained extension does.

If you run several sites from one TYPO3 instance, each can send through its own mail server. Mail Queue remembers which account an email belongs to and always retries through that same account, so a queued email never goes out under the wrong sender. On a single-site install, there’s nothing extra to set up because Mail Queue uses your normal transport.

Setup takes three steps:

1. Install the Composer package (Composer is the standard tool for installing PHP software).
2. Add one line of configuration.
3. Set up two recurring jobs (timed tasks), either in the TYPO3 scheduler or as a cron job on the server.

Until that configuration line is in place, nothing is intercepted or queued. That means you can install Mail Queue now and switch it on when you’re ready. It runs on TYPO3 v13.4.23 or later, and v14.

Yes, and for agencies that’s the useful bit. The module stays hidden until you grant it, and the rights are granular. A trusted editor who runs a site can:

• watch the queue,
• resend a stuck email, and
• redirect an email to a corrected address after a typo in the recipient.

At TAE, the last point matters most. Participants book without a customer account, so nobody tells them when they mistype their address:

For local, staging, and test environments, there’s a stronger guarantee. A manual hold lives in the database, which is fine on production. The catch is that staging regularly imports the production database, and that import carries production’s “keep sending” state along. A manual staging hold gets wiped by the next dump (database copy), and email starts flowing again.

The forceHold setting lives in the deployment config instead (the configuration files that ship with each environment), so a database import can’t clear it. When it’s on, the environment simply never sends, and no admin can lift that by accident.

One practical note: held emails pile up. On staging, set a retention period (how long emails are kept) so the daily cleanup keeps the table and disk in check. A single purge command wipes the queue clean before a demo or after a load test (a test that simulates lots of traffic).

The same hold is useful on production too. For example, you can pause a batch during a planned mail-server migration, then resume, and everything goes out on the next run.

Archive mode closes the last gap. It keeps every sent email and its content until the retention period you set removes it, with the module limited to whoever should see it.

That gives you a real answer to the BCC hack: proof that the license email, the invoice, or the password reset went out, and exactly what it said. It works for every email, with no code changes, and you can resend any of them from the module with one click.

In our projects, email is one of those things that only gets attention when it fails. Mail Queue makes delivery something you can trust and, when needed, prove. You get fewer “where’s my email?” tickets, a clear trail when someone asks, and the option to drop a separate mail catcher on staging. Editors can handle day-to-day queue work (limited to their site on multi-site), admins keep the critical switches, and each site can still use its own mail server.