Name: mailman
Owner: xerions
Description: Mailman provides a clean way of defining mailers in your Elixir applications
Created: 2016-05-13 10:15:06.0
Updated: 2016-05-13 10:15:07.0
Pushed: 2016-05-12 11:44:09.0
Homepage: http://kamilc.github.io/mailman
Size: 202
Language: Elixir
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
Mailman provides a clean way of defining mailers in your Elixir apps. It allows you to send multi-part email messages containing text and html parts. It encodes messages with a proper quoted-printable encoding. It also allows you to send attachments.
To be able to send emails, you only need to provide the SMTP config (like an external SMTP server along with credentials etc.). You also need to define your emails along with text and/or html templates. Mailman uses Eex as a templating language but will likely be extended to provide other choices as well in the future.
fmodule MyApp.Mailer do
def deliver(email) do
Mailman.deliver(email, config)
end
def config do
%Mailman.Context{
config: %Mailman.LocalSmtpConfig{ port: 1234 },
composer: %Mailman.EexComposeConfig{}
}
end
d
somewhere where you start other services in your app:
ilman.LocalServer.start 1234 # just pass the port number you want
somewhere else:
f testing_email do
%Mailman.Email{
subject: "Hello Mailman!",
from: "mailman@elixir.com",
to: [ "testy@tester123456.com" ],
cc: [ "testy2#tester1234.com", "abcd@defd.com" ],
bcc: [ "1234@wsd.com" ],
data: [
name: "Yo"
],
text: "Hello! <%= name %> These are Unicode: q??ó?",
html: """
l>
y>
Hello! <%= name %></b> These are Unicode: q??ó?
dy>
ml>
"""
}
d
And then to actually send an email:
App.Mailer.deliver testing_email
There are two parts in the configuration data for how Mailman works:
The first one specifies how emails will be rendered. The second one, how will they be delivered.
For now, only the %Mailman.EexComposeConfig{} is available for configuring the composer. The library is ready to support any other composer you might want to implement.
There are three adapter configs at the moment: external smtp, local smtp and the testing one. The latter will soon support handling the queue of emails to ease testing of the email sending part of your apps.
You don't access those adapters directly. Instead, you specify a config of your choice and the library does all the rest for you. The three config options corresponding with adapters are: %Mailman.LocalSmtpConfig{}, %Mailman.SmtpConfig{} and %Mailman.TestConfig{}.
lman.Context{
config: %Mailman.LocalSmtpConfig{ port: 1234 },
composer: %Mailman.EexComposeConfig{}
Note that to be able to use the local and the test configs, you'll need to start either local SMTP server or the testing service:
ilman.LocalServer.start(1234)
or:
ilman.TestServer.start
In this example we're setting up the library to use the local SMTP server created along with the app. In order for this to work you still have to create this process:
= Mailman.LocalServer.start(1234)
You can pass context configuration to Mailman using Mix.Config. If you do set config field value in Mailman.Context struct, or if you set it to nil, Mailman expect to read the value from Mix.Config, generally in your config,exs file.
Here is an example mix.exs file snippet for Mailman:
ig :mailman,
lay: "localhost",
rt: 1025,
th: :never
The email struct is defined as:
truct subject: "",
om: "",
: [],
: [],
c: [],
tachments: [], # This has to be %Mailman.Attachment{}. More about attachments below
ta: %{}, # This is the context for EEx. You put here data for your <%= %> placeholders
ml: "", # Actual html template
xt: "", # Actual plain template
livery: nil # If the message was created through parsing of the delivered email - this holds the 'Date' header
A dedicated struct has been created for describing attachments. In this version, there's a function that takes a binary representing a path to a file that's constructing this struct for you. So you can add attachments to your email definitions like this:
chments: [
ilman.Attachment.inline!("test/data/blank.png")
This reads the file from disk, encodes it with base64 and discovers the proper mime-type. Attachments are also properly decoded from existing emails (more on that below).
If you have the source of rendered email as a binary, you can use the Mailman.Email.parse!/1 function to turn it into%Mailman.Email{}.
Here's an example from the test suite:
, message} = MyApp.Mailer.deliver(email_with_attachments)
l = Mailman.Email.parse! message
At this point, if the source contains the 'Date' header (meaning that it was put through a mailing system) ? it will have the 'delivery' field non-empty.
When you use the TestServer you can take a look at the deliveries whith:
ilman.TestServer.deliveries
Also, if you want to clear this list:
ilman.TestServer.clear_deliveries
There's one gotcha currently when using the package with Hex. Because of the dependency on the eiconv library and it's absence in the Hex database, you have to specify it as a dependency on your own in your mix.exs
As an example:
deps do
{:mailman, "~> 0.1.0"},
{:eiconv, github: "zotonic/eiconv"}
This way you'll be able to use the parse! function to parse delivered emails.