Quick links: Content - sections - sub sections
EN FR

jMailer is an object to send emails. It is based on the PHPMailer class.

Here are its features:

  • support attachments
  • HTML or TEXT email
  • Multiple recipients
  • Multiple sending channel (mail(), sendmail)
  • SMTP authentication support

You can find many PHPMailer use cases over the web. So, we won't document all of the features.

jMailer brings some additional features, and ease configuration through the main configuration file:

  • default configuration of jMailer is stored in the configuration file of the application
  • you can use jTpl templates to generate your emails content.
  • errors messages are localized in properties files (jLocale)
  • errors are raised and logged through exceptions.

Configuration file

jMailer options shall be edited in var/config/localconfig.ini.php, in a [mailer] section.

Configuration options

  • webmasterEmail: default sender email.
  • webmasterName: default sender name.
  • mailerType: indicates how to send mails (default: "mail")
    • "mail": PHP mail function
    • "sendmail": use the server program
    • "smtp": direct connection to an SMTP host
  • hostname: used in Message-Id and Received headers, and also as default HELO string. If empty, the value returned by $_SERVER['SERVER_NAME'] is used or 'localhost.localdomain'.
  • sendmailPath: path to sendmail program

To send mails with a SMTP server:

  • smtpHost: SMTP hostname
  • smtpPort: SMTP port
  • smtpSecure: secured connection or not (possible value: "", "ssl", "tls")
  • smtpHelo: SMTP Helo message
  • smtpAuth: turn on/off SMTP authentication
  • smtpUsername: SMTP login
  • smtpPassword: SMTP password
  • smtpTimeout: SMTP server time out

Starting Jelix 1.6.17, you can set these parameters into a profile, which is better than into the main configuration. Create a profile into profiles.ini.php and indicate its name into smtpProfile.

The profile:


[smtp:mymailer]
host = localhost
auth_enabled = one
secure_protocol = tls
username = me@foo
password = thepassword
timeout = 20

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

jMailer uses also general parameters locale and charset to setup the language and charset of emails.

Of course, you can change all of these parameters directly with properties and methods of jMailer class. See reference documentation.

Note about the webmasterEmail: If you don't use the smtp mailer, be sure the web server is allowed to send emails with the given Email. Else some mail servers may reject emails sent by your application or mark them as spam. For example, if your web server is public, you should set correcly the DNS SPF record for your domain name. This record should content the IP of your web server. See the configuration manager of your domain name provider.

Sending a simple mail

Sending a text email.


  $mail = new jMailer();

  $mail->Subject = 'Subject';
  $mail->Body = 'Text content';

  $mail->AddAddress('recipientId@exemple.com' , 'recipient name');

  $mail->Send();

Sending a mail using a template

You can use the powerfull template engine of Jelix to send an email. You have to create a template in your module. In this template, you can use meta values to specify your email parameters.

Example, in modules/mymodule/templates/supermail.tpl:


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

    Hello {$name},
    Here is an email generated by jMailer and Jelix.

And in your PHP code :


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

Notice that jMailer will create template variables corresponding to some PHPMailer properties, so you can use it them anywhere in the template


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

    Hello {$name},
    Here is an email generated by jMailer and Jelix.
    This email is send to : 
    {foreach $cc as $person}
      - {$person[0]}
    {/foreach}

Sending an HTML email

You have to call the isHTML method like in this example:


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

An alternative way is to give a template with HTML content, and so you have to indicate true to the method Tpl.


$tpl = $mail->Tpl('mymodule~htmlmail', true);

PHPMailer include the HTML content in the email, but also a plain text version of the content, by removing HTML elements and their attributes, CSS, javascript code. jMailer improves the process by keeping links of the <a> elements, between parenthesis after the label of the link, except if there is a class or an attribute named notexpandlink.

You can provide your own HTML to text converter, by indicating it as the third parameter to Tpl(). It should be a callable type:


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

Your HTML may content some images with the <img> element. If the src attribute is not an URL, then PHPMailer considers it as a file to include into the mail. The path to the image may be a full path. But if it is a relative path, you should indicate the base directory of all images to resolve paths.

In this example, images referred into the HTML are in the www/images/ of the application:


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

Sending an attachment

You can add attachment easily in your email, by giving the path of the file stored somewhere on the hard drive. You can also indicate an other name for the file.


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

Advanced features

Since jMailer inherits from the PHPmailer class, read the API documentation of PHPMailer to know more about its features.

Debug mode

In some environment for tests, like on your computer, you may not want to send emails. Set mailerType to file and all emails generated by jMailer will be stored into files, into your var/mails/ directory.

On a demo server, you may want to send emails, but you want to debug or have more controls on sent emails.

If you want for example to have a copy of all emails into files, set copyToFiles = on in the mailer section.

Starting with Jelix 1.6.17, you can force receivers, so all emails will be send to them instead of receivers indicated to jMailer by the application.

To activate this feature, set debugModeEnabled = on, and list receivers into debugReceivers. Here, all emails will be sent only to Bob and Joe:


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

You have also additionnals features:


; Prefix to add to subject of mails, in debug mode.
debugSubjectPrefix = "[DEMO] "

; Introduction inserted at the beginning of the messages in debug mode
debugBodyIntroduction = "This is a mail from test. Here are real headers: "

; type of receivers set into the email
; 1: only addresses from  debugReceivers
; 2: only email address of the authenticated user, or addresses from  debugReceivers
;    if the user isn't authenticated
; 3: both, addresses from debugReceivers and address of the authenticated user
debugReceiversType = 3

; Receivers for 'To' having these emails will not be replaced by debugReceivers
; Receivers for 'Cc' and 'Bcc' having these emails will not be removed
debugReceiversWhiteList[] = john@foo.local