MailPoet

Key Features

MailPoet integration for Gravity Forms

• Add Gravity Forms submitters to MailPoet lists.
• Update existing MailPoet subscribers when the submitted email address already exists.
• Uses MailPoet’s public in-process MP v1 API via \MailPoet\API\API::MP( 'v1' ).

Per-form feed configuration

• Configure MailPoet feeds per Gravity Form.
• Select the MailPoet list each feed should subscribe users to.
• Map Gravity Forms fields to MailPoet subscriber fields.
• Require a valid mapped email address before processing.

Subscriber options

• Send MailPoet confirmation emails when applicable.
• Schedule MailPoet welcome emails.
• Optionally skip new subscriber notification emails.
• Optionally update first and last name for existing subscribers.
• Add MailPoet tags using static text or Gravity Forms merge tags.

Conditional and payment-aware processing

• Use Gravity Forms conditional logic to control when a feed runs.
• Supports delayed payment processing, so subscribers can be added only after payment is received.

Reliability and observability

• Processes feeds asynchronously.
• Adds entry notes when subscribers are added, updated, skipped, or fail to sync.
• Supports Gravity Forms logging for troubleshooting MailPoet API and feed processing issues.

Requirements

Platform requirements

• WordPress 6.5+
• PHP 7.4+
• Gravity Forms 2.9.24+

External requirements

• MailPoet plugin installed and activated on the same WordPress site.
• MailPoet setup completed, including initial list setup.
• At least one MailPoet list available for feed configuration.

Installation

1. Upload the plugin folder to /wp-content/plugins/gravityformsmailpoet/, or install it using Plugins → Add New → Upload Plugin.
2. Activate Gravity Forms MailPoet Add-On from the WordPress Plugins screen.
3. Confirm that Gravity Forms and MailPoet are installed and active.
4. Complete the MailPoet setup wizard if it has not already been completed.

Setup: Connecting MailPoet and Configuring Feeds

Confirm MailPoet connection

1. Go to Forms → Settings → MailPoet.
2. Review the connection status.
3. If MailPoet is not connected:
   • Confirm the MailPoet plugin is active.
   • Open MailPoet and complete its setup.
   • Create or confirm at least one MailPoet list exists.

No external API credentials are required. The add-on communicates with the locally installed MailPoet plugin through MailPoet’s public PHP API.

Create a MailPoet feed

1. Open the target form in Forms → Edit.
2. Go to Settings → MailPoet.
3. Click Add New.
4. Configure the feed:
   • Name: Enter a descriptive feed name.
   • MailPoet List: Select the MailPoet list subscribers should be added to.
   • Map Fields: Map Gravity Forms fields to MailPoet subscriber fields.
   • Options: Choose confirmation, welcome email, notification, and existing subscriber behavior.
   • Tags: Optionally add comma-separated MailPoet tags.
   • Conditional Logic: Optionally process the feed only when entry conditions are met.
5. Save the feed.

Using the Add-On

Subscribing contacts from form submissions

1. Submit an entry through a Gravity Form with an active MailPoet feed.
2. The add-on validates the mapped email address.
3. The add-on checks whether the subscriber already exists in MailPoet.
4. The subscriber is added or updated and subscribed to the configured MailPoet list.
5. A Gravity Forms entry note is added with the result.

Existing subscribers

When the submitted email address already exists in MailPoet:

• The subscriber can be updated with mapped field values.
• First and last name are preserved by default unless the feed option to update names is enabled.
• Existing tags are preserved and merged with tags configured in the feed.
• Unsubscribed contacts may be resubscribed unless customized by developer filters.

Payment forms

For forms using payment add-ons, the feed can be configured to subscribe the contact only after payment is received.

Field Mapping

Required mapping

• Email Address is required.
• The mapped email field must contain a valid email address.

Optional mappings

Depending on the subscriber fields available in MailPoet, additional fields may be mapped, such as:

• First name
• Last name
• Custom MailPoet subscriber fields

Tags

Use the Tags setting to apply one or more MailPoet tags to synced subscribers.

Example:

new lead, Gravity Forms, newsletter signup

Gravity Forms merge tags may also be used where supported by the setting.

Logging & Troubleshooting

Quick checks

If subscribers are not being added to MailPoet:

• Confirm WordPress, PHP, and Gravity Forms meet the minimum requirements.
• Confirm MailPoet is installed and active.
• Confirm MailPoet setup is complete.
• Confirm at least one MailPoet list exists.
• Confirm the form has an active MailPoet feed.
• Confirm the feed has a MailPoet list selected.
• Confirm the email field is mapped and contains a valid email address.
• Confirm feed conditional logic is not preventing processing.

Check entry notes

Open the Gravity Forms entry and review notes for messages such as:

• Subscriber added.
• Subscriber updated.
• Invalid email address.
• MailPoet list was not configured.
• MailPoet API error.
• Subscriber skipped.

Enable Gravity Forms logging

1. Go to Forms → Settings → Logging.
2. Enable logging for the MailPoet add-on, if available.
3. Reproduce the issue.
4. Review logs for API initialization, subscriber lookup, sync, and error details.

Common causes of failures

• MailPoet plugin is inactive.
• MailPoet setup wizard has not been completed.
• No MailPoet list is configured on the feed.
• The mapped email address is invalid or empty.
• Required MailPoet subscriber fields are not mapped.
• MailPoet rejects the subscriber update.
• Conditional logic prevents the feed from running.
• Payment has not yet been received for delayed payment feeds.

Developer Notes

Main classes

• Main add-on class: Gravity_Forms\Gravity_Forms_MailPoet\GF_MailPoet
• API wrapper class: Gravity_Forms\Gravity_Forms_MailPoet\GF_MailPoet_API

Integration approach

The add-on uses MailPoet’s public MP v1 PHP API through the local MailPoet plugin. It should not call MailPoet admin JSON/REST APIs or remote HTTP endpoints for subscriber integration.

Useful filters

Developers can customize behavior with filters including:

• gform_mailpoet_supported_field_types_email_map
• gform_mailpoet_override_empty_fields
• gform_mailpoet_tags
• gform_mailpoet_options
• gform_mailpoet_subscriber
• gform_mailpoet_allow_resubscription

Development & Verification

Common verification commands:

php -l mailpoet.php

php -l class-gf-mailpoet.php

php -l includes/class-gf-mailpoet-api.php

composer install

composer install-tests

composer phpunit

composer phpcs

composer phpstan

composer semgrep

MailPoet is required for configuring and processing feeds on a WordPress site. PHPUnit smoke tests do not require MailPoet to be installed.

Uninstallation

1. Deactivate the plugin from the WordPress Plugins screen.
2. Delete the plugin if it is no longer needed.
3. Remove any remaining MailPoet feeds or settings if retained by the site.
4. Review MailPoet lists, subscribers, and tags if cleanup is needed.

Support

This is a Gravity Labs add-on and is provided as-is.

Before requesting support or reporting an issue, collect:

• WordPress version
• PHP version
• Gravity Forms version
• MailPoet version
• Gravity Forms MailPoet Add-On version
• Relevant Gravity Forms logs
• Form and feed configuration details
• Example entry notes or error messages

Redact private data, email addresses, credentials, and secrets before sharing logs.