Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Email processing: Difference between revisions

From MoodleDocs
(→‎Sending mail from Moodle: from string format in 3.2.1 (MDL-57293))
No edit summary
Line 1: Line 1:
{{Moodle 2.5}}
{{Moodle 2.5}}
This page is very out of date, the whole system has been rewritten and docs are here:
https://docs.moodle.org/311/en/Mail_configuration#Incoming_mail_configuration
== Features ==
== Features ==
Moodle is capable of using an e-mail technique known as VERP (Variable Envelope Return Path) in order to disable e-mail for bouncing e-mail addresses. This is particularly useful on busy sites where you may generate huge volumes of e-mail, where you do not control user e-mail addresses, or where users are created with false e-mail addresses (for example in Primary education).
Moodle is capable of using an e-mail technique known as VERP (Variable Envelope Return Path) in order to disable e-mail for bouncing e-mail addresses. This is particularly useful on busy sites where you may generate huge volumes of e-mail, where you do not control user e-mail addresses, or where users are created with false e-mail addresses (for example in Primary education).
Line 8: Line 13:
* handles receiving of e-mails sent to the Moodle noreply address ($CFG->noreplyaddress);
* handles receiving of e-mails sent to the Moodle noreply address ($CFG->noreplyaddress);
* handles receiving of bounce e-mails validating using the MD5 hash and validating against the site HMAC.
* handles receiving of bounce e-mails validating using the MD5 hash and validating against the site HMAC.
== Moodle configuration ==
== Moodle configuration ==
Edit config.php to enable bounce handling, and setup Moodle to match your MTA configuration. A full description of these configuraiton settings can be found in config-dist.php. You will need to uncomment the following lines:
Edit config.php to enable bounce handling, and setup Moodle to match your MTA configuration. A full description of these configuraiton settings can be found in config-dist.php. You will need to uncomment the following lines:
   // once handlebounces is true, we will be using VERP for the return address of every sent email
   // once handlebounces is true, we will be using VERP for the return address of every sent email
   $CFG->handlebounces = true;
   $CFG->handlebounces = true;
Line 24: Line 27:
   // Domain which acccepts email for processing
   // Domain which acccepts email for processing
   $CFG->maildomain = 'bounces.my.domain';
   $CFG->maildomain = 'bounces.my.domain';
Edit the $CFG->maildomain line and one of the $CFG->mailprefix lines (the one that matches your MTA).
Edit the $CFG->maildomain line and one of the $CFG->mailprefix lines (the one that matches your MTA).


Line 30: Line 32:


Edit the process_email.php script to point to the location of your php binary. It will usually be ''/usr/bin/php''.
Edit the process_email.php script to point to the location of your php binary. It will usually be ''/usr/bin/php''.
== Setup under Postfix ==
== Setup under Postfix ==
Add a line to your aliases file. The line should list a 3-letter prefix, to which we'll add a '|', and the path of the script. For example for a prefix of 'mdl' and moodle installed under /var/www/moodle we have in aliases:
Add a line to your aliases file. The line should list a 3-letter prefix, to which we'll add a '|', and the path of the script. For example for a prefix of 'mdl' and moodle installed under /var/www/moodle we have in aliases:
     mdl:    |/var/www/moodle/admin/process_email.php
     mdl:    |/var/www/moodle/admin/process_email.php
     noreply: |/var/www/moodle/admin/process_email.php
     noreply: |/var/www/moodle/admin/process_email.php
If you are using virtualdomains, consult your server administrator for the correct configuration. It probably involves editing transports and mapping your address to a "pipe" transport. One such transport can be configured using the following line in "master.cf":
If you are using virtualdomains, consult your server administrator for the correct configuration. It probably involves editing transports and mapping your address to a "pipe" transport. One such transport can be configured using the following line in "master.cf":
   moodle  unix  -      n      n      -      -      pipe
   moodle  unix  -      n      n      -      -      pipe
       flags=FR user=www-data argv=/usr/bin/env SENDER=${sender} RECIPIENT=${recipient} /srv/www/moodle/admin/process_email.php
       flags=FR user=www-data argv=/usr/bin/env SENDER=${sender} RECIPIENT=${recipient} /srv/www/moodle/admin/process_email.php
Because process_email.php uses environment variables to get recipient and sender adresses, you also need to make sure the $_ENV variable is available within PHP, otherwise Moodle will not process any messages. See : http://www.php.net/manual/en/reserved.variables.environment.php#98113
Because process_email.php uses environment variables to get recipient and sender adresses, you also need to make sure the $_ENV variable is available within PHP, otherwise Moodle will not process any messages. See : http://www.php.net/manual/en/reserved.variables.environment.php#98113
== Setup under Qmail ==
== Setup under Qmail ==
Depending on your setup, your aliases will be controlled by one or more of
Depending on your setup, your aliases will be controlled by one or more of
* ''/etc/aliases''
* ''/etc/aliases''
* ''/var/qmail/alias/.qmail-PREFIX''
* ''/var/qmail/alias/.qmail-PREFIX''
If you edit /etc/aliases add a line like this (for a prefix of 'mdl'):
If you edit /etc/aliases add a line like this (for a prefix of 'mdl'):
     mdl:    |/var/www/moodle/admin/process_email.php
     mdl:    |/var/www/moodle/admin/process_email.php
     noreply: |/var/www/moodle/admin/process_email.php
     noreply: |/var/www/moodle/admin/process_email.php
If you create /var/qmail/alias/.qmail-PREFIX, just do
If you create /var/qmail/alias/.qmail-PREFIX, just do
   echo "|/var/www/moodle/admin/process_email.php" > /var/qmail/alias/.qmail-mdl
   echo "|/var/www/moodle/admin/process_email.php" > /var/qmail/alias/.qmail-mdl
   echo "|/var/www/moodle/admin/process_email.php" > /var/qmail/alias/.qmail-noreply
   echo "|/var/www/moodle/admin/process_email.php" > /var/qmail/alias/.qmail-noreply
To this three letter prefix, we will add a '-' when sending and receiving messages. For more info, check out the manpage for dot-qmail.
To this three letter prefix, we will add a '-' when sending and receiving messages. For more info, check out the manpage for dot-qmail.
== Setup under Exim ==
== Setup under Exim ==
Open ''/etc/exim/exim.conf'' and add to trusted_users the user Apache and cron.php run as (usually "www-data" or "nobody").
Open ''/etc/exim/exim.conf'' and add to trusted_users the user Apache and cron.php run as (usually "www-data" or "nobody").


Add a line to your aliases file. The line should list a 3-letter prefix, to which we'll add a '+', and the path of the script. For example for a prefix of 'mdl' we have in aliases:
Add a line to your aliases file. The line should list a 3-letter prefix, to which we'll add a '+', and the path of the script. For example for a prefix of 'mdl' we have in aliases:
     mdl:    |/var/www/moodle/admin/process_email.php
     mdl:    |/var/www/moodle/admin/process_email.php
     noreply: |/var/www/moodle/admin/process_email.php
     noreply: |/var/www/moodle/admin/process_email.php
If you are using virtualdomains, consult your server administrator for the correct configuration. It probably involves editing transports and mapping your address to a "pipe" transport.
If you are using virtualdomains, consult your server administrator for the correct configuration. It probably involves editing transports and mapping your address to a "pipe" transport.


Line 82: Line 66:
{{Moodle 3.2}}
{{Moodle 3.2}}
== Sending mail from Moodle ==
== Sending mail from Moodle ==
When sending email in your code use email_to_user(). This function is located in lib/moodlelib.php. The function email_to_user() takes standard arguments, but the "From" header sent can be changed in the function from a combination of settings. These are detailed as follows.
When sending email in your code use email_to_user(). This function is located in lib/moodlelib.php. The function email_to_user() takes standard arguments, but the "From" header sent can be changed in the function from a combination of settings. These are detailed as follows.
* If the following is true then the actual senders email address will be used. If not then the no-reply address will be used instead:
* If the following is true then the actual senders email address will be used. If not then the no-reply address will be used instead:

Revision as of 22:57, 20 September 2021

Moodle 2.5


This page is very out of date, the whole system has been rewritten and docs are here:

https://docs.moodle.org/311/en/Mail_configuration#Incoming_mail_configuration

Features

Moodle is capable of using an e-mail technique known as VERP (Variable Envelope Return Path) in order to disable e-mail for bouncing e-mail addresses. This is particularly useful on busy sites where you may generate huge volumes of e-mail, where you do not control user e-mail addresses, or where users are created with false e-mail addresses (for example in Primary education).

The Moodle VERP system:

  • works on most modern Mail Transfer Agents such as Postfix, Qmail, and exim (at least MTAs on Unix systems);
  • generates a processing e-mail address with HMAC (Hashed Message Authentication Code) and validation hash;
  • handles receiving of e-mails sent to the Moodle noreply address ($CFG->noreplyaddress);
  • handles receiving of bounce e-mails validating using the MD5 hash and validating against the site HMAC.

Moodle configuration

Edit config.php to enable bounce handling, and setup Moodle to match your MTA configuration. A full description of these configuraiton settings can be found in config-dist.php. You will need to uncomment the following lines:

 // once handlebounces is true, we will be using VERP for the return address of every sent email
 $CFG->handlebounces = true;
 // minimum bounces allowed per user
 $CFG->minbounces = 10;
 // ratio of bad emails to sent emails
 // if we get more than 20% bounces 
 // for a given user, his/her email is marked bad
 $CFG->bounceratio = .20;
 // Prefix to identify your site MUST BE EXACTLY 3 characters
 $CFG->mailprefix = 'mdl';
 // Domain which acccepts email for processing
 $CFG->maildomain = 'bounces.my.domain';

Edit the $CFG->maildomain line and one of the $CFG->mailprefix lines (the one that matches your MTA).

Make sure your server has a command-line PHP interpreter, and that it is able to connect to mysql (or postgres if relevant). If you are able to run cron.php from the commandline or from crontab, this means PHP is ok.

Edit the process_email.php script to point to the location of your php binary. It will usually be /usr/bin/php.

Setup under Postfix

Add a line to your aliases file. The line should list a 3-letter prefix, to which we'll add a '|', and the path of the script. For example for a prefix of 'mdl' and moodle installed under /var/www/moodle we have in aliases:

   mdl:     |/var/www/moodle/admin/process_email.php
   noreply: |/var/www/moodle/admin/process_email.php

If you are using virtualdomains, consult your server administrator for the correct configuration. It probably involves editing transports and mapping your address to a "pipe" transport. One such transport can be configured using the following line in "master.cf":

  moodle  unix  -       n       n       -       -       pipe
     flags=FR user=www-data argv=/usr/bin/env SENDER=${sender} RECIPIENT=${recipient} /srv/www/moodle/admin/process_email.php

Because process_email.php uses environment variables to get recipient and sender adresses, you also need to make sure the $_ENV variable is available within PHP, otherwise Moodle will not process any messages. See : http://www.php.net/manual/en/reserved.variables.environment.php#98113

Setup under Qmail

Depending on your setup, your aliases will be controlled by one or more of

  • /etc/aliases
  • /var/qmail/alias/.qmail-PREFIX

If you edit /etc/aliases add a line like this (for a prefix of 'mdl'):

   mdl:     |/var/www/moodle/admin/process_email.php
   noreply: |/var/www/moodle/admin/process_email.php

If you create /var/qmail/alias/.qmail-PREFIX, just do

 echo "|/var/www/moodle/admin/process_email.php" > /var/qmail/alias/.qmail-mdl
 echo "|/var/www/moodle/admin/process_email.php" > /var/qmail/alias/.qmail-noreply

To this three letter prefix, we will add a '-' when sending and receiving messages. For more info, check out the manpage for dot-qmail.

Setup under Exim

Open /etc/exim/exim.conf and add to trusted_users the user Apache and cron.php run as (usually "www-data" or "nobody").

Add a line to your aliases file. The line should list a 3-letter prefix, to which we'll add a '+', and the path of the script. For example for a prefix of 'mdl' we have in aliases:

   mdl:     |/var/www/moodle/admin/process_email.php
   noreply: |/var/www/moodle/admin/process_email.php

If you are using virtualdomains, consult your server administrator for the correct configuration. It probably involves editing transports and mapping your address to a "pipe" transport.

More documentation about Exim can be found here.

You will probably have to tell Exim not to lowercase the local-part in your exim configuration. This can be done in the router which handles the mail for your aliases file with: caseful_local_part = true

Moodle 3.2

Sending mail from Moodle

When sending email in your code use email_to_user(). This function is located in lib/moodlelib.php. The function email_to_user() takes standard arguments, but the "From" header sent can be changed in the function from a combination of settings. These are detailed as follows.

  • If the following is true then the actual senders email address will be used. If not then the no-reply address will be used instead:
    • If the $usetrueaddress is set to true in the parameters to email_to_user()
    • - and the setting $CFG->allowedemaildomains is not empty
    • - and The "From" email address is in the list of $CFG->allowedemaildomains
    • - and either the sender has a personal setting (maildisplay in the user table) of showing their email address to everyone, or they have a personal setting showing their email to course members only and the recipient is in a course with the sender.
  • The "From" string will also be altered by the $CFG->emailfromvia setting. Email sent with the "via" setting active will have a "From" string with the following format: {User's name} via {site shortname} {email address}.