Ultimate Member — MailPoet is a paid extension that connects your Ultimate Member member database directly to MailPoet. Every time a member registers, updates their profile, changes roles, or is approved, their MailPoet subscription is kept automatically in sync.
What it solves
Without this plugin
With this plugin
New members don’t appear in MailPoet
Members are added to MailPoet at registration or approval
No segmentation by membership tier
Role → list mapping syncs tier changes automatically
MailPoet can’t see profile fields (country, city, job title)
Custom field mapping pushes profile data into MailPoet subscriber fields
Existing members missing from MailPoet
Bulk import adds every approved member in one click
Members can’t manage their subscriptions on-site
Account tab lets members toggle lists without leaving your site
No visibility when a sync fails
Audit log shows every API error with timestamps
Unsubscribes via email unknown to UM
Daily back-sync writes unsubscribe status to user meta
2. Requirements & Installation
Installation steps
Upload um-mailpoet.zip via Plugins → Add New → Upload Plugin.
Click Activate Plugin.
On activation, default settings are written automatically — no manual database setup needed.
Navigate to Ultimate Member → Settings → Extensions → MailPoet to configure.
📸 SCREENSHOTUM → Settings → Extensions page with the “MailPoet” sub-tab visible and active. Show the full settings page header and tab navigation.
Dependency check
If either Ultimate Member or MailPoet is missing or inactive, a red admin notice appears at the top of every admin page. The plugin does nothing until both dependencies are active.
📸 SCREENSHOTRed admin notice: “Ultimate Member — MailPoet requires the MailPoet plugin to be installed and active. [Get MailPoet]” — shown at top of WP Dashboard.
3. How List Assignment Works (Priority Order)
When a user registers or is approved, the plugin resolves which lists they should join by combining up to five sources. Sources in the “Always applied” tier bypass the opt-in checkbox gate.
Priority
Source
Opt-in gate?
Configured in
1
Role-based lists
Bypassed — always applied
Settings → Role → list mapping
2
Per-form lists
Bypassed — always applied
Form edit screen → MailPoet Lists metabox
3
Conditional rules
Bypassed — always applied
Settings → Conditional list rules
4
Global default lists
Gated — skipped if checkbox unchecked
Settings → Default lists for new members
5
Form checkbox fields
Gated — user’s explicit choice
UM form builder → MailPoet field type
✓ TipAll sources are de-duplicated. A user is never added to the same list twice even if multiple sources resolve to the same list ID.
4. Registration Opt-In Checkbox
What it does
Adds a MailPoet field type to the Ultimate Member form builder. When placed on a registration form, it renders a checkbox that lets the user opt in or out of a specific MailPoet list at the moment of registration.
Use cases
Newsletter opt-in during registration — “Subscribe to our monthly newsletter” checkbox. Users who leave it unchecked are not added to the list.
Multiple list opt-ins — add several MailPoet fields to one form, one per list (e.g. “General Newsletter” + “Product Updates”).
Auto-subscribe without a visible checkbox — enabling the Auto-subscribe option adds the user to the list silently, without showing a checkbox.
How to configure
Open the UM form builder for any registration form (Dashboard → Ultimate Member → Forms → edit).
Drag the MailPoet field from the field picker into the form layout.
In the field settings panel, configure: Title (required), Checkbox label, MailPoet list, and optionally enable Auto-subscribe without showing checkbox.
Save the form.
📸 SCREENSHOTUM form builder with a MailPoet field in the layout. Field settings panel open showing: “MailPoet list” dropdown (populated), “Checkbox label” text input, “Auto-subscribe without showing checkbox” toggle. Note visible that the field is only available on Registration-mode forms.
📸 SCREENSHOTRegistration form on the frontend showing the newsletter opt-in checkbox: “Subscribe to our newsletter”. Show in its default (unchecked) state with UM form styling.
ℹ NoteThe MailPoet field type is only available in Registration forms. It does not appear in the field picker when editing Profile or Login forms.
⚠ ImportantIf a form has at least one visible (non-auto) MailPoet checkbox and the user leaves all of them unchecked, global default lists are also skipped — the opt-in gate applies to defaults too.
5. Automatic Subscription on Approval
What it does
Handles the full user lifecycle automatically, with no admin action required.
Event
Action
User registers (any method)
Added to configured lists immediately
Admin creates a user manually in WP dashboard
Added to configured lists
User’s account is approved by admin
Added to configured lists
User’s account is deactivated / rejected
Optionally unsubscribed (configurable)
User’s account is deleted
Optionally unsubscribed or deleted from MailPoet
Use cases
Admin approval workflow — members are held as “pending” in UM. When you click Approve, they are immediately added to MailPoet.
Deactivated churned members — automatically remove deactivated members from your active lists.
GDPR cleanup on deletion — when a member requests deletion, their MailPoet record is deleted or unsubscribed automatically.
How to configure
Go to Ultimate Member → Settings → Extensions → MailPoet.
When account is deactivated: Do nothing | Unsubscribe from all lists.
When account is deleted: Do nothing | Unsubscribe | Delete contact from MailPoet.
📸 SCREENSHOTUM → Settings → Extensions → MailPoet — top section showing “When account is deactivated” and “When account is deleted” select dropdowns with their current values visible.
6. Profile Field → MailPoet Custom Field Mapping
What it does
Maps any Ultimate Member profile field (country, phone, city, job title, birthday, or any custom field) to a MailPoet subscriber custom field. Mapped values are sent to MailPoet at registration and updated every time the member saves their profile.
Prerequisites
You must first create custom subscriber fields in MailPoet before mapping:
In MailPoet, go to Subscribers → Manage fields.
Add fields like “Country”, “Phone”, “City”, etc.
MailPoet stores these as cf_1, cf_2, etc. internally.
How to configure
Go to Ultimate Member → Settings → Extensions → MailPoet.
Scroll to Profile field mapping.
Click + Add mapping.
Left dropdown: select a UM profile field (e.g. Country (country)).
Right dropdown: select the MailPoet field (e.g. Country (cf_3)).
Repeat for each field. Save settings.
📸 SCREENSHOTThe “Profile field mapping” table in UM settings. Show 3 configured rows: “Country (country) → Country (cf_3)”, “Phone (phone_number) → Phone (cf_4)”, “Job Title (job_title) → Profession (cf_5)”. The “+ Add mapping” button visible at bottom.
📸 SCREENSHOTMailPoet → Subscribers — a subscriber record expanded, showing custom fields populated: Country: Thailand, City: Bangkok. This illustrates the end result of the field mapping.
⚠ ImportantMailPoet prevents updating email, first_name, and last_name for subscribers linked to a WordPress user account. This is a MailPoet API restriction. Only custom fields (cf_X) update reliably via API for WP-linked subscribers.
7. Role → List Mapping
What it does
Automatically subscribes members to specific MailPoet lists based on their Ultimate Member role, and keeps those subscriptions in sync whenever a role changes.
Use cases
Tiered memberships — “Free” role → “Free Newsletter”. “Premium” role → “Premium Content”. “VIP” role → “VIP Announcements”.
Onboarding sequences — when a member upgrades to Premium, add them to a “Premium Onboarding” list to trigger a welcome automation.
Churn prevention — when a member downgrades, add them to a win-back campaign list.
Staff communications — “Staff” role members are automatically kept on internal staff announcement lists.
How to configure
Go to Ultimate Member → Settings → Extensions → MailPoet.
Scroll to Role → list mapping.
A table shows your UM roles as rows and MailPoet lists as columns. Check the intersection boxes.
Configure On role change: Keep subscriptions from previous role — or — Unsubscribe from previous role lists.
Save settings.
📸 SCREENSHOTThe role → list mapping matrix table. Rows: “Free Member”, “Premium”, “VIP”, “Staff”. Columns: “Newsletter”, “Premium Updates”, “VIP Lounge”, “Staff Alerts”. Some checkboxes ticked realistically. “On role change” select visible below the table.
Role change triggers
Role sync fires on five separate events to ensure no change is missed:
set_user_role — WordPress full role replacement
add_user_role — WordPress role added to multi-role user
remove_user_role — WordPress role removed
um_after_user_role_is_updated — UM role change
um_after_member_role_upgrade — UM membership upgrade
ℹ NoteRole-based lists are always applied — they bypass the opt-in checkbox gate. A user assigned to the “Premium” role is added to Premium lists regardless of any checkbox.
8. Per-Form List Assignment
What it does
Lets you assign specific MailPoet lists to individual UM registration forms. Members who register through that form are automatically added to those lists — no visible checkbox needed.
Use cases
Multiple registration forms — “Customer” form → “Customers” list. “Partner” form → “Partners” list. “Job Applicant” form → “Applicants” list.
Event registration — a dedicated form adds registrants to an event list without requiring a checkbox.
Landing page funnels — each campaign page has its own UM form, each mapped to its own MailPoet segment.
How to configure
Go to Ultimate Member → Forms in the WP admin.
Open (or create) a registration form.
In the right sidebar, find the MailPoet Lists metabox.
Check the lists you want members who use this form to be subscribed to.
Update/Publish the form.
📸 SCREENSHOTUM form edit screen (Classic Editor). Show the “MailPoet Lists” metabox in the right sidebar with 3 list checkboxes, two ticked. The form title “Partner Registration” visible at top.
ℹ NotePer-form lists are always applied — they bypass the opt-in checkbox gate. They can coexist with opt-in checkbox fields on the same form.
9. Bulk Import Existing Users
What it does
Imports all existing approved Ultimate Member members into MailPoet in a single operation. Applies current configuration — default lists, role-based lists, conditional rules, and field mapping — to every member in batches of 50.
Use cases
New plugin installation — you have 1,200 existing members who were never in MailPoet. One click imports all of them with the correct lists based on their current roles.
Configuration change — you added a new “Country” field mapping. Bulk sync pushes that data to MailPoet for all existing members.
After list restructure — you updated role mapping. Bulk sync re-applies the new configuration to everyone.
How to use
Go to Ultimate Member → Settings → Extensions → MailPoet.
Scroll to Bulk sync existing users at the bottom.
Note the count of approved members found.
Click “Sync all users to MailPoet”.
Monitor the progress bar. Errors are listed in red below.
“Sync complete.” appears in green on completion.
📸 SCREENSHOTBulk Sync panel mid-operation: progress bar at ~60% showing “300 / 500”, 2 error items in red below the bar, button showing “Syncing…” (disabled).
📸 SCREENSHOTBulk Sync panel after completion: progress bar at 100%, “600 / 600”, “Sync complete.” in green.
⚠ ImportantKeep the browser tab open until the progress bar reaches 100%. If you close the tab, the sync stops. It is safe to restart — existing subscribers are updated gracefully, not duplicated.
10. Frontend Subscription Manager
What it does
Adds a “Subscriptions” tab to the Ultimate Member account page. Logged-in members can see which public newsletter lists they are subscribed to and toggle their preferences — all without leaving your site.
Use cases
GDPR compliance — gives members a clear place to manage email preferences on your own site, satisfying the “easy withdrawal of consent” requirement.
Preference centre — members can opt in to additional lists they missed at registration.
Reducing global unsubscribes — members can unsubscribe from individual lists while staying on others, instead of clicking the global “Unsubscribe” link in emails.
Admin configuration
Go to Ultimate Member → Settings → Extensions → MailPoet.
Find “Lists visible in subscription manager”.
Check only the lists you want members to see. Leave internal lists unchecked.
Save settings.
📸 SCREENSHOT“Lists visible in subscription manager” multi-checkbox in UM settings. “Newsletter” and “Product Updates” checked. “VIP Internal” and “Admin Notifications” unchecked — showing the admin controls which lists are public.
Member experience
The tab appears as “Subscriptions” in the account page tab bar. Inside members see:
Whitelisted public lists with checkboxes showing current subscription state
“Save preferences” button
Inline confirmation: “Preferences saved.” or an error message
📸 SCREENSHOTUM account page frontend with the “Subscriptions” tab active. Show the tab bar (General, Password, Subscriptions), the active tab highlighted. Inside: two lists with checkboxes, one checked and one unchecked, “Save preferences” button at the bottom.
📸 SCREENSHOTSame view immediately after clicking Save — “Preferences saved.” confirmation in green next to the button.
✓ TipSecurity: Only whitelisted lists are shown. Internal list names and IDs are never exposed to the frontend. The AJAX handler validates all submitted list IDs server-side against the same whitelist.
11. Sync Audit Log & Admin Tools
8a — Sync error log page
Found at Ultimate Member → MailPoet Log. Shows the last 50 MailPoet API errors. Errors are stored for 7 days.
Column
Description
Time
When the error occurred
Method
Which API call failed (e.g. addSubscriber, subscribeToList)
Context
Human-readable description of what was being attempted
Error detail
The exact error message returned by MailPoet
📸 SCREENSHOTMailPoet Log admin page: title “MailPoet Sync Log”, description text, then the table with 3–4 error rows. One row showing a realistic error: “addSubscriber failed | subscriber already exists”. “Clear log” button above the table.
📸 SCREENSHOTMailPoet Log page with no errors: “No errors recorded. All good!” message — the healthy state.
8b — MailPoet column on the Users screen
A MailPoet column appears on WP Admin → Users.
✓ Synced (green) — the user was successfully synced. Hovering shows their MailPoet subscriber ID.
— (grey) — not yet synced to MailPoet.
📸 SCREENSHOTWP Admin → Users screen with the “MailPoet” column on the right. Some rows show “✓ Synced” in green, one or two show “—” in grey.
8c — Per-user resync button
When editing any user (WP Admin → Users → edit), a MailPoet section at the bottom of the profile page shows:
Current sync status and subscriber ID
Unsubscribed-in-MailPoet warning with timestamp (if detected by back-sync)
“Resync this user” button — immediately pushes the user to MailPoet using all current configuration
📸 SCREENSHOTWP Admin → Users → edit user. MailPoet section showing: “Subscriber status: Synced (Subscriber ID: 4512)” in green, and if applicable the red notice “Unsubscribed in MailPoet (detected 2026-04-15 09:30)”. The “Resync this user” button.
12. Unsubscribe Back-Sync
What it does
Runs once daily via WP-Cron. For every member who has a stored subscriber ID, it checks their current status in MailPoet and writes the result back to WordPress user meta as _um_mailpoet_unsubscribed (a Unix timestamp).
What it writes
Condition in MailPoet
Action on user meta
Status is “unsubscribed”
Sets _um_mailpoet_unsubscribed to current timestamp
Status is “subscribed” again
Deletes _um_mailpoet_unsubscribed (clears the flag)
Subscriber no longer exists in MailPoet
Sets _um_mailpoet_unsubscribed to current timestamp
Use cases
Content restriction — restrict posts to members who are currently subscribed. Read _um_mailpoet_unsubscribed in custom UM access rules.
Admin awareness — the per-user resync button shows the detected unsubscribe timestamp to admins.
Re-engagement triggers — custom code can query users with this meta key set to identify and target lapsed subscribers.
No configuration needed. The cron is scheduled on plugin activation and cancelled on uninstall.
📸 SCREENSHOTWP Admin → Users → edit user. MailPoet section showing the red notice: “Unsubscribed in MailPoet (detected 2026-04-15 09:30)” — the back-sync result visible to admins.
13. Conditional List Rules
What it does
A rule builder where each rule says: “If a member’s profile field [X] [operator] [value], add them to MailPoet list [Y].” Rules are evaluated at registration and on every profile save. They are additive only — matching a rule adds the member to a list, but a rule never removes them.
Use cases
Geographic segmentation — “If country equals Thailand → add to SEA Members list.”
Completeness gate — “If bio not_equals (empty) → add to Verified Profiles list.”
Language targeting — “If language equals fr → add to French Content list.”
Available operators
Operator
Meaning
Example use
equals
Exact match (case-sensitive)
country equals Thailand
not_equals
Value is not equal; catches empty fields when value is “”
newsletter_opt_out not_equals 1
contains
Value contains the substring
job_title contains Manager
not_contains
Value does not contain the substring
interests not_contains unsubscribed
How to configure
Go to Ultimate Member → Settings → Extensions → MailPoet.
Scroll to Conditional list rules.
Click “+ Add rule”.
Select UM Profile Field, Operator, enter Value, select MailPoet List.
Add as many rules as needed. Each rule is independent. Save settings.
📸 SCREENSHOTThe “Conditional list rules” table in UM settings showing 3 configured rule rows:Row 1: Country (country) | equals | Thailand | SEA MembersRow 2: job_title | contains | Manager | Managers NewsletterRow 3: newsletter_optin | not_equals | (empty) | Marketing CampaignsThe “+ Add rule” button visible at the bottom.
ℹ NoteRules are additive — they never remove subscriptions. If a member matched a rule, then later changes the field value, they keep the list they were added to and may gain additional ones.
⚠ ImportantOperators are case-sensitive. “Thailand” does not match “thailand”. For free-text fields, prefer contains over equals.
14. Global Settings Reference
All settings are at Ultimate Member → Settings → Extensions → MailPoet.
Setting
Type
Default
Description
When account is deactivated
Select
Do nothing
Action when a member is set to non-approved status. Options: Do nothing, Unsubscribe.
When account is deleted
Select
Unsubscribe
Action on permanent user deletion. Options: Do nothing, Unsubscribe, Delete contact.
Require double opt-in email
Checkbox
Off
When on, new subscribers receive a MailPoet confirmation email. They appear as “Unconfirmed” until they click.
Default lists for new members
Multi-checkbox
None
Lists every new approved member is added to, unless a visible opt-in checkbox is present and left unchecked.
Lists visible in subscription manager
Multi-checkbox
None
Only these lists appear in the member account tab. Internal lists not checked here stay invisible.
Role → list mapping
Matrix table
Empty
Roles × lists matrix. Check intersections to map roles to lists.
On role change
Select
Keep previous
Whether to remove old role lists when a member’s role changes.
Profile field mapping
Repeater
Empty
UM meta key → MailPoet cf_X field mapping rows.
Conditional list rules
Repeater
Empty
Field / operator / value / list rule rows.
Bulk sync existing users
Tool
—
One-click import of all approved users into MailPoet. Not a persistent setting.
📸 SCREENSHOTFull UM → Settings → Extensions → MailPoet page — composite screenshot or two separate screenshots showing the complete settings page from top (lifecycle settings) to bottom (bulk sync tool). This is the master reference screenshot.
15. User Meta Reference
The plugin stores two private user meta keys on each WordPress user:
Meta key
Type
Description
_um_mailpoet_subscriber_id
String
The MailPoet subscriber ID. Set when the user is first successfully synced. Displayed in the Users column and profile page.
_um_mailpoet_unsubscribed
Integer (timestamp)
Unix timestamp of when the daily back-sync detected an unsubscribe. Deleted when the user re-subscribes. Absent if currently subscribed.
Using in custom code
These keys can be used in custom code or UM content restriction rules. Example:
// Restrict content to currently-subscribed members$user_id = get_current_user_id();if ( get_user_meta( $user_id, ‘_um_mailpoet_unsubscribed’, true ) ) { // User has unsubscribed — redirect or show warning}
16. Frequently Asked Questions
Will existing members be automatically added to MailPoet when I install the plugin?
No. The plugin only syncs members going forward. Use the Bulk Import tool (Feature 6) to bring existing members into MailPoet.
What happens if a member is already in MailPoet with the same email?
The plugin detects the duplicate and updates the existing subscriber rather than creating a second record. Their list subscriptions are merged — they gain new lists without losing any existing ones.
Does double opt-in affect role-based or per-form list assignments?
Yes. When double opt-in is enabled, even always-applied lists require the member to confirm via email before they are fully subscribed. The subscriber appears as “Unconfirmed” in MailPoet until they click.
Can I use this plugin with MailPoet’s free version?
Yes. All features use MailPoet’s public PHP API (v1), which is available in both free and premium versions.
What if MailPoet is temporarily unavailable?
All sync operations are wrapped in exception handling. If MailPoet is unreachable during registration, the user is registered normally in WordPress — the sync fails silently and the error is logged. Resync individual users with the resync button, or run bulk sync again when MailPoet is back.
Can members subscribe to lists they weren’t originally added to?
Only if those lists are included in the “Lists visible in subscription manager” whitelist. Any whitelisted list appears in the Subscriptions tab and members can opt in themselves.
Does the plugin support MailPoet automations?
The plugin manages list membership. MailPoet’s own automation workflows are triggered by list membership — so when this plugin adds a subscriber to a list, any MailPoet automations configured for that list will fire automatically.
What happens if I uninstall the plugin?
All plugin-specific settings are removed from the database. The MailPoet sync cron job is cancelled. MailPoet subscriber data is not deleted — subscribers remain in MailPoet untouched.
17. Troubleshooting
Members are not appearing in MailPoet
Check Ultimate Member → MailPoet Log for API errors during the registration.
Confirm at least one list is configured: default lists, role-based lists, per-form lists, or a conditional rule.
If the form has a visible MailPoet opt-in checkbox and the member left it unchecked, they will not be added to default lists. This is correct behaviour.
Use the Resync this user button on the member’s WP profile page to retry.
The Subscriptions account tab is not visible
Ensure at least one list is checked under “Lists visible in subscription manager” in settings.
Confirm the member is logged in. The tab is only shown to authenticated users.
Confirm MailPoet is active. If MailPoet deactivates, the tab content cannot load.
Role changes are not triggering list updates
Confirm rows are checked in the Role → list mapping table for the relevant role.
The role sync only adds to lists — it does not create new MailPoet subscribers. If the member was never synced to MailPoet, use the resync button first.
Check the MailPoet Log for any subscribeToList errors.
Conditional rules are not working
Verify the UM Profile Field dropdown value matches the exact user meta key used by UM.
Remember operators are case-sensitive. “thailand” will not match “Thailand”.
Rules are evaluated at registration and on profile save — not retroactively. To apply rules to existing members, run the Bulk Import.
Bulk sync stops before completing
The sync runs in the browser. If the tab was closed or the session timed out, restart the sync. It is safe to restart — existing subscribers are updated gracefully, not duplicated.
MailPoet lists don’t appear in the settings dropdowns
MailPoet list data is cached for 10 minutes. After creating a new list in MailPoet, wait up to 10 minutes and refresh the settings page. Saving any MailPoet settings also clears the cache immediately.
