Le paramétrage de base utilisé par jMailer s'effectue dans le fichier var/config/localconfig.ini.php de votre application dans la section [mailer].

Les principales options de configuration ¶

Configuration SMTP ¶

[smtp:mymailer]
host = localhost
; habituellement, 587, 465 ou 25 (non sécurisé)
port = 587 ; ou 465, ou 25

;connection sécurisée ou pas (valeurs possibles: "", "ssl", "tls" ou "unencrypted")
secure_protocol = tls
timeout = 20

; Active ou non l'authentification
auth_enabled = on
username = me@foo
password = thepassword

[mailer]
webmasterEmail = webmaster@foo.com
mailerType = smtp
smtpProfile = mymailer

[mailer]
webmasterEmail = webmaster@foo.com
mailerType = smtp

; paramètres obsolètes pour la configuration SMTP
smtpHost = localhost
smtpPort = 465
smtpSecure = ssl
smtpHelo=
smtpTimeout = 20
smtpAuth = on
smtpUsername = "me@foo"
smtpPassword = thepassword

Envoi d'un email texte avec le paramétrage par défaut.

  $mail = new jMailer();

  $mail->Subject = 'Sujet de l\'email';
  $mail->Body = 'Contenu du message texte';

  $mail->AddAddress('destinataire@exemple.com' , 'Nom du destinataire');

  $mail->Send();

Vous pouvez utiliser toutes la puissance de jTpl a l'intérieur de vos mail. Pour Cela il vous suffit de créer un fichier .tpl dans l'un de vos module.

Exemple dans modules/monmodule/templates/supermail.tpl :

    {meta Subject 'Super mail.'}
    {meta Priority 1}
    {meta From 'votre nom<votre@mail.com>'}
    {meta Sender 'votre@mail.com'}
    {meta ReplyTo array('votre nom<votre@mail.com>')}
    {meta to array($name.'<'.$email.'>')}
    {meta cc array('titi <titi@example.com>')}
    {meta bcc array('tutu <tutu@example.com>')}

    Salut {$name},

    Voici un super mail généré par jMailer et Jelix.

Et dans votre code PHP :

    $mail = new jMailer();
    $tpl = $mail->Tpl('monmodule~supermail');
    $tpl->assign('name', 'Monsieur Toto');
    $tpl->assign('email', 'toto@example.com');
    $mail->Send();

Il est à noter que jMailer créé des variables de templates correspondantes à des propriétés (protégées) de PHPMailer. Vous pouvez ainsi y accéder dans votre template.

    {meta Subject 'Super mail.'}
    {meta Priority 1}
    {meta From 'votre nom<votre@mail.com>'}
    {meta Sender 'votre@mail.com'}
    {meta ReplyTo array('votre nom<votre@mail.com>')}
    {meta to array($name.'<'.$email.'>')}
    {meta cc array('titi <titi@example.com>', 'tutu <tutu@example.com>')}

    Salut {$name},

    Voici un super mail généré par jMailer et Jelix. Il est en copie à :
    {foreach $cc as $person}
      - {$person[0]}
    {/foreach}

Pour envoyer un email en HTML, il suffit d'appeler la méthode isHTML() comme dans l'exemple suivant :

$mail = new jMailer();
$mail->isHTML(true);
$mail->Body = "<p>Envoi d'un mail en <strong>HTML</strong> !</p>";
$mail->AddAddress('toto@example.com' , 'Toto');
$mail->Send();

Vous pouvez aussi utiliser un template en HTML, il faut alors indiquer true à la méthode Tpl en second paramètre.

$tpl = $mail->Tpl('monmodule~supermail', true);

PHPMailer incluera dans le mail le contenu HTML que vous donnez, mais aussi une version purement textuelle de votre contenu, en enlevant les balises HTML, les rêgles css et le code javascript. jMailer améliore la conversion en préservant les liens des balises <a>, c'est à dire en affichant les URLS des liens entre parenthèses après l'intitulé du lien, sauf si il y a un attribut ou une classe notexpandlink.

Vous pouvez fournir votre propre convertisseur HTML vers texte, en l'indiquant en troisième paramètre à Tpl(). Cela doit être un paramètre de type callable.

$tpl = $mail->Tpl(
    'mymodule~supermail',
    true,
    function ($html) {
        // ... convert to text
        return $text;
    }
);

Votre HTML peut avoir des images, avec la balise <img>. Si l'attribut src n'est pas une URL, alors PHPMailer considère que c'est un chemin de fichier sur le disque, et inclus l'image dans le mail. Le chemin de l'image indiqué peut être un chemin absolu sur le disque. Si c'est un chemin relatif, vous devez indiquer en quatrième paramètre de Tpl() le chemin de base des images.

Dans cet exemple, les images affichées dans le mail se trouvent dans le répertoire www/images/ de l'application.

$tpl = $mail->Tpl(
    'mymodule~supermail',
    true,
    null,
    jApp::wwwPath('images/')
);

L'envoi de fichier en pièce jointe se fait très simplement, en donnant le chemin du fichier stocké sur le disque, et le nom que l'on veut faire apparaitre.

$mail = new jMailer();
$mail->AddAttachment(jApp::varPath('nom_fichier_original.pdf'), 'nom_fichier_pour_email.pdf');
...
$mail->Send();

jMailer utilise comme base PHPMailer, si vous voulez avoir d'avantage de documentation, consultez la documentation de PHPMailer.

Si vous voulez savoir si jMailer enverra correctement les emails avec la configuration effectuée, vous pouvez lancer la commande php console.php mailer:test. Donnez une adresse email à cette commande, et un email sera envoyé à cette adresse.

` php console.php mailer:test john.doe@example.com `

Dans certains environnement de tests, comme votre machine de développement, vous ne voudriez pas envoyer de mail. Pour désactiver l'envoi de mail, mettez mailerType = file, et tous les mails seront enregistrés dans des fichiers dans var/mails/. Cela vous permet de vérifier le contenu des mails qui ont été générés.

Sur un serveur de démo où vous voulez quand même envoyer des mails, vous avez des fonctionnalités qui facilitent le débuggage.

Si vous voulez par exemple avoir une copie fichier de tous les emails envoyés, mettez copyToFiles = on dans la section mailer.

À partir de Jelix 1.6.17, vous pouvez forcer les destinataires des mails, ainsi tous les mails iront chez eux plutôt que chez le destinataire indiqué dans le mail.

Pour activer cette fonctionnalité, mettez debugModeEnabled = on, et la liste des destinataires dans debugReceivers. Ici, tous les mails seront envoyés à Bob et à Joe, même si d'autres destinataires sont indiqués dans les mails.

debugModeEnabled = on
debugReceivers[] = bob@foo.local
debugReceivers[] = joe@foo.local

Vous avez d'autre paramètres :

; Préfixe à ajouter au sujet des mails
debugSubjectPrefix = "[DEMO] "

; Phrase précédent la liste des en-têtes originaux insérés dans le corp du mail
debugBodyIntroduction = "This is a mail from test. Here are real headers: "

; Type de destinataires à forcer
; 1: uniquement les adresses indiquées dans debugReceivers
; 2: uniquement l'utilisateur courant si il a un email, ou à debugReceivers si il
;    n'est pas authentifié
; 3: les deux, adresses de debugReceivers et adresse de l'utilisateur courant
debugReceiversType = 3

; Les destinataires suivants à qui sont envoyés les mails (direct ou en copie),
; reçevront leurs emails et ne seront donc pas remplacé par ceux de debugReceivers
debugReceiversWhiteList[] = john@foo.local

Vous pouvez aussi débugger la communication SMTP. Utilisez le paramètre de configuration debugSmtpLevel pour indiquer ce que vous voulez voir dans les logs de l'application :

• 0: Pas de débuggage
• 1: Commandes SMTP
• 2: Données et commandes
• 3: Données, commandes et état de connection
• 4: données bas-niveau