🌍
English
Differences
This shows you the differences between two versions of the page.
|
dev:send_emails_with_piwigo [2013/11/06 19:25] mistic100 [Basic usage] |
— (current) | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== Send emails with Piwigo ====== | ||
| - | <WRAP center round important 60%> | ||
| - | This page only applies to Piwigo 2.6 and newer. | ||
| - | </WRAP> | ||
| - | |||
| - | ===== Introduction ===== | ||
| - | Piwigo integrates a powerful mailing function compatible with standard PHP **mail()** function and SMTP servers. It is base on [[https://github.com/Synchro/PHPMailer|PHPMailer]] and [[http://www.pelagodesign.com/sidecar/emogrifier/|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 | ||
| - | |||
| - | ===== Basic usage ===== | ||
| - | **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: | ||
| - | <code php>array( | ||
| - | 'name' => 'Name', | ||
| - | 'email' => 'name@domain.com', | ||
| - | )</code> | ||
| - | * 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]] | ||
| - | |||
| - | == About mail_title and mail_subtitle == | ||
| - | 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. | ||
| - | |||
| - | == Example == | ||
| - | <code php> | ||
| - | 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', | ||
| - | ) | ||
| - | ); | ||
| - | </code> | ||
| - | |||
| - | ===== Email with template ===== | ||
| - | 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 | ||
| - | |||
| - | == About filename and dirname == | ||
| - | Each mail template must be available in both //text/plain// and //text/html// formats and you must respect the following files hierarchy: | ||
| - | <code> | ||
| - | some/template/directory | ||
| - | +-- text | ||
| - | |-- html | ||
| - | | |-- a-template-file.tpl | ||
| - | | +-- another-template-file.tpl | ||
| - | +-- plain | ||
| - | |-- a-template-file.tpl | ||
| - | +-- another-template-file.tpl | ||
| - | </code> | ||
| - | |||
| - | In this configuration:\\ | ||
| - | ''filename = a-template-file''\\ | ||
| - | ''dirname = some/template/directory'' | ||
| - | |||
| - | == Example == | ||
| - | <code php> | ||
| - | 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, | ||
| - | ), | ||
| - | ) | ||
| - | ); | ||
| - | </code> | ||
| - | |||
| - | **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'). | ||
| - | |||