The Chicago Boss API is mostly stable, but still might change before 1.0.

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:

boss_mail:send(FromAddress, ToAddress, Subject, Body)

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

boss_mail:send(FromAddress, ToAddress, Subject, BodyFmt, [BodyArgs])

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} |

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

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 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 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) ->
       {"Subject", "My amazing UTF-8 email!"}
      [{template_parameter, template_parameter_value()}],
      [{charset, "utf-8"}]