PlugPress
Send Mailpuff Email Through PostShiba, Mailyard or SMTP
How Mailpuff delivers email: connecting PostShiba, domain verification, warm-up, sending speed, bounce and complaint webhooks, and using Mailyard, an SMTP plugin or PHP mail instead.
Mailpuff sends email through PostShiba, a delivery service built for newsletters that Mailpuff connects to directly. For Amazon SES, Postmark, Resend, Brevo, Mailgun or any SMTP server, install the free Mailyard plugin. An SMTP plugin you already run also works, and your host’s PHP mail is the last fallback. Mailpuff picks the route on its own, and Settings → Sending shows which one it uses.
How does Mailpuff choose the sending route?
Mailpuff checks five routes in order and uses the first one that’s available.
| Order | Route | Used when |
|---|---|---|
| 1 | PostShiba | You connected PostShiba in Settings. Email goes straight to PostShiba’s API and skips wp_mail(). |
| 2 | Mailyard | The Mailyard plugin is active with a provider set up. |
| 3 | SMTP plugin | A known SMTP plugin is active. This includes Mailyard with no provider, which passes mail to your host. |
| 4 | Custom | Other code hooks pre_wp_mail or phpmailer_init. |
| 5 | PHP mail | Nothing else is set up. Your host sends the email. |
On every route except PostShiba, Mailpuff hands each email to wp_mail(), and the plugin behind it delivers it under that plugin’s own terms.
How do I connect PostShiba?
- In PostShiba, create a Full access API key and copy your Team ID. PostShiba’s guide to creating an API key shows where both are.
- In WordPress, open Mailpuff → Settings → Sending, paste both and connect.
- Mailpuff lists the DNS records for your From address’s domain. Add them at your DNS host, including the DMARC record.
- Press Verify. New records can take from a few minutes to a few hours to show up. If a check fails, wait and try again before changing anything.
- Send a delivery test to your own address and check it arrived in the inbox, not spam.
PostShiba approves each new account by hand. Until it does, only your own team receives mail, and Mailpuff’s checklist says so.
An AI agent can do steps 2 to 5 for you with connect-postshiba, get-delivery, verify-sending-domain and send-delivery-test. You paste the key into the chat, and the agent never repeats it back. See the tools reference.
Can I keep the PostShiba key out of the database?
Yes. Define both in wp-config.php, and they take priority over anything saved in Settings:
define( 'MAILPUFF_POSTSHIBA_API_KEY', 'your-api-key' );
define( 'MAILPUFF_POSTSHIBA_TEAM_ID', 'your-team-id' );Mailpuff never shows the key in the admin, in REST answers or to an AI agent, only its last four characters. It’s left out of exports, and Delete all data removes it along with the webhook.
What does warm-up do?
Warm-up raises a new sending domain’s daily limit step by step over 14 days, from 50 emails on day one up to 40,000, so inbox providers learn to trust it. It never goes above your PostShiba plan’s daily limit. Emails past the day’s cap wait for the next day on their own, and the send’s finish time accounts for it.
Warm-up is on for new domains. Turn it off in Settings → Sending only if the domain already sends email regularly.
How fast does Mailpuff send?
- On PostShiba: 4 emails a second, which fits PostShiba’s limit of 300 requests a minute per key. Your plan’s hourly limit is the ceiling, and its daily limit is the daily cap.
- On PHP mail: 100 emails an hour until you set your own limit.
- On other routes: no limit unless you set one.
Set your own hourly limit under Settings → Sending. When PostShiba asks Mailpuff to slow down, the send pauses and picks up later. Nobody is marked failed for a wait, and nobody gets the same email twice.
How are bounces and complaints handled?
When you connect PostShiba, Mailpuff creates a webhook so PostShiba can report back. It lands at /wp-json/mailpuff/v1/webhooks/postshiba.
| PostShiba event | What Mailpuff does |
|---|---|
| Bounce | Marks the address bounced and never mails it again |
| Bounce, type blocked | Records a soft bounce. Three soft bounces within a month mark the address bounced |
| Spam report | Marks the address complained and never mails it again |
| Unsubscribe | Unsubscribes the address |
| Dropped | Treated like the earlier bounce, complaint or unsubscribe that caused it |
Each request is signed with HMAC-SHA256 in the X-Capsule-Signature header, and requests older than five minutes are refused. PostShiba webhooks reach every site on a team, so each message carries a key for your site, and Mailpuff ignores events from other sites.
On other routes, a recipient rejection during a campaign (a 5xx error with a 5.1.x code) marks the address bounced. Connection, sign-in and timeout errors never do. Mailyard reports the bounces it learns about to Mailpuff on its own.
Does Mailpuff work with my SMTP plugin?
Yes. Mailpuff sends through wp_mail(), so WP Mail SMTP, FluentSMTP, Post SMTP and similar plugins deliver campaigns the way they deliver everything else. Settings → Sending tells you which route is in use.
To report bounces from your own mail code, fire this action:
do_action( 'mailpuff_bounce', $email, 'hard', $reason, 'my-plugin' );Use hard or complaint to stop mailing the address at once, or soft to record it. Three soft bounces within a month stop mail to that address too.
Can I send campaigns with my host’s PHP mail?
You can, but it often lands in spam. Send yourself a test first. If it arrives, turn on My host delivers mail under Settings → Sending. Campaign sends stay blocked on PHP mail until you do. Only you can change this switch. An AI agent can’t.
What headers do Mailpuff emails carry?
Every list email has a List-Unsubscribe header and, with one-click unsubscribe on, a List-Unsubscribe-Post header as described in RFC 8058. It also carries a List-Id header, so inboxes file it as a newsletter. The mailpuff_message filter can change a message, but it can’t remove the unsubscribe headers.
FAQ
Do I need a PostShiba account?
No. Mailyard, an SMTP plugin or your host’s mail all work. PostShiba is the route Mailpuff sets up most for you: domain records, warm-up and bounce handling.
Who runs PostShiba?
PostShiba is run by Bento (Backpack Internet Pty Ltd), not by PlugPress. It works under its own terms and privacy policy.
Does the confirmation email use the same route?
Yes. On PostShiba, confirmation emails go through a transactional sending cluster when your team has one, so signup confirmations travel apart from your campaigns.
My send stopped moving. Why?
If Mailpuff says a send has stalled, WordPress’s scheduled tasks aren’t running. Sends pause at the hourly or daily cap on purpose, and that’s not a stall. Check that WP-Cron runs, or set up a real cron job on your server.