API d'envoi de mails

Un article de OviWiki.


L'envoi des mails s'appuie sur la configuration SMTP renseignée par l'administrateur du site. Avant d'utiliser les fonctions disponibles, un fichier PHP doit être inclut :

global $babInstallPath;
include_once $babInstallPath."utilit/mailincl.php";

Sommaire

bab_mail()

Retourne un objet permettant de définir le contenu d'un mail et ses destinataires. Si l'administrateur du site a désactivé l'envoi de mails, la fonction bab_mail() renverra un booléen à la valeur false.

Exemple d'intégration en PHP :

$mail = bab_mail();
if(!$mail) {
       return true;
} else {
       ...
}

mailFrom()

Cette méthode est disponible sur l'objet renvoyé par bab_mail(). Elle permet de définir l'expéditeur du mail.

mailFrom($expediteur_mail, $expediteur_nom)
  • $expediteur_mail
    e-mail de l'expéditeur
  • $expediteur_nom
    nom de l'expéditeur

mailTo()

Cette méthode est disponible sur l'objet renvoyé par bab_mail(). Elle permet de définir le destinataire du mail. Elle peut être exécuté plusieurs fois pour définir plusieurs destinataires.

mailTo($destinataire_mail, $destinataire_nom)
  • $destinataire_mail
    e-mail du destinataire
  • $destinataire_nom
    nom du destinataire

mailCc()

Cette méthode est disponible sur l'objet renvoyé par bab_mail(). Elle permet de définir un destinataire supplémentaire en mode CC (copie) du mail. Elle peut être exécutée plusieurs fois pour définir plusieurs destinataires.

mailCc($destinataire_mail, $destinataire_nom)
  • $destinataire_mail
    e-mail du destinataire
  • $destinataire_nom
    nom du destinataire

mailBcc()

Cette méthode est disponible sur l'objet renvoyé par bab_mail(). Elle permet de définir un destinataire supplémentaire en mode BCC (copie cachée) du mail. Elle peut être exécutée plusieurs fois pour définir plusieurs destinataires. $mail->mailBcc($destinataire_mail, $destinataire_nom);

mailBcc($destinataire_mail, $destinataire_nom)
  • $destinataire_mail
    e-mail du destinataire
  • $destinataire_nom
    nom du destinataire

ClearTo()

Cette méthode est disponible sur l'objet renvoyé par bab_mail(). Elle permet de supprimer (réinitialiser) les destinataires.

ClearCc()

Cette méthode est disponible sur l'objet renvoyé par bab_mail(). Elle permet de supprimer (réinitialiser) les destinataires.

ClearBcc()

Cette méthode est disponible sur l'objet renvoyé par bab_mail(). Elle permet de supprimer (réinitialiser) les destinataires.

mailReplyTo()

Cette méthode est disponible sur l'objet renvoyé par bab_mail(). Elle permet de définir le destinataire dans le cas d'une réponse au mail. Elle peut être exécutée plusieurs fois pour définir plusieurs destinataires. Cette fonction est optionnelle.

mailReplyTo($destinataire_mail, $destinataire_nom)
  • $destinataire_mail
    e-mail du destinataire
  • $destinataire_nom
    nom du destinataire

ClearReplyTo()

Cette méthode est disponible sur l'objet renvoyé par bab_mail(). Elle permet de supprimer (réinitialiser) les destinataires dans le cas d'une réponse au mail.

setPriority()

Cette méthode est disponible sur l'objet renvoyé par bab_mail(). Elle permet de définir la priorité du mail. Cette fonction est optionnelle.

setPriority($priorite)
  • $priorite
    entier compris entre 1 et 5 :

1 étant une priorité haute 3 étant une priorité normale 5 étant une priorité faible

mailSubject()

Cette méthode est disponible sur l'objet renvoyé par bab_mail(). Elle permet de définir le sujet du mail.

mailSubject($sujet)
  • $sujet
    sujet du mail

mailBody()

Cette méthode est disponible sur l'objet renvoyé par bab_mail(). Elle permet de définir le contenu du mail.

mailBody($contenu, $format)
  • $contenu
    contenu du mail
  • $format
    paramètre optionnel indiquant le format du contenu (html ou plain) (HTML par défaut)

mailAltBody()

Cette méthode est disponible sur l'objet renvoyé par bab_mail(). Elle permet de définir le contenu alternatif du mail, c'est à dire le contenu en mode texte qui sera visible si le destinataire choisit de ne pas afficher le mail en mode HTML.

mailAltBody($contenu)
  • $contenu
    contenu du mail

mailTemplate()

Cette méthode est disponible sur l'objet renvoyé par bab_mail(). Elle permet d'envoyer le mail en tenant compte du template du site Ovidentia (mailtemplate.html).

mailTemplate($contenu)
  • $contenu
    contenu du mail

Exemple d'intégration en PHP :

global $babInstallPath;
include_once $babInstallPath."utilit/mailincl.php";
 
$mail = bab_mail();
if(!$mail) {
	//L'administrateur a désactivé l'envoi des mails
} else {
	$mail->mailFrom($expediteurmail, $expediteur);
	$mail->mailTo($destinatairemail, $destinataire);
	$mail->mailSubject($sujet);
	$mail->mailBody($mail->mailTemplate($contenu));
	$mail->send();
}

mailFileAttach()

Cette méthode est disponible sur l'objet renvoyé par bab_mail(). Elle permet d'attacher une pièce jointe au mail. Elle peut être exécutée plusieurs fois pour attacher plusieurs fichiers.

mailFileAttach($cheminfichier, $nomfichier, $typefichier)
  • $cheminfichier
    chemin système d'accès au fichier
  • $nomfichier
    nom du fichier
  • $typefichier
    type mime du fichier

send()

Cette méthode est disponible sur l'objet renvoyé par bab_mail(). Elle permet d'envoyer le mail. Elle doit donc être appelée après avoir configuré le mail.

cette méthode retourne false, s'il est impossible d'envoyer le message.


ErrorInfo()

Cette méthode retourne un message d'erreur ou false si il n'y a pas d'erreur, le message d'erreur est déclenché par la méthode send()

exemple :

if (false === $mail->send()) {
     $babBody->addError($mail->ErrorInfo());
}


Le message peut être un message non traduit renvoyé pas le serveur SMTP



Événements

Image:warning.png Depuis la version 7.2.0 d'Ovidentia

API du gestionnaire d'événement

Événement Parent Description
bab_eventMail bab_event Événement principal utilisé dans l'API de la messagerie, il regroupe tout les évènements appelés lors de l'envoi des email
bab_eventBeforeMailSent bab_eventMail Événement déclenché avant l'envoi d'un email, il permet d'annuler l'envoi avec la méthode cancel()
bab_eventAfterMailSent bab_eventMail Événement déclenché après l'envoi d'un email, il permet de récupérer un plus le statut de l'envoi