API

La doc de l'API HAPPY Mails

  • Initialisation

    Téléchargez le wrapper officiel HAPPY Mails ici : Télécharger l'API

    Puis ajouter dans votre fichier php ces lignes en adaptant avec vos identifiants.

    require dirname(__FILE__).'/api.happymails.php';
    
    $api_key = 'votre_cle';
    $api_pwd = 'votre_mot_de_passe';
    $server = 'http://server.api.happymails';
    
    $campaign = new Happymails($api_key,$api_pwd,$server);
    

  • addBase

    Cette méthode permet l'ajout d'une nouvelle base d'emails

    Paramètre Description
    name Le nom que va porter la base d'emails
    $params = array();
    $params["name"]="Nom nouvelle base";
    $result = $campaign->addBase();
    
    var_dump($result);
    {"status":"success","id_base":"242"}
    

  • getBases

    Cette méthode va retourner toutes les bases liées à votre compte.

    $result = $campaign->getBases();
    
    print_r($result);
    
    [
        {
            "id_collection": "239",
            "name": "base test",
            "date": "2015-02-03 22:04:31"
        },
        {
            "id_collection": "242",
            "name": "Nom nouvelle base",
            "date": "2015-02-13 11:05:19"
        }
    ]
    

  • deleteBase

    Cette méthode supprime une base d'emails

    Paramètre Description
    id_base Un ID de base d'emails
    $params = array();
    $params["id_base"]=(int)1234;
    $result = $campaign->deleteBase($params);
    
    var_dump($result);
    {"status":"success","message":"deleted"}
    

  • getCampaigns

    Cette méthode va retourner toutes les campagnes liées à votre compte, triées par date de création décroissante.

    $result = $campaign->getCampaigns();
    
    var_dump($result);
    
    [
        {
            "id": "1657",
            "titre": "Campagne via API PHP",
            "sujet": "Campagne via API PHP",
            "url": "http://v2r.happymails.fr/element_campagn/P9Ge8UK6fT2ifeTUbX66IX2G6m6auT/index.html",
            "expediteur": "HAPPY Mails",
            "date": "2015-02-12 16:11:52",
            "etat": "0",
            "id_expediteur": "155",
            "date_start": "0",
            "begin_at": "0",
            "finish_at": "0",
            "bases": "",
            "total": "2",
            "sended": "2",
            "opened": "3",
            "unique_opened": "2",
            "clicked": "0",
            "unique_clicked": "0",
            "bounced": "0",
            "unsub": "0",
            "devices": "2",
            "desktop": "2",
            "tablet": "0",
            "smartphone": "0"
        }
     ]
    

  • addContactToBase

    Cette méthode ajoute un contact dans une base d'emails

    Paramètre Description
    id_base Un ID de base d'emails
    email Un email valide
    attribut Un tableau de données comme le nom, le prénom, afin de pouvoir personnaliser une future campagne
    $params = array();
    $params["id_base"]=(int)1234;
    $params["email"]="email@email.com";
    $params["attribut"]=array("nom"=>"Un nom","prenom"=>"Un prénom");
    $result = $campaign->addContactToBase($params);
    
    var_dump($result);
    {"status":"success","message":"contact inserted"} ou {"status":"success","message":"contact updated"}
    

  • deleteContactFromBase

    Cette méthode supprime un contact d'une base d'emails

    Paramètre Description
    id_base Un ID de base d'emails
    email Une adresse email valide
    $params = array();
    $params["id_base"]=(int)1234;
    $params["email"]="email@domain.tld";
    $result = $campaign->deleteContactFromBase($params);
    
    var_dump($result);
    {"status":"success","message":"deleted"}
    

  • addSender

    Cette méthode permet d'ajouter un expéditeur. Lorsque vous envoyez une campagne il est nécessaire qu'elle le soit avec un expéditeur reconnu et validé.

    En ajoutant un expéditeur, vous recevrez un mail à l'adresse de cet expéditeur. Dans ce mail, vous trouverez un lien sur lequel il faudra cliquer pour valider cet expéditeur dans notre système.

    Ce mécanisme a été mis en place pour lutter contre le fishing ou l'exploitation d'un email d'expédition frauduleusement.

    Paramètre Description
    from Adresse email valide
    $params = array();
    $params["from"]="email@domain.tld";   
    
    $result = $campaign->addSender($params);
    var_dump($result);
    
    {
        "status":"success",
        "message":"sender created, you have received a mail, please click to activate sender",
        "id_sender":"157"
    }
    

  • deleteSender

    Cette méthode permet de supprimer un expéditeur

    Paramètre Description
    from Une adresse email valide
    $params = array();
    $params["from"]="email@domain.tld";   
    
    $result = $campaign->deleteSender($params);
    var_dump($result);
    
    {
        "status":"success",
        "message":"from email is deleted"
    }
    

  • addCampaign

    Cette méthode permet de créer une campagne de mails.

    Paramètre Description Obligatoire
    name Le nom de la campagne, un nom interne que les destinataires ne verront pas Oui
    subject Le sujet de la campagne, celui qui s'affichera dans la boite de réception. Oui
    from_name Un nom d'expéditeur Oui
    from Une adresse email valide, reconnu par Happymails, voir la méthode addSender Oui
    bases Un ID ou une liste d'ID de base, exemple : 125,256,123 ou tout simplement : 15. Si vous n'indiquez pas de bases, la campagne ne sera pas envoyée. Vous devrez utiliser la méthode sendEmail Non
    html Contenu de votre newsletter Oui mais seulement si paramètre 'bases' est renseigné
    html_file URL du contenu de votre newsletter, l'API lira le contenu de cette url et hébergera la newsletter avec les images. Oui mais seulement si paramètre 'bases' est renseigné et paramètre 'html' non renseigné
    date_start La date à laquelle la campagne doit démarrer, format : YYYY-MM-DD HH:MM:SS
    $params = array();
    $params["name"]="Campagne 01";
    $params["subject"]="Notre Nouvelle campagne";
    $params["from_name"]="Nom expéditeur;
    $params["from"]="email@domain.tld";
    $params["bases"]="12,13,14";
    $params["html_file"]="http://www.domain.com/newsletter01/index.html";
    
    $result = $campaign->addCampaign();
    
    var_dump($result);
    {"status":"success","message":"campagn created","id_campagn":"1658"}
    

  • sendEmail

    Cette méthode permet d'envoyer un mail associé à une campagne déjà créée.

    Cette méthode peut par exemple être utilisé dans une boucle pour envoyer votre campagne en masse.

    Paramètre Description Obligatoire
    id_campagn Un ID de campagne créée avec la méthode addCampagn Oui
    to Un email valide Non
    subject Le sujet du mail, si non renseigné, le sujet donné au moment de la création de la campagne est utilisé. Oui
    body Le contenu du mail Oui
    bodytext Le contenu du mail au format brut sans html. Oui
    custom_header des variables supplémentaires Non
    bat Paramètre a utiliser pour faire des tests d'envoi sur la même adresse mail.
    valeur attendue : 1 ou 0
    1 == ne vérifie pas si le destinataire a déjà eu de mail pour la campagne concernée
    0 == n'envoie pas de mail si déjà envoyé pour la campagne concernée.
    Valeur par défaut : 0
    Non
    $params = array();
    $params["id_campagn"]="1234";
    $params["to"]="email@domain.tld";
    $params["subject"]="sujet du mail";
    $params["body"]="contenu html de votre email...";
    $params["custom_header"]=array("my_message_id"=>1234,"other_var"=>"aaabbbccc");
    
    $result = $campaign->sendMail();
    
    var_dump($result);
    {"status":"success","message":"campagn created","id_campagn":"1658"}
    

  • getStatCampaign

    Cette méthode permet de récupérer les statistiques d'une seule campagne.

    Paramètre Description
    id_campagn Un ID de campagne lié à votre compte
    $params = array();
    $params["id_campagn"]="12";   
    
    $result = $campaign->getStatCampaign($params);
    var_dump($result);
    
    {
            "id": "12",
            "titre": "Campagne via API PHP",
            "sujet": "Campagne via API PHP",
            "url": "http://v2r.happymails.fr/element_campagn/P9Ge8UK6fT2ifeTUbX66IX2G6m6auT/index.html",
            "expediteur": "HAPPY Mails",
            "date": "2015-02-12 16:11:52",
            "etat": "0",
            "id_expediteur": "155",
            "date_start": "0",
            "begin_at": "0",
            "finish_at": "0",
            "bases": "",
            "total": "2",
            "sended": "2",
            "opened": "3",
            "unique_opened": "2",
            "clicked": "0",
            "unique_clicked": "0",
            "bounced": "0",
            "unsub": "0",
            "devices": "2",
            "desktop": "2",
            "tablet": "0",
            "smartphone": "0"
        }
    

  • catchEvent

    Cette méthode permet d'ajouter une url dont la fonction est de recevoir un évenement en temps réel.

    Vous pouvez par exemple ajouter une url pour obtenir en temps réel les échecs de votre campagne.

    Lorsqu'un échec est traité, l'API renvoi sur votre url les données complètes avec vos 'custom_header' en prime.
    Il vous suffit de récupérer le flux json envoyé sur avec file_get_contents("php://input");

    Paramètre Description
    event une liste d'évenements reconnu et séparé par une virgule.
    Liste des évenements officiels : bounce, feedbackloop
    url une url valide
    $params = array();
    $params["event"]="bounce,feedbackloop";
    $params["url"]="http://www.domain.tld/catch_event_happymails.php";
    $result = $campaign->catchEvent($params);
    

  • deleteEvent

    Cette méthode supprime un événement attaché à votre compte

    Paramètre Description
    name Un nom d'événement valide : bounce, feedbackloop
    $params = array();
    $params["name"]="bounce";
    $result = $campaign->deleteEvent($params); 
    var_dump($result);
    {"status":"success","message":"event deleted"}
    

  • testEvent

    Cette méthode permet de tester votre url de réception d'événement paramétrée avec la méthode catchEvent.

    Paramètre Description
    event un évenement reconnu.
    Liste des évenements officiels : bounce, feedbackloop
    $params = array();
    $params["event"]="bounce";
    $result = $campaign->testEvent($params);
    

    Votre fichier de réception va lire l'entrée INPUT, elle contiendra un flux json contenant toutes les informations nécessaires au traitement de l'événement.

    $json = file_get_contents("php://input");
    //flux réceptionné, les données que vous recevrez son fictives, uniquement le paramètre reason_bounce change en fonction de l'événement demandé.
    //{"hook":"bounce","message_id":"aabbcc-ddee-ffgg@domain.tld","date":1424939679,"type_bounce":"hard","reason_bounce":"user_reject","email":"email@domain.tld","custom_var":{"var_1":"content_var_1","var_2":"content_var_1","var_3":"content_var_1"}}
    
    $event = json_decode($rest_json, true);
    //placer ici le code de traitement de votre événement
    

  • getLogs

    Cette méthode permet de récupérer les logs complets d'un mail envoyé, peu importe sa délivrabilité.

    Paramètre Description
    message_id un message_id reconnu.
    $params = array();
    $params["message_id"]="123456789@domain.tld";
    $result = $campaign->getLogs($params);
    

    Il se peut qu'au moment de l'appel de cette méthode, les logs ne soient pas encore totalement enregistrés dans notre système. Dans ce cas, la méthode retournera cette information et vous pourrez revenir plus tard pour récupérer les logs complets.


  • Exemple concret

    Partons du principe que vous n'avez encore envoyé aucune campagne, que vous venez de recevoir vos identifiants API et que vous souhaitez les utiliser pour créer votre 1ère campagne.

    L'API d'HAPPY Mails vous permet de créer et d'envoyer une campagne de deux manières.

    Méthode 1 :
    La première méthode consiste à créer une base puis une campagne en y associant cette base. Dans ce cas, le routage est géré intégralement par notre système.

    Dans l'ordre, voici les étapes à suivre :
    • Création d'un expéditeur
    • Validation de l'expéditeur
    • Création de la base
    • Ajout des destinataires dans la base
    • Création de la campagne

    Le code :

    require dirname(__FILE__).'/api.happymails.php';
    
    $api_key = 'api_key';
    $api_pwd = 'api_passwd';
    
    $campaign = new Happymails($api_key,$api_pwd);
    
    //Création d'un expediteur
    $params = array();
    $params["from"] = "email@domain.tld";
    $result = $campaign->addSender($params);
    //après execution de cet appel, un email est envoyé, vous devez cliquer dans ce mail pour valider l'adresse email.
    
    //Création d'une base d'emails vierge
    $params = array();
    $params["name"] = "ma base emails 01";
    
    $result = $campaign->addbase($params);
    echo $id_base = $result["id_base"];
    
    //Ajout de contact dans la base d'emails
    //On lit par exemple le contenu d'un fichier csv
    $contacts = file("./mabase.csv");
    foreach($contacts as $contact){
        list($email, $nom, $prenom) = explode(";",$contact);
        $params = array();
        $params["id_base"]=$id_base;
        $params["email"]=$email;
        $params["attribut"]=array("nom"=>$nom,"prenom"=>$prenom);
        $campaign->addContactToBase($params);
    }
    
    //on créer maintenant la campagne
    $params = array();
    $params["name"]="Campagne methode 1";
    $params["subject"]="Notre Nouvelle campagne";
    $params["from_name"]="Nom expéditeur";
    $params["from"]="email@domain.tld";
    $params["bases"]=$id_base;
    $params["html_file"]="http://v2.happymails.fr/processing/process.php?action=voirmail&campagn=vDgCLTbb5SZtKxi1imkO8dJJYFPR1q";
    
    //si vous n'ajoutez par le paramètre date_start, la campagne part immédiatement.
    //$params["date_start"]="2015-03-01 18:50:00";
    
    $result = $campaign->addCampaign($params);
    print_r($result);
    
    

     

    Méthode 2 :
    La seconde méthode consiste à créer une campagne mais sans y associer de base de d'emails. C'est vous par la suite qui enverrez l'un après l'autre les mails, à la vitesse que vous voulez, aux destinataires que vous souhaitez, dans l'ordre que vous souhaitez.

    Dans l'ordre, voici les étapes à suivre :
    • Création d'un expéditeur
    • Validation de l'expéditeur
    • Création de la campagne
    • Envoi des mails aux destinataires

    Le code :

    require dirname(__FILE__).'/api.happymails.php';
    
    $api_key = 'api_key';
    $api_pwd = 'api_passwd';
    
    $campaign = new Happymails($api_key,$api_pwd);
    
    //Création d'un expediteur
    $params = array();
    $params["from"] = "email@domain.tld";
    $result = $campaign->addSender($params);
    //après execution de cet appel, un email est envoyé, vous devez cliquer dans ce mail pour valider l'adresse email.
    
    //on créer la campagne
    $params = array();
    $params["name"]="Campagne 01";
    $params["subject"]="Notre Nouvelle campagne";
    $params["from_name"]="HAPPY Mails";
    $params["from"]="email@domain.tld";
    
    $result = $campaign->addCampaign($params);
    
    if($result["status"]=="success"){
        $id_campagn = $result["id_campagn"];
    
        $contacts = file("./mabase.csv");
        foreach($contacts as $contact){
            list($email, $prenom, $nom) = explode(";",$contact);
            $params = array();
            $params["id_campagn"]=$id_campagn;
            $params["to"]=$email;
            $params["body"]="contenu html de votre email...";
            $params["subject"]="Bienvenue ".$prenom." ".$nom;
            //vous pouvez ajouter des variables dans l'entête du mail avec le paramètre 'custom_header'
            //Vous retrouverez par exemple ces variables lors du traitement des echecs
            $params["custom_header"]=array("unique_id"=>rand(1,1000000000),"other_var"=>rand(1,1000000000));
            
            $result = $campaign->sendEmail($params);
        }
    }else{
        print_r($result["message"]);
    }
    
    
    

    Note : Vous pourriez rencontrer des problèmes avec les accents dans certains paramètres, enregistrez vos fichiers en UTF8 sans BOM pour y remédier.


  • Les différents types d'échecs

    Les types d'échecs

    • autoreply
    • blocked
    • generic
    • hard
    • soft
    • temporary

    Les raisons d'échecs

    • antispam
    • autoreply
    • concurrent
    • content_reject
    • command_reject
    • defer
    • delayed
    • dns_loop
    • dns_unknown
    • full
    • inactive
    • internal_error
    • latin_only
    • other
    • oversize
    • timeout
    • unknown
    • unrecognized
    • user_reject
    • warning