Group Membership API

LetterPress groups are static audience segments. Campaigns can target one group instead of the whole list, and only subscribed, non-blocklisted members receive the email.

The plugin exposes six functions for working with membership from your own code. They handle email lookup, reuse existing subscriber rows, create missing subscribers, and resolve WordPress users by role, so you do not need to write to LetterPress tables directly.

When to call​

Call these functions after LetterPress has loaded, for example on plugins_loaded with priority 20 or later, or later in a request such as a form handler or a scheduled job.

add_action( 'plugins_loaded', function () {
	$result = lp_add_subscriber_to_group( '[email protected]', 12 );
}, 20 );

Every function returns an array on success, a WP_Error on failure, or null when LetterPress is unavailable. Check for null if your code may run on a site where the plugin is inactive.

Add one subscriber​

$result = lp_add_subscriber_to_group(
	'[email protected]',
	12,
	[
		'name'   => 'Jane Doe',
		'source' => 'default',
		'status' => 'subscribed',
		'create' => true,
	]
);

An existing subscriber is reused as is. The function does not change their name, source, or status. That keeps the call safe when the contact already exists.

A newly created address is rejected when it is on the blocklist. An existing subscriber can still be added to the group, but campaigns only mail members whose status is subscribed and who are not blocklisted.

A successful call returns:

[
	'group_id'      => 12,
	'subscriber_id' => 94,
	'email'         => '[email protected]',
	'created'       => false,
	'added'         => true,
]

created tells you whether a new subscriber row was written. added tells you whether the group membership is new. Adding the same member twice is safe and returns added as false.

Common errors:

Remove one subscriber​

$result = lp_remove_subscriber_from_group( '[email protected]', 12 );

The subscriber must already exist. Removing a group membership does not delete the subscriber or change their status. A successful call returns the group ID, subscriber ID, email, and a removed boolean.

Add or remove many subscribers​

$result = lp_add_subscribers_to_group(
	[ '[email protected]', '[email protected]' ],
	12,
	[ 'source' => 'import' ]
);

$result = lp_remove_subscribers_from_group(
	[ '[email protected]', '[email protected]' ],
	12
);

The bulk add passes the same arguments to the single add call for each address. Duplicate and empty addresses in the input are ignored. The result reports each outcome separately:

[
	'group_id'       => 12,
	'added'          => 2,
	'created'        => 1,
	'skipped'        => 0,
	'subscriber_ids' => [ 94, 95 ],
	'errors'         => [],
]

skipped counts addresses that returned an error. Each failure is also listed in errors with the email, error code, and message.

The bulk remove returns the number of memberships removed and the number of input addresses that did not resolve to a subscriber:

[
	'group_id' => 12,
	'removed'  => 2,
	'skipped'  => 0,
]

Fill a group from a WordPress role​

lp_add_users_by_role_to_group() accepts any registered role slug, including author, editor, subscriber, or a role added by another plugin such as customer.

$result = lp_add_users_by_role_to_group( 'customer', 12 );

By default, new subscriber rows use the wp_users source and the subscribed status. You can override both:

$result = lp_add_users_by_role_to_group(
	'customer',
	12,
	[
		'source' => 'wp_users',
		'status' => 'subscribed',
	]
);

Users are matched by email. Existing subscribers are reused, and missing rows are created with the user's display name and a link to their WordPress user ID.

[
	'group_id' => 12,
	'role'     => 'customer',
	'added'    => 3,
	'created'  => 1,
	'skipped'  => 0,
	'total'    => 3,
]

total is the number of users with that role, not the number of new memberships.

Sync a group from its stored role​

A group can store a WordPress role in its settings. The Groups screen exposes a Sync role action for that case. The same operation is available in PHP:

$result = lp_sync_group_role( 12 );

The function reads the group's stored role and calls lp_add_users_by_role_to_group() with the default source and status. If the group has no role assigned, it returns a WP_Error with the code lp_group_role_empty.

Role sync is additive. It never removes members who no longer have the role, so manual additions and earlier memberships remain in the group.

Choosing between the REST API and PHP​

Use the PHP functions when the code runs inside WordPress, for example a form handler, a WooCommerce hook, or your own plugin screen. They avoid an HTTP round trip and use the current request's database connection. To create the subscriber itself from PHP, see Add a Subscriber.

Use the REST API when the caller is outside WordPress, such as a landing page on another domain or a script. The add-subscriber endpoint accepts a group_id and performs the same membership step. See API Keys for authentication and request details.

Things to keep in mind​

• A group membership is not a subscription. Adding a pending or unsubscribed contact to a group does not make them mailable.
• Campaigns check both status and blocklist when the queue is built, and again before each individual send.
• New addresses are checked against the blocklist. Existing addresses are not unblocked by a group call.
• The group must already exist. Create and manage groups under Groups and Sources.
• Removing a member leaves the subscriber row and its history untouched.

Next steps​

• Segment contacts from the admin in Groups and Sources.
• Register a group for a campaign in Campaigns.
• Combine membership calls with a transactional welcome email using the Transactional Email API.