Add a Subscriber

lp_add_subscriber() adds an email address to your audience with one call. Use it from a custom plugin, a theme's functions file, a form handler, a checkout hook, or an import script. The subscriber passes through the same checks as public signups: blocklist, duplicate handling, and your double opt-in setting. The built-in subscribe forms call this same function, so custom code and the public form behave identically.

When to call​

Call the function after LetterPress has loaded, for example on plugins_loaded with priority 20 or later, or later in the request such as a form handler.

add_action( 'plugins_loaded', function () {
	lp_add_subscriber( [ 'email' => '[email protected]' ] );
}, 20 );

Parameters​

The function takes one array:

$result = lp_add_subscriber(
	[
		'email'             => '[email protected]',
		'name'              => 'Jane Doe',
		'source'            => 'default',
		'group_id'          => 12,
		'send_confirmation' => null,
	]
);

Return values​

Success returns an array, including when the address was already subscribed. Failure returns a WP_Error. Always check with is_wp_error():

$result = lp_add_subscriber( [ 'email' => '[email protected]' ] );

if ( is_wp_error( $result ) ) {
	// $result->get_error_code() and get_error_message() explain the failure.
	return;
}

if ( $result['created'] ) {
	// New row written. Check confirmation_email if it is present.
} else {
	// Already subscribed. The message says so, and only a passed group changed.
}

With double opt-in enabled, a successful call returns:

[
	'success' => true,
	'created' => true,
	'email'   => '[email protected]',
	'name'    => 'Jane Doe',
	'source'  => 'default',
	'status'  => 'pending',
	'message' => 'Subscriber added.',
]

With double opt-in off, status is subscribed and no confirmation email is sent.

Error codes​

Controlling the confirmation email​

By default the function follows the double opt-in setting to decide whether a confirmation email goes out and whether the contact starts as pending. Pass send_confirmation to override that for a single call:

// Force a confirmation email even when double opt-in is off.
lp_add_subscriber( [ 'email' => '[email protected]', 'send_confirmation' => true ] );

// Add the contact without a confirmation email.
lp_add_subscriber( [ 'email' => '[email protected]', 'send_confirmation' => false ] );

With false the subscriber is stored as subscribed immediately. Use it when consent was already collected elsewhere, such as your own opt-in checkbox.

Examples​

Add a customer after checkout​

add_action( 'woocommerce_thankyou', function ( $order_id ) {
	$order = wc_get_order( $order_id );
	if ( ! $order || ! $order->get_billing_email() ) {
		return;
	}

	lp_add_subscriber(
		[
			'email'  => $order->get_billing_email(),
			'name'   => trim( $order->get_billing_first_name() . ' ' . $order->get_billing_last_name() ),
			'source' => 'checkout', // A source you created under Sources.
		]
	);
} );

PHP or REST API​

Use this function when your code runs inside WordPress. Use the REST endpoint when the caller is outside WordPress, such as a landing page on another domain or a script. See REST API Keys for the external route.

Next steps​

• Manage group membership by email with the Group Membership API.
• Segment contacts and create sources in Groups and Sources.