Setting up push and email notifications in XenForo 2.3

XenForo talks to members in two official pipes: email (lost password, conversations, watched-thread mail, 2FA links) and push (the same alerts system, delivered to a device that installed the PWA). You set email under Setup → Options → Email options. You set push under Setup → PWA setup. There is no third “notifications app” in core. If mail does not leave the box, 2FA-by-email and security-lock resets are theatre. If PWA is half-configured, push is a checkbox that does nothing.

This is not the engagement article. That one is about why people come back. This one is the transport: which of the three official mail methods you pick, which addresses you print on the envelope, what HTTPS and icons a PWA demands, and why iOS will not push until the member uses Add to Home Screen. It is also not the security checklist, except where mail is a security control.

Official sources: Email (docs.xenforo.com/manual/configuration/email), PWA (docs.xenforo.com/manual/configuration/pwa), Checks and tests (PWA setup reports capability). Community 2.3: push is the checkbox near the bottom of PWA setup; browser permission and cookies decide whether this browser will prompt again.

Two pipes, one alerts system

Members already have alerts (the bell). Official PWA chapter: XenForo’s alerts system integrates with the device notification tray so those alerts can appear even when the user is not browsing the forums. Push is not a second product with a second preference matrix. It is alerts, off-site.

Email is older and wider:

• Lost password and “must reset password” security lock
• Email-link two-step verification
• Conversation mail, watched forums/threads, mention mail — whatever you have enabled in user preferences and options
• Contact users / staff mailings
• Bounce handling, if you gave a bounce address

A board can live on email alone. A board cannot live on push alone: iOS will not see push until the PWA is installed; desktop users will dismiss the permission prompt; guests have no alerts. Ship email first. Turn on push the same week you have HTTPS and icons.

Job	Email	Push
Lost password / security lock reset	Required	No
Email-link 2FA	Required if that provider is on	No
“Someone quoted you” while the app is closed	Works if they watch/mail	The reason PWA exists
Guests	Only if you mail them as an admin	No
iOS	Works in Mail.app	Only after Add to Home Screen (16.4+)

Email options — the three transports

Immediately after install, official says XenForo can send mail on most servers using PHP’s default mailing settings. When you want control, Setup → Options → Email options (the manuals also say Options → Email options group).

Email transport method has three official values:

1. PHP built-in mail

Uses PHP’s default mail() configuration. Official: preferred, because it offloads the actual send to a dedicated program on the server and gives better performance. On a well-run VPS that already has Postfix/Exim/OpenSMTPD sending as your domain, this is the right box.

It is not “no configuration.” The OS still needs a smarthost or local delivery that downstream providers will accept. XenForo just is not speaking SMTP itself.

Use this when: the host documents “PHP mail works,” you can send a test to Gmail/Outlook without it dying in spam, and you do not need per-message SMTP auth inside XF.

2. SMTP

Uses an outside server. Official: in some situations this reduces the chance mail is seen as spam. Official cost: slower, because each mail is sent by XenForo rather than handed to a local daemon.

You will type host, port, encryption, username, password — the ACP form is the source of the field names; the public email page does not reprint every input. Typical submission ports in the wider world are 587 (STARTTLS) or 465 (implicit TLS). Official does not mandate a port. Use what the provider documents.

Use this when: PHP mail is disabled (common on locked shared hosting), or you already pay for a transactional provider and want XF to auth to it directly.

Use it knowing: a slow SMTP handshake on every watched-thread mail is why official calls this slower. A busy board plus SMTP plus a remote API on the other side of the planet is a job queue you will feel.

3. Google OAuth

Official wording: Google is moving toward not accepting standard SMTP credentials, expecting an OAuth token instead. To use this method you create a project in Google’s Developer Console with OAuth 2.0 credentials for a web application. Step-by-step instructions are on-screen inside XenForo during OAuth setup. This article will not invent a screenshot tour that will rot. Follow the ACP.

Official also points at a community post for more OAuth context (assorted improvements, post 1437261). Use that if the on-screen steps disagree with Google’s current console labels — Google renames menus; XF’s wizard is what the 2.3 product ships.

Use this when: the mailbox you must send from is Google Workspace / Gmail and app passwords / SMTP auth are no longer acceptable. Do not use it because it sounds modern if PHP mail already delivers.

Which one to pick (decision, not a product)

Situation	Transport
VPS with a working local MTA, SPF/DKIM already on the domain	PHP built-in mail
Shared host that blocks mail(), or you already have SMTP credentials	SMTP
Google is the mailbox and refuses SMTP passwords	Google OAuth
You do not know	Send a test with PHP mail. If it never arrives, SMTP. If the mailbox is Google and SMTP is rejected, OAuth

There is no official “Microsoft OAuth” row on the email page. Community threads mention people trying Microsoft; this article will not document a core wizard that the manual does not list. If your ACP shows an extra provider in a later 2.3 point release, believe the ACP.

Addresses and the sender name

Official additional options — set all three the same day you pick a transport:

Default email address. Most mail XF sends appears to come from this address. Official: it must be a valid email address. It should be a mailbox (or a plus-address) on a domain you control, with SPF (and DKIM if you can) allowing the machine that actually sends. noreply@ is fine if you do not want replies. admin@ is fine if you read it. webmaster@localhost is how you fail every spam check.

Bounced email address. When a message cannot be delivered, the bounce goes here. Official: if you leave it empty, bounces go to the Default email address. Use a dedicated bounces@ if you intend to read them (or to point a filter at them). Official email chapter does not, in the public page cited here, walk an automatic bounce processor. There is community discussion of bounce handling with Gmail and OAuth; treat that as extra, not as a core toggle this article will invent. For most boards, a real mailbox you glance at monthly is the requirement — so you notice “user does not exist” after a phpBB import.

Default email sender name. Official: normally the sender name is your Board title. This option overrides that with a more reasonable name. Board titles like “The Unofficial Late-Night Homebrew and Tactics Collective” become a useless From header. Use a short name members will recognize: Harbor Staff, Northwind Forum. This is not the PWA Board short title. Different fields, different jobs.

Prove mail works before you touch PWA

XenForo’s ACP has long offered a way to send a test message from email options (community / ACP practice). If your build’s Email options page has a test button, use it — to an address you control on a different provider than the one you send from. If the page has no test button, register a throwaway user and trigger lost password. That is the same pipe 2FA email and security lock will use.

Pass criteria:

• It arrives within a few minutes
• From address is the Default email address
• From name is the sender name you set (or Board title if you left that blank)
• It is not in spam, or you know why and will fix SPF/DKIM
• Links in the mail point at your https Board URL

Fail criteria: silent void, 550 relay, Google “less secure app,” or a From that shows as apache@box.example. Fix transport before you mandate email 2FA.

Contact users and watched-thread mail will multiply whatever you just tested. A transport that “works once” and dies at volume is an SMTP timeout or a provider rate-limit — look at the server mail log, not at a new add-on.

PWA setup — what the product actually is

Official pitch: XenForo does not require a separate native app. On a small viewport it becomes a progressive web app. Responsive layout happens automatically. The rest needs Setup → PWA setup.

Official feature list (so you do not sell members a store listing you do not have):

• Responsive design — single column, larger hit targets, secondary chrome in menus
• Installability — an icon on the device; launch without opening the browser chrome the same way
• Push notifications — alerts in the OS tray while they are not on the site
• App badging — a counter of active notifications on the icon
• Share sheet — share controls use the device’s native share UI

That is the product. No App Store review. No separate push vendor in core.

Absolute PWA requirements

Official, numbered:

1. The site must be accessible over HTTPS / SSL
2. You must provide a title of 12 or fewer characters
3. You must provide two square icons: 192 pixels and 512 pixels

Miss any one and PWA functionality does not enable. The PWA setup page automatically tests and reports whether the system can provide PWA (official Checks and tests). Believe that report. Do not argue with a red X by installing a “PWA add-on.”

HTTPS

Same control as security. Certificate, Board URL https://…, no mixed-content loop. Push subscription APIs will not run on http://.

Title vs Board short title

If the main Board title is already ≤ 12 characters, you are done. If it is longer — it usually is — official: enter a shortened version in Board short title.

Count characters. “Northwind RP” is 12. “Northwind Roleplay” is not. The short title is what install prompts and home-screen labels can actually show. It is not a slogan. It is not the email sender name.

Icons

Upload or paste URLs for:

• 192×192
• 512×512

Official: PNG as a general rule. Square. Ideally maskable — important graphics sit inside the safe zone so adaptive icon masks (Android especially) do not crop the mark off. If they are maskable, check the box that says so. Official points at web.dev’s maskable-icon write-up for the geometry.

Do not upload a 512 JPG with a wordmark that goes to the edge. Do not use a screenshot of the logo. Do not put the two files only in data/ without going through the PWA setup fields — the product needs the URLs it stores there.

Enable push notifications

On Setup → PWA setup, official: you may enable push notifications if the server has PHP 7.1 or newer with gmp, mbstring, and openssl. XenForo Cloud meets this. Self-host: php -m on the same PHP the site uses (php-fpm, not a random CLI 7.4). Missing gmp is the usual miss. The PWA page’s own test should tell you.

Community 2.3: the enable control is a checkbox near the bottom of PWA setup. After it is on, a browser prompt asks the member. If they already allowed or denied, you will not see the prompt again until they reset site permissions (or, as community notes, cookies — push preference can live there). That is a browser rule, not a missing XF option.

Push is off until:

• HTTPS is real
• PHP extensions are present
• You ticked enable
• The member granted permission
• On iOS, they also installed the PWA (next section)

Alerts the member has muted in Preferences will not start firing as push just because PWA is on. Push delivers alerts they already receive. It does not invent new events. There is no official core “push campaign” composer separate from alerts / notices. Notices are on-site chrome. Push is the bell, elsewhere.

iOS 16.4+: Add to Home Screen is mandatory for push

Official Installability: Apple devices on iOS 16.4 and newer can install the PWA with Safari’s Add to Home Screen. Official: this step is required to enable push notifications on iOS.

Say that in your onboarding and on a help page. Members who “turned on notifications” in Safari without installing will file a bug that is Apple’s model, not yours. You cannot ACP around it. There is no official “iOS push without PWA install” switch.

Android and desktop Chromium can prompt more like a normal site. Still ask them to install if you want badging and an icon.

Language and colors

Official PWA Language: you must choose one of the languages installed on the forum as the primary language for the PWA. One. Not “whatever the user picked in XF.” A multilingual board still has a single PWA language. The later multilingual article in this series owns the language pack tree; here: pick the language most installers will expect.

Official Colors:

• The PWA’s general styling follows the default style
• You may set Meta theme color (often tints the device UI)
• You may set Page background color (the surface content sits on)

If you later enable 2.3 style variations (light/dark), do not assume the PWA meta color automatically tracks the OS. The PWA setup fields are explicit. Set them to something that does not clash with both variations, or accept a fixed chrome color.

A worked setup (email Monday, push Tuesday)

Monday — mail

1. Decide transport with the table above.
2. Email options: Default address staff@yourdomain.example, bounce bounces@yourdomain.example, sender name Harbor Staff.
3. If SMTP: provider host/port/auth. If Google OAuth: run the on-screen Developer Console steps; do not paste client secrets into a public thread.
4. Send a test (button or lost-password). Read headers. Fix SPF if Gmail fileted it.
5. Trigger a conversation mail to yourself as a second user. That is the watched-content pipe.
6. Only then enable email-link 2FA under Service providers.

Tuesday — PWA

1. Confirm HTTPS and Board URL.
2. Board short title if Board title is > 12 characters.
3. Export a maskable PNG pair, 192 and 512. Upload in PWA setup. Tick maskable if they are.
4. Pick PWA language. Set meta theme color and page background to the default style’s steel, not white-on-white.
5. Confirm gmp, mbstring, openssl. Tick Enable push notifications.
6. On a phone that is not your daily driver: install (iOS: Add to Home Screen). Allow notifications. Quote yourself from a desktop. Confirm a tray notification and a badge.
7. Write a three-line help page: Android/desktop “Allow,” iOS “Add to Home Screen, then Allow.” Link it from onboarding.

Do not embed a live Twitch player on / the same day you are measuring whether push badges. One variable at a time.

What members actually control

You cannot (and should not) force desktop push the way you force staff 2FA. Official 2FA mandate is a group permission. Push permission is a browser permission plus a PWA install on iOS.

What you can do:

• Make install possible (this article)
• Make alerts worth receiving (watch defaults, notices for the 72-hour thing, not a push blast)
• Not spam. Every watched-forum mail you enable is also a push if they installed. A busy quoting culture plus “email on every quote” plus push is how they disable everything

Default user notification preferences live in user options / group permissions depending on the item — official does not, on the PWA page, give you a “force push on for all Registered.” Do not look for that checkbox.

Troubleshooting that is usually not XenForo

Symptom	Look at first
No mail at all	Transport, host mail() disabled, SMTP auth, Board URL in links
Mail to Gmail is spam	SPF/DKIM/DMARC on the sending domain, From = Default address on that domain
Google SMTP rejected	Official reason Google OAuth exists
PWA setup shows failures	HTTPS, title length, icons, PHP modules — the page’s own tests
Android push works, iPhone does not	They did not Add to Home Screen, or iOS < 16.4
Prompt never appears	Browser already denied; site settings / cookies
Push on, no events	They have no alerts (preferences), or they are testing as a guest
Badge stuck	Pending alerts they have not marked read; not a separate badge API for you to reset in ACP

Missing gmp looks like “push checkbox does nothing.” Install the extension, restart php-fpm, reload PWA setup.

A reverse proxy that strips service-worker headers or caches service_worker.js like a static asset will produce “installed but dead” PWAs. Official PWA chapter does not name your CDN. If you added “cache everything,” exclude the worker and the ACP. The speed article already warned about CDNs that “help.”

Checklist

• Transport chosen: PHP mail, SMTP, or Google OAuth — not all three “just in case”
• Default email address is valid and on a domain you authorize to send
• Bounced email address is set (or you knowingly accept bounces on default)
• Default email sender name is readable; not a 60-character Board title unless you want that
• A test message was received, not just “sent”
• SPF (and DKIM if you can) match the machine that sends
• HTTPS is real; Board URL is https://
• Board title ≤ 12 characters or Board short title is filled
• Icons 192 and 512, square, PNG, maskable if you ticked the box
• PHP gmp, mbstring, openssl on the live interpreter
• Enable push notifications ticked; PWA setup tests are green
• iOS instructions say Add to Home Screen
• PWA language is an installed language you meant
• Meta theme color and page background set; default style is the one you think it is
• Email-link 2FA is off until mail delivers
• Staff 2FA still uses TOTP first (security)

What this is not

It is not an engagement strategy. Push will not save a dead first 30 days.

It is not a native iOS/Android app. Official is explicit: there is no separate store app.

It is not a newsletter platform. Contact users plus a preference field is the official-shaped digest. A third-party ESP is optional and unnamed here.

It is not Discord. A webhook into a channel is the Discord article. That is not push.

Takeaways

• Email options pick a transport (PHP mail preferred, SMTP slower, Google OAuth when Google demands it) and three envelope fields: default address, bounce address, sender name.
• Prove mail with a lost-password or ACP test before you depend on it for 2FA or a move announcement.
• PWA setup needs HTTPS, a ≤12 character title, and 192/512 icons. Push also needs gmp + mbstring + openssl and the enable checkbox.
• Push is the alerts system on a device, not a second notification product.
• iOS 16.4+ push requires Add to Home Screen. Document it.
• One PWA language. Colors follow the default style plus two explicit fields.

Get the From line right on Monday. Get the home-screen icon right on Tuesday. The bell can travel after that.