Repository navigation
Laravex's mail system is implemented in Laravex.Mail.Mailer. Three mailers are supported: log, array, and smtp. Mailable modules can render Blade templates, Markdown views, or provide a plain string body.
Configure the mailer in config/mail.exs:
%{
"default" => Laravex.Env.get("MAIL_MAILER", "log"),
"mailers" => %{
"log" => %{"transport" => "log"},
"array" => %{"transport" => "array"},
"smtp" => %{
"transport" => "smtp",
"host" => Laravex.Env.get("MAIL_HOST", "127.0.0.1"),
"port" => Laravex.Env.get("MAIL_PORT", 2525),
"username" => Laravex.Env.get("MAIL_USERNAME"),
"password" => Laravex.Env.get("MAIL_PASSWORD"),
"scheme" => Laravex.Env.get("MAIL_SCHEME", "smtp"), # "smtp" | "smtps"
"local_domain" => Laravex.Env.get("MAIL_EHLO_DOMAIN", "localhost")
}
},
"from" => %{
"address" => Laravex.Env.get("MAIL_FROM_ADDRESS", "hello@example.com"),
"name" => Laravex.Env.get("MAIL_FROM_NAME", "Laravex App")
}
}| Mailer | Behaviour |
|---|---|
log |
Writes the full message (to, subject, body, from) to the application log via Laravex.Log.Logger.info/2. |
array |
Stores messages in ETS. Use with Mailer.fake() and Mailer.assert_sent/1 in tests. |
smtp |
Delivers mail over a real SMTP connection via :gen_tcp / :ssl (no Hex deps). |
The SMTP transport (Laravex.Mail.Transports.Smtp) opens a TCP connection to the configured host and speaks ESMTP:
| Env var | Config key | Default | Description |
|---|---|---|---|
MAIL_HOST |
host |
127.0.0.1 |
SMTP server hostname |
MAIL_PORT |
port |
2525 |
SMTP port (587 for STARTTLS, 465 for SMTPS) |
MAIL_USERNAME |
username |
— | SMTP auth username |
MAIL_PASSWORD |
password |
— | SMTP auth password |
MAIL_SCHEME |
scheme |
"smtp" |
"smtp" for plain TCP or "smtps" for SSL/TLS |
MAIL_EHLO_DOMAIN |
local_domain |
"localhost" |
Domain sent in EHLO
|
# .env
MAIL_MAILER=smtp
MAIL_HOST=smtp.mailgun.org
MAIL_PORT=587
MAIL_USERNAME=postmaster@example.com
MAIL_PASSWORD=secret
Known limitations: AUTH LOGIN mechanism only (no PLAIN, XOAUTH2). No connection reuse — a new TCP connection is opened per message. No inline attachment encoding in the SMTP body (attachments are present on the message map but not MIME-encoded by the transport).
A mailable is any Elixir module that describes an email. Use the Laravex.Mail.Mailable macro for the standard send/0 shorthand:
defmodule App.Mail.WelcomeMail do
use Laravex.Mail.Mailable
def build do
%{
to: "alice@example.com",
subject: "Welcome to the app!",
view: "emails/welcome",
data: %{name: "Alice"}
}
end
enduse Laravex.Mail.Mailable injects a send/0 function that calls Laravex.Mail.Mailer.send(__MODULE__).
If you prefer the multi-method style instead of build/0, define any combination of these callbacks:
| Callback | Required? | Description |
|---|---|---|
to/0 |
Yes (if no build/0) |
Recipient address or list |
subject/0 |
Yes (if no build/0) |
Email subject line |
content/0 |
No | Plain string body |
view/0 |
No | Blade/HTML template name |
data/0 |
No | Assigns passed to the view |
cc/0 |
No | CC recipients |
bcc/0 |
No | BCC recipients |
reply_to/0 |
No | Reply-To address |
attachments/0 |
No | List of attachment maps |
markdown/0 |
No | Markdown view or inline markdown string |
defmodule App.Mail.InvoiceMail do
use Laravex.Mail.Mailable
def to, do: "alice@example.com"
def subject, do: "Invoice #1234"
def view, do: "emails/invoice"
def data, do: %{invoice_number: 1234, total: "99.00"}
def cc, do: ["manager@example.com"]
def reply_to, do: "billing@example.com"
end# Using the injected send/0
App.Mail.WelcomeMail.send()
# Or via the mailer directly
Laravex.Mail.Mailer.send(App.Mail.WelcomeMail)You can bypass the mailable pattern and pass a map directly:
Laravex.Mail.Mailer.send(%{
to: "alice@example.com",
subject: "Your invoice",
body: "<h1>Invoice #1234</h1>",
from: "billing@example.com"
})message
|> Laravex.Mail.Mailer.cc(["boss@example.com", "team@example.com"])
|> Laravex.Mail.Mailer.bcc("archive@example.com")
|> Laravex.Mail.Mailer.reply_to("support@example.com")
|> Laravex.Mail.Mailer.deliver_now()Or set them directly on the message map:
%{
to: "alice@example.com",
subject: "Re: your order",
body: "Thank you!",
cc: "manager@example.com",
bcc: "log@example.com",
reply_to: "support@example.com"
}message = Laravex.Mail.Mailer.attach(message, "/path/to/report.pdf")
# Custom filename and MIME type
message = Laravex.Mail.Mailer.attach(message, "/path/to/report.pdf",
as: "Annual Report 2026.pdf",
mime: "application/pdf"
)csv_data = "name,email\nAlice,alice@example.com"
message = Laravex.Mail.Mailer.attach_data(message, csv_data, "users.csv",
mime: "text/csv"
)Note: The SMTP transport includes attachment metadata on the message struct. Full MIME multipart encoding (embedding files in the SMTP body) is not yet implemented — use a service-based mailer (e.g. Mailgun HTTP API) for attachment delivery in production.
When Mailer.send/1 receives a module name, it resolves the message by calling the module's functions in this order:
-
build/0— if present, the return value is used as the message map directly. - Otherwise, it calls each individual callback (
to/0,subject/0,view/0, etc.) and merges the results.
The from address and name are merged in from mail.from config.
If a mailable specifies a view, the mailer renders the template from resources/views/{view}.blade.php (or .html) using Laravex.View.render_string/2, passing the data map as assigns.
defmodule App.Mail.InvoiceMail do
use Laravex.Mail.Mailable
def build do
%{
to: "alice@example.com",
subject: "Invoice #1234",
view: "emails/invoice",
data: %{invoice_number: 1234, total: "99.00"}
}
end
end{{-- resources/views/emails/invoice.blade.php --}}
<h1>Invoice #{{ invoice_number }}</h1>
<p>Total: ${{ total }}</p>If body is provided alongside view, the body takes precedence.
./artisan make:mail InvoiceMailThis scaffolds a new mailable module at app/Mail/InvoiceMail.ex.
Laravex.Mail.Mailer.fake()Calling fake/0 sets an application env flag and clears the in-memory store. While the fake is active, all mail sent via any driver is captured into ETS — no real mail is dispatched.
Laravex.Mail.Mailer.fake()
App.Mail.WelcomeMail.send()
# Returns true if any captured message matches the predicate
Laravex.Mail.Mailer.assert_sent(fn msg ->
msg.to == "alice@example.com"
end)
Laravex.Mail.Mailer.assert_sent(fn msg ->
String.contains?(msg.subject, "Welcome")
end)
# Returns true if no captured message matches the predicate
Laravex.Mail.Mailer.assert_not_sent(fn msg ->
msg.to == "unknown@example.com"
end)messages = Laravex.Mail.Mailer.sent()
# => [%{to: "alice@example.com", subject: "Welcome…", body: "…", from_address: "…"}]- Notifications — sending mail via the notification system
-
Artisan-Console —
make:mail - Views — Blade template rendering
- Limitations — SMTP transport constraints
Laravex — Laravel-faithful application skeleton & runtime for Elixir.
GitHub
·
Docs
·
Limitations
·
Laravel Docs
Not affiliated with Laravel LLC or the Elixir core team. Built to feel like Laravel on the BEAM.
- Home
- Installation
- Configuration
- Directory-Structure
- Request-Lifecycle
- Service-Container
- Service-Providers
- Deployment
- Routing
- Middleware
- CSRF-Protection
- Controllers
- Requests
- Responses
- Views
- Blade-Templates
- Asset-Bundling
- Session
- Validation
- Error-Handling
- Logging
- Artisan-Console
- Broadcasting
- Cache
- Collections
- Events
- File-Storage
- Helpers
- HTTP-Client
- Localization
- Notifications
- Pipeline
- Queues
- Rate-Limiting
- Strings
- Task-Scheduling