Skip to content
David Ciulla edited this page Nov 7, 2026 · 2 revisions

Mail

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.


Configuration

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).

SMTP Transport

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).


Writing Mailables

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
end

use Laravex.Mail.Mailable injects a send/0 function that calls Laravex.Mail.Mailer.send(__MODULE__).

Mailable Callbacks

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

Sending Mail

Via a Mailable Module

# Using the injected send/0
App.Mail.WelcomeMail.send()

# Or via the mailer directly
Laravex.Mail.Mailer.send(App.Mail.WelcomeMail)

Via a Plain Map

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

CC, BCC, and Reply-To

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

Attachments

Attach a File Path

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"
)

Attach Raw Data

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.


Mailable Resolution

When Mailer.send/1 receives a module name, it resolves the message by calling the module's functions in this order:

  1. build/0 — if present, the return value is used as the message map directly.
  2. 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.


Rendering Views

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.


Generate a Mailable

./artisan make:mail InvoiceMail

This scaffolds a new mailable module at app/Mail/InvoiceMail.ex.


Testing

Activating the Fake

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.

Asserting Mail Was Sent

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)

Inspecting Sent Mail

messages = Laravex.Mail.Mailer.sent()
# => [%{to: "alice@example.com", subject: "Welcome…", body: "…", from_address: "…"}]

See Also

Clone this wiki locally