Piwigo integrates a powerful mailing function compatible with standard PHP mail() function and SMTP servers. It is base on PHPMailer and Emogrifier libraries.

There are four functions to send emails:

• pwg_mail() - the main one
• pwg_mail_admins() - to send emails to all admins
• pwg_mail_groups() - to send emails to a specific group
• pwg_mail_notification_admins() - dedicated to administrative emails

pwg_mail() takes three parameters, for basic usage you only need to use the first and the second one.

The first parameter is the recipient(s) of the mail, it can be either:

• a single email: name@domain.com
• a single email with associated name: Name <name@ domain.com>
• a comma separated list of emails (with or without associated names)
• a hashmap containing email and name keys:

array(
  'name' => 'Name',
  'email' => 'name@domain.com',
  )

• an array of hashmaps containing email and name keys

The second parameter is an array of options:

• from - sender of the email [defaults to webmaster email and gallery name]
• Cc - carbon copy recipients as array [defaults to empty]
• Bcc - blind carbon copy recipients as array [defaults to empty]
• subject - subject of the email [defaults to 'Piwigo']
• content - content of the email
• content_format - text/html or text/plain [defaults to 'text/plain']
• email_format - text/html or text/plain [defaults to 'text/html'] will be forced to 'text/plain' if webmaster disabled HTML emails
• theme - clear or dark [defaults to $conf['mail_theme']]
• mail_title - main title in email corpus [defaults to $conf['gallery_title']]
• mail_subtitle - subtitle in email corpus [defaults to subject]]

If you set subject to [something] something else and leave mail_title and mail_subtitle empty, you will get:
mail_title = something
mail_subtitle = something else
This is for backward compatibility only.

include_once(PHPWG_ROOT_PATH . 'include/functions_mail.inc.php');
 
pwg_mail(
  array(
    'name' => 'Username',
    'email' => 'name@domain.com',
    ),
  array(
    'content' => $content
    'content_format' => 'text/plain',
    'subject' => 'Sample mail',
    )
  );

Instead of providing the content parameter you can use the third parameter of pwg_mail() which allows you to manipulate the mail template. Options are:

• filename - name of .tpl file to use
• dirname - path to your template directory
• assign - array of variables to pass to the template

Each mail template file must be available in both text/plain and text/html formats and you must respect the following files hierarchy:

some/template/directory
    +-- text
        |-- html
        |   |-- a-template-file.tpl
        |   +-- another-template-file.tpl
        +-- plain
            |-- a-template-file.tpl
            +-- another-template-file.tpl

In this configuration:
filename = a-template-file
dirname = some/template/directory

include_once(PHPWG_ROOT_PATH . 'include/functions_mail.inc.php');
 
pwg_mail(
  array(
    'name' => 'Username',
    'email' => 'name@domain.com',
    ),
  array(
    'subject' => 'Sample mail',
    ),
  array(
    'filename' => 'a-template-file',
    'dirname' => PHPWG_ROOT_PATH . 'some/template/directory',
    'assign' => array(
      'USERNAME' => $user['username'],
      'MY_VAR' => 1234,
      ),
    )
  );

Note: If you use the template system AND provide a content it will be available on the {$CONTENT} template variable (after converting line-breaks and links if content_type='text/plain').

From Piwigo 2.6 it is possible to apply prefilters on emails template. One does have to know that emails do not use the same instance of the Template class as the rest of Piwigo, and theses instances are cached (if multiple pwg_mail() are called in the same script).
We added a new trigger before_parse_mail_template in order to access theses instances. Usually there are two instances, one for text/plain and one for text/html, but if the language is changed with switch_lang_to() there will be more.

Here is an example of how to change the contact link in the footer of the email:

add_event_handler('before_parse_mail_template', 'my_mail_template', EVENT_HANDLER_PRIORITY_NEUTRAL, 2);
 
function my_mail_template($cache_key, $content_type)
{
  global $conf_mail;
 
  $template = &$conf_mail[$cache_key]['theme'];
 
  if ($content_type == 'text/html')
  {
    $template->set_prefilter('mail_footer', 'my_mail_template_prefilter_html');
  }
  else
  {
    $template->set_prefilter('mail_footer', 'my_mail_template_prefilter_plain');
  }
}
 
function my_mail_template_prefilter_html($content)
{
  return str_replace(
    'mailto:{$CONTACT_MAIL}?subject={\'A comment on your site\'|translate|escape:url}',
    'http://new-url-to-contact-page',
    $content
    );
}
 
function my_mail_template_prefilter_plain($content)
{
  return str_replace(
    '{$CONTACT_MAIL}',
    'http://new-url-to-contact-page',
    $content
    );
}

Note that you may have to use two different prefilters for HTML and plain text.

You can apply these prefilters on:

• mail_header
• mail_footer
• css
• (any template file provided with the third parameter of pwg_mail())

pwg_mail_admins() parameters are exactly the same as pwg_mail() except the first one which is not present.

Likewise, pwg_mail_group() parameters are the same except the first one which is the group identifier.

pwg_mail_notification_admins() takes three parameters:

• subject - string or array of get_l10n_args()
• content - string or array of get_l10n_args()
• send_technical_details - set it true to include user IP and UserAgent in the mail

Some little functions may be useful too:

• get_str_email_format
• switch_lang_to
• switch_lang_back
• set_make_full_url
• unset_make_full_url