Référence des hooks et filtres de MailerPress

MailerPress déclenche des actions et des filtres WordPress (hooks) qui permettent aux développeurs de réagir aux événements des contacts, des campagnes et du suivi, d’ajuster des requêtes et des limites, et de connecter MailerPress à leur propre code. Cette page liste les principaux hooks publics de MailerPress et de MailerPress Pro, par thème, avec leurs arguments. Les hooks absents de cette page sont internes et peuvent changer sans préavis.

La plupart des hooks ci-dessous font partie de MailerPress (gratuit). Ceux des sections marquées « (MailerPress Pro) » ne sont déclenchés que si MailerPress Pro est actif.

Où ajouter votre code

Ajoutez vos extraits de code dans une extension personnalisée, une extension « must-use » (wp-content/mu-plugins) ou le fichier functions.php d’un thème enfant. De nombreux événements MailerPress s’exécutent en arrière-plan via Action Scheduler : chargez donc votre code à chaque requête, pas seulement dans l’administration. Quand un hook transmet plusieurs arguments, indiquez leur nombre dans add_action() ou add_filter().

Contacts et abonnements

Exemple : exécuter votre propre code quand un contact reçoit une étiquette précise.

add_action( 'mailerpress_contact_tag_added', function ( $contact_id, $tag_id ) {
	if ( 12 !== (int) $tag_id ) {
		return;
	}

	// Prévenir votre CRM, journaliser l’événement, etc.
	error_log( sprintf( 'MailerPress contact %d received tag %d', $contact_id, $tag_id ) );
}, 10, 2 );

Ajouter un contact depuis votre code

add_mailerpress_contact() crée un contact, ou le met à jour si l’adresse e-mail existe déjà. Transmettez au minimum email ; vous pouvez ajouter first_name, last_name, lists et tags (identifiants) et opt_in_source. Sans liste, le contact rejoint votre liste par défaut. Sans subscription_status, MailerPress applique votre réglage de confirmation de l’inscription : avec le double opt-in activé, le contact est en attente et reçoit l’e-mail de confirmation. La fonction renvoie un tableau avec success et contact_id, ou success et error.

function my_plugin_subscribe( $email, $first_name ) {
	if ( ! function_exists( 'add_mailerpress_contact' ) ) {
		return;
	}

	$result = add_mailerpress_contact( [
		'email'         => $email,
		'first_name'    => $first_name,
		'lists'         => [ 2 ],
		'tags'          => [ 5 ],
		'opt_in_source' => 'my_plugin',
	] );

	if ( empty( $result['success'] ) ) {
		error_log( 'MailerPress: ' . $result['error'] );
	}
}

Campagnes

Suivi et rebonds

Webhooks de rebond des services d’envoi (MailerPress Pro)

MailerPress Pro reçoit les notifications de rebond (e-mails non distribuables) de votre service d’envoi d’e-mails. Une notification non signée n’est appliquée que si le site a récemment envoyé un e-mail à cette adresse via le même service, et seulement dans une limite horaire. Ces filtres ajustent cette protection.

Éditeur d’e-mails et contenu

Pour ajouter vos propres étiquettes de personnalisation, utilisez mailerpress_register_merge_tag_group(), décrite dans Créer des merge tags personnalisés pour l’éditeur d’e-mails MailerPress.

Exemple : retirer les pages des contenus que vous pouvez insérer dans vos e-mails.

add_filter( 'mailerpress_post_types_public', function ( $post_types ) {
	unset( $post_types['page'] );
	return $post_types;
} );

Pages d’abonnement

mailerpress_pages_rendered_content (filtre) reçoit le HTML généré par le shortcode [mailerpress_pages] et un tableau contenant action (confirm, confirm_unsubscribe, manage, reengagement_confirm ou unsubscribe), atts (attributs du shortcode) et is_preview. Renvoyez le HTML à afficher. Pour personnaliser ces pages sans code, consultez Personnaliser les pages de gestion d’abonnement et de désinscription dans MailerPress.

Automatisations

Démarrer une automatisation depuis votre code

Le déclencheur Crochet personnalisé démarre une automatisation quand une action WordPress est déclenchée. Par défaut, il accepte les noms de hook qui commencent par mailerpress_custom_. Dans les réglages du déclencheur, saisissez le Nom du crochet et choisissez le type de chaque paramètre (Adresse e-mail, ID utilisateur, ID du contact ou Données personnalisées) ; le champ Exemple de code affiche l’appel do_action() correspondant. Avec une adresse e-mail inconnue, MailerPress crée un contact en attente. L’automatisation doit être créée par un administrateur et activée.

// Type du paramètre 1 : Adresse e-mail
do_action( 'mailerpress_custom_course_completed', $user_email );

Pour utiliser un hook existant dont le nom ne commence pas par mailerpress_custom_, autorisez-le avec le filtre mailerpress/workflows/allowed_custom_hooks :

add_filter( 'mailerpress/workflows/allowed_custom_hooks', function ( $hooks ) {
	$hooks[] = 'my_plugin_order_validated';
	return $hooks;
} );

Filtres et actions des automatisations

Les classes des automatisations se trouvent dans les espaces de noms MailerPress\Core\Workflows\Models (AutomationJob, Step) et MailerPress\Core\Workflows\Results (StepResult). Par exemple, $job->getAutomationId() renvoie l’identifiant de l’automatisation.

Webhooks (MailerPress Pro)

Consultez le Guide des webhooks MailerPress pour la liste des événements et le format des données.

Intégrations de formulaires (MailerPress Pro)

Imports de contacts

Réduisez ces valeurs sur un petit hébergement mutualisé si les imports échouent par dépassement de délai.

Sécurité, réglages et administration

Exemple : votre site est derrière un proxy à l’adresse 203.0.113.10, et vous ne voulez pas que MailerPress charge de promotions.

add_filter( 'mailerpress_trusted_proxies', function ( $proxies ) {
	$proxies[] = '203.0.113.10';
	return $proxies;
} );

add_filter( 'mailerpress_remote_promotions_enabled', '__return_false' );

Pour gérer vos contacts et campagnes depuis une autre application, utilisez l’API REST publique de MailerPress. Pour les outils en ligne de commande, consultez Commandes WP-CLI de MailerPress.