Email

Moya has support for sending template emails which allow you to insert personalized information for the recipient.

Email Settings

See the Mailservers for information on how to configure Moya to send emails.

You can test your email settings with the following command:

$ moya email send

Namespace

Email tags use the namespace http://moyaproject.com/email.

Defining Emails

Before sending emails they must first be defined with the <email> tag – typically in a file called email.xml, although this is just a convention. Here's a an example of a very simple email definition:

<moya xmlns="http://moyaproject.com">
    <!-- An example email -->
    <email libname="email.test" subject="Test Email" xmlns="http://moyaproject.com/email">
        <text template="email/test.txt"/>
    </email>
</moya>

The <text> tag tells moya to create a text email with the subject Test Email created from the template email/test.txt. Here's an example email:

Dear Sir/Madam,

This is a test Email!

Love,

Moya

You can attach HTML in the same way with the <html> tag. Here's an example:

<email libname="email.test" subject="Test Email" xmlns="http://moyaproject.com/email">
    <text template="email/test.txt"/>
    <html template="email/test.html"/>
</email>

Here we have attached both text and HTML. Some email clients don't display rich (HTML) emails, so it is a good idea to include a text version as well. However, these days there are few people who can't view HTML emails, so you might consider just going with HTML.

The email tag also has the optional attributes from, cc, bcc and replyto which will set the relevant email headers. These attributes can be overridden when you send the email.

Sending

To send the email, use the <send> tag; the email attribute should be the element reference of the email you want to send, and to should be the recipients email address. Here's how you would send the example email:

<email:send email="#email.text" to="user@example.org" />

The <send> tag has the optional attributes from, subject, cc, bcc, replyto to set the relevant email fields. These override the attributes of the same name on the email definition.

Errors

If the email could not be sent, Moya will throw a email.send-failed exception, unless you set the fail_silently attribute to yes.

Emails can fail to send due to a variety of reasons such as connectivity issues, server isn't running etc. Often your application won't be able to do much more that suggest the user try again. Moya will write an error log to the moya.email logger, to alert you when emails fail to send.

Email Parameters

When you send an email, Moya calls the <email> tag, which allows you to pass in parameters to be used in the template. For instance, lets say we want to render a personalized greeting in our email template. We could edit it as follows:

Dear ${name},

This is a test Email!

Love,

Moya

We can send this email in the usual way, but add a parameter for name which will be substituted in the text template.

<email:send email="#email.text" to="user@example.org" let:name="'John'"/>

Alternatively <send> has a data attributer which you can set to a dictionary containing data to be rendered in the template. Here's the equivalent of the above, using the data attribute

<email:send email="#email.text" to="user@example.org" data="{'name': John'}"/>

Debugging Emails

If you are running the server in debug mode, Moya will display emails in the terminal. This is useful for debugging because you won't have to wait for the email to come through to check your emails.