API Newsletter

L’API Newsletter se décompose en 3 modules subscribe, compose et send qui correspondent aux 3 grandes fonctionnalités qui constituent la gestion de Newsletter.

subscribe

Un exemple d’implémentation est fourni par le plugin Mailsubscribers

newsletter/subscribe

Inscrit un subscriber par son email. Si le subscriber existe deja, on met a jour les informations (nom, listes, lang). L’ajout d’une inscription a une liste est cumulatif : si on appelle plusieurs fois la fonction avec le même email et plusieurs listes différentes, l’inscrit sera sur chaque liste.
Pour retirer un mail d’une liste, il faut le désinscrire.

Quand aucune liste n’est indiquée :

  • si l’email n’est inscrit a rien, on l’inscrit a la liste générale newsletter
  • si l’email est déjà inscrit, on ne change pas ses inscriptions, mais on modifie ses informations (nom,lang)
$subscribe = charger_fonction("subscribe","newsletter");
$subscribe($email, $options);
* @param $email
 *   champ obligatoire
 * @param array $options
 *   nom : string
 *   listes : array (si non fourni, inscrit a la liste generale 'newsletter')
 *   lang : string
 *   force : bool permet de forcer une inscription sans doubleoptin (passe direct en valide)
 *   graceful : bool permet a contrario de ne pas inscrire quelqu'un qui s'est desabonne (utilise lors de l'import en nombre, l'utilisateur est ignore dans ce cas)
 * @return bool
 *   true si inscrit comme demande, false sinon
 *
 *

newsletter/unsubscribe

Désinscrire un subscriber par son email. Si une ou plusieurs listes sont précisées, le subscriber est désinscrit de ces seules listes. Si il n’en reste aucune, le statut du subscriber est suspendu. Si aucune liste n’est précisée, le subscriber est désinscrit de toutes les listes newsletter.

$unsubscribe = charger_fonction("unsubscribe","newsletter");
$unsubscribe($email, $options);
*
 * @param $email
 *   champ obligatoire
 * @param array $options
 *   listes : array
 * @return bool
 *   true si inscrit, false sinon

newsletter/subscriber

Décrit les informations d’un inscrit. Pour retirer une liste il faut utiliser unsubscribe.

$subscriber = charger_fonction("subscriber","newsletter");
$subscriber($email);
*
 * @param $email
 *   champ obligatoire
 * @return bool|array
 *   false si n'existe pas
 *   array :
 *     string email
 *     string nom
 *     array listes
 *     string lang
 *     string status : on|pending|off
 *     string url_unsubscribe : url de desabonnement
 */

newsletter/subscribers

Renvoie les inscrits à une ou plusieurs listes. Si plusieurs listes sont demandées, c’est un OU qui s’applique (renvoie les inscrits à au moins une des listes). Les options count et limit permettent de faire un simple comptage ou de ne récupérer qu’une portion de la liste.

$subscribers = charger_fonction("subscribers","newsletter");
$inscrits = $subscribers($listes,$options);
*
 * @param array $listes
 *   listes de diffusion. 'newsletter' si non precise
 * @param array $options
 *   count : si true renvoyer le nombre de resultats au lieu de la liste (perf issue, permet de tronconner)
 *   limit : ne recuperer qu'un sous ensemble des inscrits "10,20" pour recuperer 20 resultats a partir du 10e (idem SQL)
 * @return int|array
 *   liste d'utilisateurs, chacun decrit par un array dans le meme format que newsletter/subscriber

newsletter/lists

Renvoie les listes de diffusion disponibles avec leurs statuts (open,close,?).

$lists = charger_fonction("lists","newsletter");
$inscrits = $lists($options);
*
 * @param array $options
 *   status : filtrer les listes sur le status
 * @return array
 *   listes
 *   chaque liste est decrite par :
 *   id => array(titre=>'','status'=>'')

#FORMULAIRE_NEWSLETTER_SUBSCRIBE

Permet d’insérer dans une page un formulaire d’inscription à la newsletter, ou à une ou plusieurs autres listes passées en argument.

#FORMULAIRE_NEWSLETTER_SUBSCRIBE
 
#FORMULAIRE_NEWSLETTER_SUBSCRIBE{nouveautes}
 
#FORMULAIRE_NEWSLETTER_SUBSCRIBE{newsletter,nouveautes}

#FORMULAIRE_NEWSLETTER_UNSUBSCRIBE

Permet d’insérer dans une page un formulaire de désinscription à la newsletter, ou à une ou plusieurs autres listes passées en argument.

#FORMULAIRE_NEWSLETTER_UNSUBSCRIBE
 
#FORMULAIRE_NEWSLETTER_UNSUBSCRIBE{nouveautes}
 
#FORMULAIRE_NEWSLETTER_UNSUBSCRIBE{newsletter,nouveautes}

compose

Un exemple d’implémentation est fourni par le plugin Newsletters

newsletter/content

Renvoyer le contenu d’une newsletter par son id (le format de l’id n’est pas imposé par l’API et peut être un entier ou une chaine. Il doit être cohérent avec celui passé à la fonction newsletter/send).

$content = charger_fonction("content","newsletter");
$lettre = $content($id);
*
 * @param int|string $id
 * @return array|bool
 *   string sujet
 *   string html
 *   string texte

newsletter/contextualize

Contextualiser le contenu de l’infolettre en fonction des informations concernant le destinataire. La syntaxe des variables n’est pas imposée par l’API et dépend de l’implémentation par le plugin qui prend en charge cette partie de l’API.

$contextualize = charger_fonction("contextualize","newsletter");
$content2 = $contextualize($content, $context);
* @param $content
 *   le contenu (html ou texte) de la newsletter
 * @param $context
 *   le contexte des variables
 * @return string
 */

send

Un exemple d’implémentation est fourni par le plugin Mailshot

newsletter/send

Envoie une infolettre à un destinataire. L’infolettre peut être fournie par son id (et la fonction utilisera newsletter/content pour récupérer son contenu détaillé, ou decrite explicitement par un tableau (de format homogène à ce que attend envoyer_mail).

L’argument $destinataire attendu est homogène à ce que fournit newsletter/subscriber.

Le contenu $corps de l’email sera contextualisé à l’aide du contenu de $destinataire au moyen de la fonction newsletter/contextualize

$send = charger_fonction("send","newsletter");
$res = $send($destinataire, $corps, $options);
*
 * @param array $destinataire
 *   description du destinataire
 *     string email
 *     string nom
 *     array listes
 *     string lang
 *     string status : on|pending|off
 *     string url_unsubscribe : url de desabonnement
 *
 * @param array|string $corps
 *   string id de la newsletter
 *ou array contenu de la newsletter
 *     string sujet
 *     string html
 *     string texte
 *     string from : email de l'envoyeur
 *     string nom_envoyeur : un nom d'envoyeur pour compléter l'email from
 *     string cc : destinataires en copie conforme
 *     string bcc : destinataires en copie conforme cachee
 *     string|array repondre_a : une ou plusieurs adresses a qui repondre
 *
 * @param array $options
 *   options d'envoi
 *     bool test : mode test (ajoute un [TEST] dans le sujet
 *     string tracking_id
 *
 * @return string|int
 *   vide si ok, ou message d'erreur sinon

newsletter/bulkstart

Démarrer un envoi en nombre d’une info-lettre vers une ou plusieurs listes.

$bulkstart = charger_fonction("bulkstart","newsletter");
$res = $bulkstart($corps, $listes, $options);
* 
 * @param string|array $corps
 *   string id de la newsletter a envoyer en lot
 *ou array contenu a envoyer
 *     string sujet
 *     string html
 *     string texte
 * @param array $listes
 *   listes a qui on envoie (1 ou ++)
 * @param array $options
 *   string statut : statut par defaut
 * @return int
 *   0 si echec ou id de l'envoi sinon

newsletter/feedback

Permet la prise en compte d’un évènement concernant un mail envoyé (tracking de l’ouverture, clic sur un lien, bounce...) pour mettre à jour le statut de l’envoi correspondant, ou désabonner un email qui n’est plus valide etc.

$feedback = charger_fonction("feedback","newsletter");
$feedback($quoi, $email, $tracking_id);

Le tracking_id correspond à celui qui a été fourni en option dans l’appel à newsletter/bulkstart.

* 
 * @param string $quoi
 *   open : l'email a ete ouvert
 *   clic : un lien a ete clique
 *   soft_bounce : refus temporaire pour cause de boite mail pleine ou autre
 *   hard_bounce : adresse foireuse, refus definitif
 *   reject : email rejete
 *   spam : email taggue en spam
 * @param $email
 * @param $tracking_id

#FORMULAIRE_NEWSLETTER_SEND

Permet d’envoyer une info-lettres. L’identifiant de l’info-lettres est fourni en argument.
Il n’y a aucune contrainte sur cet identifiant, qui doit simplement être reconnu par la fonction newsletter/content à laquelle il sera passé.

Un second argument permet de préciser que l’envoi se fait en mode test uniquement (pour les info-lettres non finalisées par exemple). En mode test, le sujet du mail est préfixé par [TEST] et l’envoi en nombre n’est pas permis.

#FORMULAIRE_NEWSLETTER_SEND{#ID_NEWSLETTER}
 
[(#REM) En mode test : ]
#FORMULAIRE_NEWSLETTER_SEND{#ID_NEWSLETTER,' '}

Dernière modification de cette page le 9 février 2019

Discussion

7 discussions

  • 4

    Déjà posté ailleurs mais bon je cherche ....

    Bonjour,

    Je ne sais si c’est le bon endroit, mais j’ai un problème avec l’ordre :

    [(#ENV{date}|affdate)] qui affiche dans un titre d’infolettre par exemple, la date !

    qui est incompatible avec le plugin Enluminures typographiques V3
    car les [(........)] centrent un texte et donc c’est la grosse caguade, aucune idée pour en sortir et vous ?

    Merci :-)

    • En faisant #SET{frdate,#ENV{date}|affdate} avant, tu peux utiliser #GET{frdate} qui probablement ne présente plus le pb.

    • Cela n’a marché qu’une seule fois .... puis les { sont traités comme italique et tout plante ! Mais le concept est bon !!!

      Merci mais je pense que la modif devrait être + lourde ! Et je n’ai pas envie de bricoler le plugin !

    • C’est le rôle de l’API contextualize en fait. Faut passer la date dans le contexte et ça sera interprété, mais je sais pas encore trop comment précisément.

    • Mon cher confrère, en cette occasion qui nous rassemble ....

    Répondre à ce message

  • 2

    Erreur : il faut un sujet
    Je tombe sur un os : Impossible de faire un test d’envoi : j’ai ce message « erreur, il faut un sujet » et le processus est bloqué. (voir la copie d’écran ci-dessous).
    J’ai l’impression d’avoir pourtant renseigné ce qu’il fallait (l’infolettre a un titre ) .. C’est moi qui passe à côté de quelque chose ou il y a un schmiliblick quelque part ?

    SPIP 3.0.20
    newsletter/mailsubscribers/facteur : à jour

    Répondre à ce message

  • 7

    Bonjour,

    Suite à une mise à jour de spip 3.0.16 à 3.1, et des plugins :
    -  Newsletter 1.3.16
    -  Mailsubscriber 1.7.8
    -  Mailshot 1.14.1

    Depuis l’interface de publication de la newsletter, avec le statut « publier en ligne », nous ne parvenons plus à sélectionner la liste des abonnés comme c’était le cas auparavant...
    Dans le option du select, on aperçois « Ouverte » qui est le statut de la liste, mais pas la liste elle-même (nommée Newsletter pour l’originalité ;-) )

    Du coup pas d’envoi possible !!
    Nous avons plus de 2000 inscrits et nous aimerions effectuer cet envoi rapidement...
    Que pouvons-nous faire ? Est-ce un bug ?

    Merci de vos lumières...

    • Bonjour,

      je viens de vérifier chez moi suite aux modifications récentes, tout apparait bien. Par contre, il faut que la liste ait des inscrits pour apparaitre. Il y a peut-être un problème de cache sur le nombre d’inscrits si tu viens tout juste de les importer. Essaye avec &var_mode=calcul dans l’URL de la page ?

    • Bonjour Cerdic, ces lettres sont envoyées tous les mois depuis septembre 2014 sans aucun problèmes :)
      La listes des inscrits est toujours la même, quelques inscrits en plus et en moins, c’est tout.
      Ci-joint une impression d’écran...
      J’hésite à vider le cache à la main (temps de calcul / affichage...), mais déjà fait via l’interface admin.

      Merci de ton aide !

    • On dirait un bug dans le comptage du nombre d’inscrit. Tu sais quelle version du plugin mailshot tu avais avant la mise à jour ? Tu as essayé d’ajouter &var_mode=calcul dans l’URL de la page de la newsletter pour voir si ça résoud ?

    • Bonjour Cerdic,

      Nouvelle version de Mailshot disponible ce matin donc mise à jour (1.14.1 -> 1.14.2)
      Vidage du cache par FTP, et du coup plus de « Ouverte » dans la liste déroulant, plus rien :-/
      Dans la liste des inscrits j’ai bien « La Newsletter » avec 1752 inscrits, mais elle n’apparait plus dans le select...
      ... et oui j’ai bien ajouté &var_mode=calcul à l’url, sans effet.
      ... et non je ne me souviens plus de l’ancienne version de Mailshot, mais elle datait probablement de juin 2014 (?)

      Que pouvons-nous faire ?

    • Précision peut-être importante (?), SPIP est mutualisé (2 sites), et celui-ci est en sous-domaine de l’autre... Mais encore une fois, tout se passait très bien jusqu’à l’upgrade d’hier.

    • Corrigé par http://zone.spip.org/trac/spip-zone/changeset/95698/_plugins_/mailsubscribers qui traite le cas particulier des listes de diffusion avec un identifiant numerique !

    • Je n’ai qu’un mot, Bravo !
      Moins de 24 heures pour corriger et mettre à jour trois plugins ! Qui dit mieux ???
      Respect :-)

    Répondre à ce message

  • Christophe

    Bonjour,

            $send = charger_fonction("send","newsletter");

    Sauf erreur, lors de l’appel de la fonction "send", si $corps est un tableau, les infos 'from' et 'nom_envoyeur' ne sont pas récupérés.

    Il faut ajouter dans le fichier « send.php », le code

            $from = $corps['from'];
            $nom_envoyeur = $corps['nom_envoyeur'];

    .

    Répondre à ce message

  • 4

    Bonjour,

    Lors de l’inscription à la newsletter via le formulaire qui est inséré dans un article de la manière suivante :
    <formulaire|newsletter_subscribe>

    si je saisi une adresse mail et que je clique sur « m’inscrire à la newsletter », je n’ai pas le message de retour qui indique (sur cette même page) que l’inscription est prise en compte !?

    Pourtant le reste du processus est parfait.

    Quel pourrait être le souci à votre avis ?

    MErci,
    françois

    • Est-ce que ton article ne serait pas affiché via un #INCLURE dans le squelette ? Si c’est le cas peux-tu essayer avec <INCLURE> à la place ? Sinon peux tu essayer en insérant le formulaire dans le squelette et non dans l’article pour vérifier si cela fonctionne mieux ?

    • Je n’ai pas précisé que j’utilisais les dernières versions de SPIP3 et des plugins.

      Mon article n’est pas affiché via un #INCLURE.

      Je viens d’essayer avec une insertion directe (dans mon squelette article.html) du formulaire #FORMULAIRE_NEWSLETTER_SUBSCRIBE et le phénomène est le même : juste après avoir cliqué sur « m’inscrire à la newsletter », il y a bien la petite roue ajax qui tourne, mais pas de message qui s’affiche.

      L’inscription se déroule néanmoins correctement.

    • Je ne sais pas si il y a des éléments en commun entre les 2 plugins, mais j’utilise le plugin FORMIDABLE pour ma page de contact, et lors de l’envoi d’un message, j’ai bien le message de retour ajax « Votre message a bien été envoyé par courriel ».

    • OUPS !!!

      Le message est bien présent, mais j’avais un style css personnalisé qui le masquait (display :none) :-((((

      Désolé pour le bruit Cédric.
      françois

    Répondre à ce message

  • 4

    Bonjour,

    Quelle sera la syntaxe pour insérer un formulaire d’inscription à la newsletter dans un article ?

    Merci,
    françois

    • Salut, tout simplement :

      <formulaire|newsletter_subscribe>

      cf la doc des formulaires de SPIP : http://www.spip.net/fr_article3796.html

      ++

    • Parfait !
      Merci b_b

    • Pierrot

      Bonjour,

      J’avais trouvé pour cette syntaxe de base, le problème est qu’elle inscrit la personne à la liste newsletter::newsletter ... Quelle est la syntaxe si on veut inscrire à une liste spécifique ?
      on a essayé :

      <formulaire|newsletter_subscribe|liste=newsletter::uneautrenewsletter>
      <formulaire|newsletter_subscribe|newsletter::uneautrenewsletter>
      <formulaire|newsletter_subscribe|liste=uneautrenewsletter>
      <formulaire|newsletter_subscribe|uneautrenewsletter>

      Marche pas. A noter d’ailleurs qu’on constate que la syntaxe « newsletter::uneautrenewsletter » est obligatoire :

      #FORMULAIRE_NEWSLETTER_SUBSCRIBE{uneautrenewsletter} 

      ne marche pas ici, les inscrits se retrouvent dans newsletter::newsletter (si cette liste n’existe pas elle se crée direct avec le nouvel inscrit) , il faut utiliser :

      #FORMULAIRE_NEWSLETTER_SUBSCRIBE{newsletter::uneautrenewsletter} 

      marche bien, les inscrits se retrouvent dans la bonne liste

      On a tout faux ?

      Pierre.

    • Pierrot

      Je me permet un petit up sur ce sujet pour lequel je ne trouve pas la solution. J’ai tourné le pbm en créant un modèle qui inclut lui le bon formulaire d’inscription à une newsletter spécifique mais c’est moins pratique et plus lourd ...
      P.

    Répondre à ce message

  • Fantastique !

    Répondre à ce message

Ajouter un commentaire

Qui êtes-vous ?

Pour afficher votre trombine avec votre message, enregistrez-la d’abord sur gravatar.com (gratuit et indolore) et n’oubliez pas d’indiquer votre adresse e-mail ici.

Ajoutez votre commentaire ici

Ce champ accepte les raccourcis SPIP {{gras}} {italique} -*liste [texte->url] <quote> <code> et le code HTML <q> <del> <ins>. Pour créer des paragraphes, laissez simplement des lignes vides.

Ajouter un document

Suivre les commentaires : RSS 2.0 | Atom