Update doc of 'tools/notify_quarantined_recipients.py' shipped in iRedAdmin-Pro.

This commit is contained in:
Zhang Huangbin 2017-02-14 22:04:26 +08:00
parent ed009b26ca
commit d34b83f7a4
2 changed files with 108 additions and 36 deletions

View File

@ -104,41 +104,70 @@ Screenshots attached at the bottom.
### Notify users about quarantined mails
!!! note
This feature requires you to enable self-service for mail domain -- you can
enable it in domain profile page.
iRedAdmin-Pro ships script `tools/notify_quarantined_recipients.py` to notify
users which have email quarantined in SQL database.
iRedAdmin-Pro ships a script you can run to notify users about quarantined
mails: `tools/notify_quarantined_recipients.py`.
Default notification email contains basic info of each quarantined email:
The notification email is read from template file
`tools/notify_quarantined_recipients.html`, you're free to modify it to match
your needs. (don't forget to backup it before upgrading iRedAdmin-Pro.)
* mail subject
* sender
* recipient
* spam level (score)
* mail arrived time
The notification email will show the link of iRedAdmin-Pro so that users can
click it and login to manage quarantined mails. You must change the URL by
adding below parameter with proper URL in iRedAdmin-Pro config file:
The notification email message is read from (HTML) template file
`tools/notify_quarantined_recipients.html`, if you want to modify it, please
copy it to `tools/notify_quarantined_recipients.local.html` then modify it.
During upgrading iRedAdmin-Pro, this custom file will be copied to
new iRedAdmin-Pro directory, so you won't lose your customization.
Several parameters are required by this script in iRedAdmin-Pro config file:
```
NOTIFICATION_IREDADMIN_URL = 'https://[your_server]/iredadmin/'
# SMTP server address, port, username, password used to send notification mail.
NOTIFICATION_SMTP_SERVER = 'localhost'
NOTIFICATION_SMTP_PORT = 587
NOTIFICATION_SMTP_STARTTLS = True
NOTIFICATION_SMTP_USER = 'no-reply@localhost.local'
NOTIFICATION_SMTP_PASSWORD = ''
NOTIFICATION_SMTP_DEBUG_LEVEL = 0
# URL of your iRedAdmin-Pro login page which will be shown in notification
# email, so that user can login to manage quarantined emails.
# Sample: 'https://your_server.com/iredadmin/'
NOTIFICATION_URL_SELF_SERVICE = 'https://[your_server]/iredadmin/'
# Subject of notification email. Available placeholders:
# - %(total)d -- number of quarantined mails in total
NOTIFICATION_QUARANTINE_MAIL_SUBJECT = '[Attention] You have %(total)d emails quarantined and not delivered to mailbox'
```
To notify user, please add a cron job to run
`tools/notify_quarantined_recipients.py`. for example, every 6 hours:
To notify user periodly, please add a cron job for root user to run
`tools/notify_quarantined_recipients.py`. For example, every 6 hours ('6 hours'
is just an example, the period is totally up to you):
```
1 */12 * * * python /path/to/tools/notify_quarantined_recipients.py >/dev/null
1 */6 * * * /usr/bin/python /var/www/iredadmin/tools/notify_quarantined_recipients.py --force-all >/dev/null
```
Don't forget to use the correct path to `notify_quarantined_recipients.py` on your server.
You can also run this script manually to notify users. for example, on RHEL/CentOS:
You can also run this script manually to notify users. for example,
on RHEL/CentOS:
```
cd /var/www/iredadmin/tools/
python notify_quarantined_recipients.py
python notify_quarantined_recipients.py --force-all
```
`notify_quarantined_recipients.py` supports few arguments:
Argument | Comment
---|---
`--force-all` | Send notification to all users which have email quarantined
`--force-all-time` | Notify users for their all quarantined emails instead of just new ones since last notification.
`--notify-backupmx` | Send notification to all recipients under backup mx domain
## Quarantine clean emails
Note: If you just want to quarantine clean emails sent from/to certain local

View File

@ -122,33 +122,76 @@ web server) is required.</p>
or delete them.</p>
<p>Screenshots attached at the bottom.</p>
<h3 id="notify-users-about-quarantined-mails">Notify users about quarantined mails</h3>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This feature requires you to enable self-service for mail domain -- you can
enable it in domain profile page.</p>
</div>
<p>iRedAdmin-Pro ships a script you can run to notify users about quarantined
mails: <code>tools/notify_quarantined_recipients.py</code>.</p>
<p>The notification email is read from template file
<code>tools/notify_quarantined_recipients.html</code>, you're free to modify it to match
your needs. (don't forget to backup it before upgrading iRedAdmin-Pro.)</p>
<p>The notification email will show the link of iRedAdmin-Pro so that users can
click it and login to manage quarantined mails. You must change the URL by
adding below parameter with proper URL in iRedAdmin-Pro config file:</p>
<pre><code>NOTIFICATION_IREDADMIN_URL = 'https://[your_server]/iredadmin/'
<p>iRedAdmin-Pro ships script <code>tools/notify_quarantined_recipients.py</code> to notify
users which have email quarantined in SQL database.</p>
<p>Default notification email contains basic info of each quarantined email:</p>
<ul>
<li>mail subject</li>
<li>sender</li>
<li>recipient</li>
<li>spam level (score)</li>
<li>mail arrived time</li>
</ul>
<p>The notification email message is read from (HTML) template file
<code>tools/notify_quarantined_recipients.html</code>, if you want to modify it, please
copy it to <code>tools/notify_quarantined_recipients.local.html</code> then modify it.
During upgrading iRedAdmin-Pro, this custom file will be copied to
new iRedAdmin-Pro directory, so you won't lose your customization.</p>
<p>Several parameters are required by this script in iRedAdmin-Pro config file:</p>
<pre><code># SMTP server address, port, username, password used to send notification mail.
NOTIFICATION_SMTP_SERVER = 'localhost'
NOTIFICATION_SMTP_PORT = 587
NOTIFICATION_SMTP_STARTTLS = True
NOTIFICATION_SMTP_USER = 'no-reply@localhost.local'
NOTIFICATION_SMTP_PASSWORD = ''
NOTIFICATION_SMTP_DEBUG_LEVEL = 0
# URL of your iRedAdmin-Pro login page which will be shown in notification
# email, so that user can login to manage quarantined emails.
# Sample: 'https://your_server.com/iredadmin/'
NOTIFICATION_URL_SELF_SERVICE = 'https://[your_server]/iredadmin/'
# Subject of notification email. Available placeholders:
# - %(total)d -- number of quarantined mails in total
NOTIFICATION_QUARANTINE_MAIL_SUBJECT = '[Attention] You have %(total)d emails quarantined and not delivered to mailbox'
</code></pre>
<p>To notify user, please add a cron job to run
<code>tools/notify_quarantined_recipients.py</code>. for example, every 6 hours:</p>
<pre><code>1 */12 * * * python /path/to/tools/notify_quarantined_recipients.py &gt;/dev/null
<p>To notify user periodly, please add a cron job for root user to run
<code>tools/notify_quarantined_recipients.py</code>. For example, every 6 hours ('6 hours'
is just an example, the period is totally up to you):</p>
<pre><code>1 */6 * * * /usr/bin/python /var/www/iredadmin/tools/notify_quarantined_recipients.py --force-all &gt;/dev/null
</code></pre>
<p>Don't forget to use the correct path to <code>notify_quarantined_recipients.py</code> on your server.</p>
<p>You can also run this script manually to notify users. for example, on RHEL/CentOS:</p>
<p>You can also run this script manually to notify users. for example,
on RHEL/CentOS:</p>
<pre><code>cd /var/www/iredadmin/tools/
python notify_quarantined_recipients.py
python notify_quarantined_recipients.py --force-all
</code></pre>
<p><code>notify_quarantined_recipients.py</code> supports few arguments:</p>
<table>
<thead>
<tr>
<th>Argument</th>
<th>Comment</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>--force-all</code></td>
<td>Send notification to all users which have email quarantined</td>
</tr>
<tr>
<td><code>--force-all-time</code></td>
<td>Notify users for their all quarantined emails instead of just new ones since last notification.</td>
</tr>
<tr>
<td><code>--notify-backupmx</code></td>
<td>Send notification to all recipients under backup mx domain</td>
</tr>
</tbody>
</table>
<h2 id="quarantine-clean-emails">Quarantine clean emails</h2>
<p>Note: If you just want to quarantine clean emails sent from/to certain local
user, please refer to this document instead: