Browse files

doc: Add section on e-mail receiving

  • Loading branch information...
1 parent b0e7305 commit 495edd5eed9f6faf661c1cee746b2204a833cf77 @arjan arjan committed Oct 13, 2012
Showing with 111 additions and 36 deletions.
  1. +3 −3 doc/glossary.rst
  2. +108 −33 doc/manuals/email.rst
View
6 doc/glossary.rst
@@ -22,7 +22,7 @@ Glossary
See also the section on :ref:`manual-actions` in the templates manual.
Tag
- The template systems provides tags which function as simple programming constructs. For instance, the if tag can be used for boolean tests and the for tag allows looping. The zotonic templating system compiles the tags found in a template to Erlang byte code which will be called when the template is rendered. This is very efficient.
+ The template systems provides tags which function as simple programming constructs. For instance, the if tag can be used for boolean tests and the for tag allows looping. The Zotonic templating system compiles the tags found in a template to Erlang byte code which will be called when the template is rendered. This is very efficient.
Scomp
A scomp (from .Screen COMPonent.) is a custom template tag, implemented by an Erlang module named after the scomp name, prefixed with `scomp_`. Scomps usually generate HTML. Zotonic modules can implement their own scomp in the module.s scomps/ folder.
@@ -89,10 +89,10 @@ Glossary
There are two kinds of translations. Texts in the templates and Erlang modules; and translations of resources. Templates and Erlang modules are translated using gettext. Resources are translated in the admin, any resource can have an arbitrary number of translations. Zotonic selects the shown language based on the preferred language of the visitor and the available languages of a resource.
Zotonic module
- A zotonic module (just .module., for short) is a collection of related functionality like scomps, filters, dispatch rules, controllers, templates, etc. Zotonic modules are located in folders under the modules/ directory and, by convention, are prefixed with `mod_`.
+ A Zotonic module (just .module., for short) is a collection of related functionality like scomps, filters, dispatch rules, controllers, templates, etc. Zotonic modules are located in folders under the modules/ directory and, by convention, are prefixed with `mod_`.
Zotonic site
- A zotonic site is a collection of scomps, filters, dispatch rules for one website. It is a special kind of zotonic module with has its own config file which allows one to set the hostname, admin password, database connection parameters. It often has a set of site specific modules. The config file contains site wide settings. Zotonic uses the settings to start the site on the right port and connect it to the right database. A zotonic system can run multiple sites.
+ A Zotonic site is a collection of scomps, filters, dispatch rules for one website. It is a special kind of Zotonic module with has its own config file which allows one to set the hostname, admin password, database connection parameters. It often has a set of site specific modules. The config file contains site wide settings. Zotonic uses the settings to start the site on the right port and connect it to the right database. A Zotonic system can run multiple sites.
Erlang module
Not to be confused with a Zotonic module, an Erlang module is a single .erl file which contains Erlang functions.
View
141 doc/manuals/email.rst
@@ -1,7 +1,10 @@
.. _manual-email:
-E-mail configuration
-====================
+E-mail handling
+===============
+
+Configuration
+-------------
Any Zotonic system is capable of sending and receiving e-mail messages
over SMTP.
@@ -12,14 +15,14 @@ to one or more recipients.
Out of the box, e-mail sending should "just work".
Feedback
---------
+........
If you need feedback on messages that have been sent, enable
:ref:`mod_logging` which provides an overview of sent/received and
bounced messages.
Site-specific settings
-----------------------
+......................
+----------+--------------+-----------------------------------------+
|Module |Key |Value |
@@ -29,7 +32,7 @@ Site-specific settings
| | |like noreply@yoursite.com. |
+----------+--------------+-----------------------------------------+
|site |email_override|If set, all e-mail messages that get sent|
-| | |from zotonic will arrive at this |
+| | |from Zotonic will arrive at this |
| | |address. Usefull if you are testing but |
| | |don't want to confuse other people with |
| | |your test e-mails. |
@@ -40,14 +43,20 @@ Site-specific settings
| | |handshake. Defaults to the site's |
| | |hostname, but can be overriden |
+----------+--------------+-----------------------------------------+
-|zotonic |admin_email |E-mail address of the admin user, the |
+|site |admin_email |E-mail address of the admin user, the |
| | |address where admin log/debug messages |
| | |get sent to when using |
| | |``z_email:send_admin/3``. |
+----------+--------------+-----------------------------------------+
+The ``z_email:send_admin/3`` command actually looks in three different
+places for determining the admin e-mail address: the config key
+``zotonic.admin_email``, then the ``site.admin_email`` key, and
+finally the `email` property of the admin user (user with id 1).
+
+
Zotonic-wide settings
----------------------
+.....................
The file ``priv/config`` can be configured to hold any of the
configuration options below. They are in effect for every site running
@@ -97,31 +106,8 @@ in the Zotonic instance.
+------------------+--------------------------------------+
-Sending E-mail
---------------
-
-Once configured, you can use the following Erlang commands to send
-e-mail from Zotonic code:
-
-+-------------------------+--------------------------------------------------+
-|Command |Explanation |
-+=========================+==================================================+
-|``z_email:send_admin/3`` |Sends a quick e-mail to the site |
-| |administrator. Handy to notice the site admin that|
-| |something is wrong, a job has finished, etc... The|
-| |e-mail that is used is the admin_email address |
-| |that is specified in the site's config file. |
-+-------------------------+--------------------------------------------------+
-|``z_email:send/4`` |Sends a text message with a subject to a specified|
-| |recipient. |
-+-------------------------+--------------------------------------------------+
-|``z_email:send_render/4``|Renders a template and sends it as a HTML message |
-| |to a specified recipient. |
-+-------------------------+--------------------------------------------------+
-
-
The sender’s domain
--------------------
+...................
Recipients of e-mail want a valid sender’s address on the
envelope. This section describes how to set your e-mail bounce/sender
@@ -145,7 +131,7 @@ before the ``@`` is generated by Zotonic and is used for identifying
the original message and recipient when the message bounces.
How does Zotonic know the domain?
-.................................
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It checks in order:
@@ -157,8 +143,97 @@ The part before the ``@`` is generated by Zotonic itself, for
administration and detection of bounces. A typical sender address on
the envelope looks like: ``noreply+mlcm6godbz2cchtgdvom@example.org``
+
+Sending E-mail
+--------------
+
+Once configured, you can use the following Erlang commands to send
+e-mail from Zotonic code:
+
++-------------------------+--------------------------------------------------+
+|Command |Explanation |
++=========================+==================================================+
+|``z_email:send_admin/3`` |Sends a quick e-mail to the site |
+| |administrator. Handy to notice the site admin that|
+| |something is wrong, a job has finished, etc... The|
+| |e-mail that is used is the admin_email address |
+| |that is specified in the site's config file. |
++-------------------------+--------------------------------------------------+
+|``z_email:send/4`` |Sends a text message with a subject to a specified|
+| |recipient. |
++-------------------------+--------------------------------------------------+
+|``z_email:send_render/4``|Renders a template and sends it as a HTML message |
+| |to a specified recipient. |
++-------------------------+--------------------------------------------------+
+
+
+Receiving E-mail
+----------------
+
+In its default configuration, Zotonic starts an SMTP server on port
+2525 for receiving e-mail messages. You can write your own code to
+decide what happens when somebody sends e-mail to the system, by
+implementing the ``email_received`` notification (see below).
+
+The SMTP server is also used to receive bounce messages from other
+servers, when sending of a message has failed. :ref:`mod_mailinglist`
+uses this functionality to automatically deactivate invalid e-mail
+addresses.
+
+Configuring incoming E-mail
+...........................
+
+To send messages to Zotonic, the domain part of the e-mail address
+should have an A or MX record which points to the server where Zotonic
+is able to receive on port 25. This means that you have to add a
+firewall rule to redirect port 25 to 2525.
+
+If you were to set up e-mail receiving for a site called
+``example.com``, you could test if this is working by using the `netcat`
+program, like this::
+
+ nc example.com 25
+
+Then, you should be greeted by Zotonic in the following way::
+
+ 220 example.com ESMTP Zotonic 0.9.0
+
+Press ctrl-c to exit.
+
+Handling incoming E-mail
+........................
+
+When receiving an e-mail message, Zotonic looks at the domain part of
+the e-mail address to determine which :term:`Zotonic site` is
+configured to handle this message. It looks at the ``host`` and
+``hostalias`` fields in the site's config file to match the recipient
+domain.
+
+When no site matches the e-mails domain, the message is dropped, and a
+warning logged.
+
+For handling incoming messages in your site, you need a hook in your
+site module to do something with the received messages, implementing
+the ``email_receive`` notification.
+
+.. highlight:: erlang
+
+The code in your module looks like this::
+
+ observe_email_received(E, _C) ->
+ lager:warning("Email from: ~p: ~p", [E#email_received.from,
+ E#email_received.email#email.subject]),
+ ok.
+
+Export this function and then restart your site. Now, send an e-mail
+message to any address ``@example.com``, and notice that it arrives in
+Zotonic::
+
+ (zotonic001@host.local)9> 20:57:54.174 [warning] Email from: <<"arjan@miraclethings.nl">>: <<"Hello!">>
+
+
Troubleshooting
-...............
+---------------
Check in the admin the log and smtp log. When a message bounces back
to the Zotonic SMTP server, you will see errors there. A typical error

0 comments on commit 495edd5

Please sign in to comment.