Chicago Boss provides API functions for sending and receiving emails. No SMTP configuration or server is necessary.

Sending a simple email

The easiest way to send a message is:

If you want to treat Body as an io_lib format string and pass in arguments, use this format:

If you need to customize the email headers or wish to generate emails from Django templates, read on.

Sending email with templates

If the simple method doesn't meet your needs, Chicago Boss provides a way to send email using controllers and views.

Mail controller logic should go into src/mail/my_application_outgoing_mail_controller.erl in your project directory, and templates should go into src/mail/view/. To send an email from a web controller, call:

    boss_mail:send_template(my_application, foo_message, [Arg1, Arg2, ...])
    boss_mail:send_template(my_application, foo_message, [Arg1, Arg2, ...], fun Callback/1)

That will invoke outgoing_mail_controller:foo_message(Arg1, Arg2, ...) and use the return value to populate the templates src/mail/view/foo_message.txt and src/mail/view/foo_message.html, then send the email in a background process. If Callback is provided, the return value from the email delivery will be passed to it, either {ok, Receipt} or {error, Reason}.

Your mail controller function should return:

    {ok, FromAddress, ToAddress, HeaderFields} |
    {ok, FromAddress, ToAddress, HeaderFields, Variables} |
    {ok, FromAddress, ToAddress, HeaderFields, Variables, Options} |
    nevermind

If the return value is nevermind, no email will be sent. Otherwise,

• FromAddress is the sender's email address. The address should not be in "friendly" form, i.e. "foo@example.com" is OK, but "Kai Foo <foo@example.com>" is not.

• ToAddress is recipient's email address.

• HeaderFields is a proplist of email header fields, e.g. [{"From", "SECRETARY TO CHARLES TAYLOR <mo@hotmail.com>"}, {"Subject", "Unclaimed Lottery Winnings"}]. If you want the From: and To: fields to appear in the message, you need to provide values here; they will not be taken from FromAddress and ToAddress. However, the header fields for Message-ID: and Date: will be populated automatically if not provided.

• Variables (if present) will be passed to the associated Django template(s), which will form the body of the message.

• Options (if present) is a proplist of additional options, possibly containing:

  • attachments - a list of tuples representing email attachments. Each attachment should consist of: {FileName, MimeType, Contents}. In this case FileName simply refers to how the file will be named in the email (and is not necessarily a file on the local file system). The file's Contents should be an io_list.

  • template - a string with the name of another template to use for rendering (assuming you don't want the default template, which is just the same as the function name).

  • charset - specify which character set to use for the outgoing email (see Specifying character set).

Formatting. If templates ending only in ".txt" are present, the message will be sent in plain-text; if templates ending only in ".html" are present, the message will be sent as HTML; but if both ".txt" and ".html" templates are present, the message will be sent as a a MIME multi-part message with alternative plain-text and HTML representations.

I18n. To use Chicago Boss's i18n machinery in emails, specify the desired language in the "Content-Language" header field returned from the mail controller.

Receiving email

To receive email, you must first enable the SMTP server in your configuration. You can then define endpoints in src/mail/my_application_incoming_mail_controller.erl. Each function should take two arguments:

• The address that the email is from
• A parsed version of the email

The return value is ignored.

To implement authentication for incoming email, simply define an authorize_/3 function in your incoming mail controller. It should take three arguments:

• The user name of the sender
• The domain name of the sender
• The IP address of the sender

The authorize_/3 function should return true if the user should be permitted to send email to the controller, or false otherwise.

Specifying character set

To specify the character set of the outgoing email, provide the option {charset, <CHARSET>} in the options part of the return value from the controller function, example:

my_function(FromAddress, ToAddress) ->
    {
      ok,
      FromAddress,
      ToAddress,
      [
       {"Subject", "My amazing UTF-8 email!"}
      ],
      [{template_parameter, template_parameter_value()}],
      [{charset, "utf-8"}]
    }.