MailPoet Integration

MailPoet is a self-hosted WordPress email marketing plugin. WP Smart Consent integrates with it via MailPoet’s native PHP API — no external API key or internet connection required. The integration runs entirely on your server.

Enabling the Integration#

In the WP Smart Consent dashboard, go to CRMs & ESPs, find the MailPoet card, open the Connection tab, and toggle it on. MailPoet must be installed and active on the same site.

Custom Fields#

MailPoet custom fields are referenced by a cf_{id} key format, where {id} is the numeric ID of the custom field. To find a field’s ID, go to MailPoet → Subscribers → Custom fields and check the ID shown for each field.

In the Custom fields tab, add a row, select the WPSC source field on the left, and enter the MailPoet custom field key on the right in cf_{id} format — for example cf_3 for a custom field with ID 3. These are merged directly into the subscriber data object passed to the API.

Field Mapping#

The Field mapping tab maps WPSC fields to MailPoet subscriber field keys. MailPoet’s standard fields are email, first_name, and last_name — these are always sent automatically and do not need to be mapped. For any other field, use the destination key cf_{id} matching the custom field ID in MailPoet. Any destination key that does not match a standard field is stored as a custom field value.

How It Works#

WP Smart Consent calls \MailPoet\API\API::MP('v1')->addSubscriber() with the subscriber data, selected list IDs, and options. If the subscriber already exists — detected by catching MailPoet’s SUBSCRIBER_EXISTS exception (code 12) — WP Smart Consent falls back to updateSubscriber() to update their fields, then subscribeToLists() to ensure list membership is current.

Tags are applied after the upsert using tagSubscriber() rather than being passed in the initial subscriber data. This is because MailPoet’s resolveTagNames() throws an exception if a tag does not exist yet, whereas tagSubscriber() creates missing tags automatically.

When a contact is forwarded via Send on unchecked, the subscriber is created with status: unsubscribed so the record exists for logging purposes but MailPoet suppresses all emails to them.

Lists Tab#

The Lists tab is where you select which MailPoet lists opted-in contacts are subscribed to. Lists are fetched from your MailPoet installation after enabling the integration.

Options#

The Options tab has three settings.

Update existing contacts — controls whether an existing MailPoet subscriber matched by email has their fields updated on each opt-in.

Send on unchecked — when enabled, contacts are forwarded to MailPoet even when the opt-in checkbox was not ticked, with unsubscribed status so they receive no emails.

Tags — a comma-separated list of tag names to apply to every subscriber. Tags are applied via tagSubscriber() after the upsert and are created automatically in MailPoet if they do not exist yet.

Troubleshooting#

Contact not appearing in MailPoet — confirm MailPoet is installed and active. WP Smart Consent checks for the \MailPoet\API\API class at opt-in time and skips the call silently if it is not available.

Custom field values not saving — confirm the destination key is in cf_{id} format and the numeric ID matches an existing custom field in MailPoet → Subscribers → Custom fields. Keys that do not match a standard or custom field are silently ignored.

Tags not being created — tags are applied using tagSubscriber() which creates missing tags automatically. If a tag is still not appearing, check the WPSC Logs tab to confirm the opt-in event fired and review the WordPress error log for any MailPoet API exceptions.

Subscriber not re-subscribed to list — if a subscriber previously unsubscribed from a list, subscribeToLists() is still called on the existing subscriber path. Whether MailPoet re-subscribes them depends on your MailPoet subscription settings and any confirmation email requirements.