Sign in to fill these examples with your own keys. Sign in Start free trial

Send emails with Mautic

Set Mautic's mailer DSN to PostShiba SMTP.

What you'll build

A Mautic install that sends its segment, campaign, and test emails through PostShiba over SMTP. Mautic keeps your contacts, segments, and unsubscribe links. PostShiba delivers the mail and suppresses addresses that hard bounce or report spam.

This page covers Mautic 5 and later, which configure mail with a Symfony Mailer DSN. Mautic 4 used different settings.

Before you start

  • A Marketing cluster. Newsletters belong on a bulk cluster, not a transactional one, and the type is locked after create. See Clusters.
  • An SMTP username and password. Open your cluster in the dashboard, go to its SMTP credentials, and choose Create SMTP credential. Copy the password right away, because it is shown once. You can also use the SMTP credentials API.
  • A verified sending domain. See Add and verify a domain. Mautic's from address, and the from address of every email you build, must be on it.
  • A cluster that is ready to send (sending_ready is true).
  • Mautic 5 or later. Pacing with max_per_second needs Mautic 6 or later.

Install

Nothing to install. Mautic has SMTP support built in.

Pick a plan for your largest list

PostShiba caps each cluster per hour and per rolling 24 hours. The 24-hour cap must cover your largest segment plus anything else the cluster sends that day.

Plan Emails per hour Emails per 24 hours Mautic max_per_second option
Nano 100 600 Test sends only
Micro 4,000 24,000 1
Small 40,000 240,000 11
Medium 100,000 600,000 27
Large 200,000 1,200,000 55

When a cap is full, SMTP answers 451 4.7.0 hourly send limit reached or 451 4.7.0 daily send limit reached and does not keep the message. Select Resize on the cluster page before a send that would go over. See What happens at your cap.

Send your first email

  1. In Mautic, open Settings with the cog at the top right, then Configuration → Email Settings.
  2. Under Mail Send Settings, set E-mail address to send mail from to an address on your verified domain.
  3. Under Email DSN, enter these values. The user starts with smtp_. Add the option as a row in Options.
mautic-dsn.txt
1E-mail address to send mail from: hello@mail.example.com 2Scheme: smtp 3Host: smtp.postshiba.com 4Port: 587 5User: smtp_9 6Password: YOUR_PASSWORD 7Options: ping_threshold = 20
  1. On Mautic 6 or later, add a second row in Options with max_per_second set to the value for your plan in the table above. The hourly cap divided by 3,600 keeps a long send under the hourly cap.
  2. Leave Custom return path (bounce) address empty. Mautic uses it as the envelope sender, and PostShiba refuses an envelope sender that is not on a verified domain.
  3. Choose Save, then Send test email. Mautic sends it to the address on your Mautic user. The message shows under Events in the PostShiba dashboard.

The smtp scheme upgrades the connection with STARTTLS on port 587 and picks AUTH PLAIN, the only method PostShiba offers. ping_threshold makes Mautic check a connection that has been quiet for 20 seconds and reconnect if PostShiba closed it. Every SMTP setting is on Send emails with SMTP.

If you write the DSN straight into config/local.php instead of using the form, URL-encode the password yourself. The form encodes it for you.

local.php
1'mailer_dsn' => 'smtp://smtp_9:YOUR_PASSWORD@smtp.postshiba.com:587?ping_threshold=20',

Send segment emails from cron

Segment emails sent from the browser need the window open until the send finishes. Send them from cron instead. Mautic sends only published emails this way. --limit caps how many contacts each run picks up, which also spreads a large segment across runs.

broadcasts-cron.sh
1php /path/to/mautic/bin/console mautic:broadcasts:send --channel=email --limit=1000

If you turned on Mautic's email queue, also run messenger:consume email from cron with --time-limit, --limit, or --memory-limit, so each run exits.

Bounces, complaints, and unsubscribes

Bounce emails go to PostShiba, not to Mautic. Mautic's monitored inbox never sees them, so leave its Bounces folder unset. When it is set, Mautic rewrites the envelope sender to that mailbox. PostShiba stops the mail instead.

Event What happens
Hard bounce PostShiba suppresses the address. Later sends to it are refused with 550 suppressed.
Spam report PostShiba suppresses the address the same way.
Soft bounce PostShiba retries delivery. Nothing is suppressed.
Unsubscribe When an email contains {unsubscribe_url}, or the monitored inbox has an Unsubscribe Requests folder, Mautic adds its own List-Unsubscribe and List-Unsubscribe-Post headers. PostShiba leaves them alone, and Mautic marks the contact Do Not Contact. Otherwise, or with Disable unsubscribe link in header turned on, PostShiba adds its own one-click header.

Suppressed addresses still look reachable in Mautic. PostShiba refuses them, so they never reach a mailbox, but they stay in your segments. Copy them into Mautic as Do Not Contact now and then to keep your segments clean.

Copy suppressions into Mautic

  1. Export every suppressed address to postshiba-suppressions.csv. Follow How do I export my suppression list?. It takes a read-only Support key and one script.
  2. Mautic's importer needs a header row, and the export has none. Add one, plus a column set to 1 for every address.
add-dnc-column.sh
1(echo "email,dnc"; sed 's/$/,1/' postshiba-suppressions.csv) > mautic-dnc.csv
  1. In Mautic, open Contacts and choose Import. Upload mautic-dnc.csv and choose Upload and match fields.
  2. Map email to the Email contact field and dnc to Do not contact under the special fields, then start the import. Mautic marks each contact Do Not Contact for email. Addresses that are not in Mautic yet are added as new contacts marked the same way.

Run it again after each large send. Importing an address that is already Do Not Contact does no harm.

Troubleshooting

What you see What to do
Authentication fails Check User and Password. Use scheme smtp on port 587. Port 465 and the smtps scheme are not offered. PostShiba accepts AUTH PLAIN only.
Send test email is missing Mautic shows it only for a saved DSN. Choose Save first.
550 unverified domain The envelope sender is not on a verified domain. Clear Custom return path (bounce) address and the monitored inbox Bounces folder.
550 from header not aligned with verified domain Set E-mail address to send mail from, and the from address on the email itself, to an address on your verified domain.
550 kyc_required Your team is pending production approval. Until then, send only to team members, live inbox addresses, and inbox forward-to addresses. See Does PostShiba require production approval?.
550 suppressed The contact hard bounced or reported spam. Copy suppressions into Mautic as shown above.
451 4.7.0 hourly send limit reached or 451 4.7.0 daily send limit reached The cluster is at its cap and did not keep the message. Lower max_per_second or the cron --limit, or resize the cluster before the next send.
451 4.4.5 too many sessions, slow down Too many Mautic processes opened SMTP connections on one username in 10 seconds. Run fewer mautic:broadcasts:send or messenger:consume processes at once.
421 4.3.2 ... idle too long A connection sat idle for 30 seconds. Add ping_threshold with a value under 30 in Options. See 421 4.3.2 idle too long.

Next steps