Hikyaku
Email delivery library for Erlang — composable email builder with swappable adapter backends. The Erlang counterpart to Elixir's Swoosh: build an email once, deliver it through any adapter.
Features
- Builder — functional, chainable email construction with address normalization
- Attachments — from file path, binary data, or inline with content-id
- Mailer — behaviour-based mailer modules with validation on delivery
- Adapters — SMTP, SendGrid, Mailgun, Amazon SES, logger, and test
- Content Types — automatic MIME type detection for attachments
Quick Start
Define a Mailer
-module(my_mailer).
-behaviour(hikyaku_mailer).
-export([config/0, deliver/1]).
config() ->
#{
adapter => hikyaku_adapter_smtp,
relay => <<"smtp.example.com">>,
port => 587,
username => <<"user@example.com">>,
password => <<"secret">>,
tls => always
}.
deliver(Email) ->
hikyaku_mailer:deliver(?MODULE, Email).
Build & Send
Email = hikyaku_email:new(),
Email1 = hikyaku_email:from(Email, {<<"Alice">>, <<"alice@example.com">>}),
Email2 = hikyaku_email:to(Email1, <<"bob@example.com">>),
Email3 = hikyaku_email:subject(Email2, <<"Hello!">>),
Email4 = hikyaku_email:text_body(Email3, <<"Hi Bob">>),
Email5 = hikyaku_email:html_body(Email4, <<"<b>Hi Bob</b>">>),
{ok, _} = my_mailer:deliver(Email5).
Addresses accept a binary (<<"bob@example.com">>), a {Name, Address} tuple, or a #hikyaku_address{} record.
Use to/2, cc/2, bcc/2 to append recipients, or put_to/2, put_cc/2, put_bcc/2 to replace the entire list.
Each address must be a single bare mailbox that gen_smtp can parse (local@domain; plus addressing, IDN domains and quoted local parts such as "a"@b.com are fine), otherwise {invalid_address, address, Address} is raised. Display names containing RFC 5322 specials (such as , or <) are sent as quoted strings; a name with control characters raises {invalid_address, name, Name}, and an empty name counts as no name.
Custom headers are set with header/3. The name must be printable ASCII without : (at most 76 characters) and the value must not contain control characters other than tab, otherwise {invalid_header, Name} is raised. Headers hikyaku derives from other fields (From, To, Cc, Bcc, Reply-To, Subject, Content-Type, MIME-Version, Content-Transfer-Encoding) or that providers set themselves (Received, DKIM-Signature, SendGrid's X-SG-ID and X-SG-EID) raise {reserved_header, Name}.
Attachments
%% From file path (content type auto-detected)
Pdf = hikyaku_attachment:from_path(<<"/tmp/report.pdf">>),
%% From binary data
Csv = hikyaku_attachment:from_data(<<"data.csv">>, CsvBin),
%% Inline image with content-id
Logo = hikyaku_attachment:inline(<<"logo">>, <<"/tmp/logo.png">>),
Email6 = hikyaku_email:attachment(Email5, Pdf),
Email7 = hikyaku_email:attachment(Email6, Logo).
from_path/2 and from_data/3 accept an options map: #{content_type => binary(), filename => binary()}.
The content type must be type/subtype, optionally with ; name=value parameters whose value is a token or a quoted string without control characters (for example text/csv; charset=utf-8; header=present); the filename must not contain control characters, and an inline content id must be printable ASCII without < or >. Anything else raises {invalid_attachment, Field, Value}, both from the builders and from hikyaku_email:attachment/2.
Reading an Email
Each setter has a matching one-argument getter, so a built or delivered email can be read without including the record header:
<<"Hello!">> = hikyaku_email:subject(Email5),
<<"Hi Bob">> = hikyaku_email:text_body(Email5),
[_Bob] = hikyaku_email:to(Email5).
Getters: subject/1, from/1, to/1, cc/1, bcc/1, reply_to/1, text_body/1, html_body/1, attachments/1, headers/1, provider_options/1. Addresses are returned as #hikyaku_address{} records and attachments as #hikyaku_attachment{} records (from hikyaku/include/hikyaku.hrl).
Adapters
| Adapter | Description | Config |
|---|---|---|
hikyaku_adapter_smtp |
SMTP via gen_smtp | relay, port, username, password, ssl, tls, tls_options, no_mx_lookups |
hikyaku_adapter_sendgrid |
SendGrid v3 API | api_key, http_client |
hikyaku_adapter_mailgun |
Mailgun Messages API | api_key, domain, base_url, http_client |
hikyaku_adapter_ses |
Amazon SES v2 API | access_key, secret_key, region, http_client |
hikyaku_adapter_logger |
Logs emails via logger | level |
hikyaku_adapter_test |
Sends to a process | pid |
SMTP
config() ->
#{
adapter => hikyaku_adapter_smtp,
relay => <<"smtp.example.com">>,
port => 587, %% default 587; use 465 with ssl => true
username => <<"user@example.com">>,
password => <<"secret">>,
tls => always %% always | if_available | never
}.
-
tlscontrols STARTTLS. It defaults toalways, so neither credentials nor the message are sent over an unencrypted connection, and a relay that does not offer STARTTLS fails with an error. The exceptions aressl => true(already encrypted) and a loopback relay (localhost,127.0.0.0/8,::1) withoutusername, where it defaults toif_available. -
To send plain SMTP to a relay on a trusted private network that has no STARTTLS, opt out explicitly with
tls => if_available(use STARTTLS when offered, otherwise send in clear) ortls => never(never use STARTTLS):config() -> #{ adapter => hikyaku_adapter_smtp, relay => <<"mailrelay.internal">>, port => 25, tls => if_available %% trusted private network only }.This is a downgrade: anyone on the path can strip STARTTLS and read the session, including the AUTH exchange if
usernameis set. Only use it where the network itself is trusted. -
ssl => trueconnects with implicit TLS (port 465) instead of STARTTLS. -
Every TLS connection, STARTTLS or implicit, verifies the relay certificate against the OS trust store (
public_key:cacerts_get()) and checks that it is valid forrelay, which is also sent as SNI. -
tls_optionsreplaces the default ssl client options, for example to trust a private CA:tls_options => [{verify, verify_peer}, {cacerts, MyCaCerts}]relayis still sent as SNI unless the list setsserver_name_indication, and{depth, 3}is added unless the list setsdepth, so a chain with intermediates verifies. -
no_mx_lookupsdefaults tofalse: as in normal SMTP, the MX records of a domainrelayare looked up and those hosts are dialled if any exist, falling back torelayitself. Setno_mx_lookups => trueto always connect torelaydirectly. MX lookups are always skipped whenrelayis an IP address, or whentls_optionssets{server_name_indication, disable}, because the certificate check then has no name to tell the relay from a host a spoofed MX answer points at. -
Unless the email sets its own
Message-IDheader, one is generated from random bytes and the sender's domain, so the sending host's name does not leak.
SendGrid
config() ->
#{
adapter => hikyaku_adapter_sendgrid,
api_key => <<"SG.xxx">>
}.
Attachments (including inline parts with a content id) and custom headers are sent through the v3 mail/send API. SendGrid does not accept parameters in an attachment type, so only the bare media type (for example text/csv) is sent.
Mailgun
config() ->
#{
adapter => hikyaku_adapter_mailgun,
api_key => <<"key-xxx">>,
domain => <<"mg.example.com">>,
base_url => <<"https://api.eu.mailgun.net">> %% optional, defaults to US region
}.
Amazon SES
config() ->
#{
adapter => hikyaku_adapter_ses,
access_key => <<"AKIA...">>,
secret_key => <<"...">>,
region => <<"us-east-1">>
}.
SES uses the v2 JSON API for simple emails and automatically falls back to raw MIME encoding when attachments or custom headers are present. Authentication uses AWS Signature V4, with no external dependencies beyond OTP crypto.
Testing
-include_lib("eunit/include/eunit.hrl").
-behaviour(hikyaku_mailer).
config() ->
#{adapter => hikyaku_adapter_test, pid => self()}.
send_test() ->
Email = hikyaku_email:to(
hikyaku_email:from(
hikyaku_email:subject(hikyaku_email:new(), <<"Test">>),
<<"sender@test.com">>
),
<<"recipient@test.com">>
),
{ok, _} = hikyaku_mailer:deliver(?MODULE, Email),
receive
{hikyaku_email, Received} ->
?assertEqual(<<"Test">>, hikyaku_email:subject(Received))
after 1000 ->
error(timeout)
end.
Requirements
- Erlang/OTP 27+