Upgrading from v0.1 to v0.2

Copy Markdown View Source

This guide is now a subordinate codemod reference.

The canonical latest-0.x to 1.0 path lives in upgrading-to-v1_0.md. Use that guide for the full compatibility story, support matrix, strict-CI posture, and retained legacy bridge inventory. Use this page when you specifically need the focused v0.1 -> v0.2 setter rewrite details.

This guide covers the original v0.1 mailable API migration to the v0.2 public surface. The big change is that the common authoring path now uses native Mailglass.Message setters instead of direct Swoosh.Email calls inside your mailables.

Before/After Examples

In v0.1, mailables commonly piped directly into Swoosh.Email:

# v0.1 Mailable
defmodule MyApp.WelcomeEmail do
  use Mailglass.Mailable, stream: :transactional

  def welcome(user) do
    new()
    |> Swoosh.Email.to(user.email)
    |> Swoosh.Email.from("hello@myapp.com")
    |> Swoosh.Email.subject("Welcome!")
    |> Swoosh.Email.html_body("<h1>Welcome</h1>")
    |> Swoosh.Email.attachment("path/to/guide.pdf")
    |> Mailglass.Message.put_function(:welcome)
  end
end

In v0.2, the same mailable becomes:

# v0.2 Mailable
defmodule MyApp.WelcomeEmail do
  use Mailglass.Mailable, stream: :transactional

  def welcome(user) do
    new()
    |> to(user.email)
    |> from("hello@myapp.com")
    |> subject("Welcome!")
    |> html_body("<h1>Welcome</h1>")
    |> attach("path/to/guide.pdf")
    |> Mailglass.Message.put_function(:welcome)
  end
end

The codemod covers these eight setters:

  • to/2
  • from/2
  • subject/2
  • text_body/2
  • html_body/2
  • header/3
  • attachment/2 -> attach/2
  • put_tag/2

Codemod Walkthrough

mix mailglass.upgrade.v0_2 is an Igniter-backed codemod. Use it as a dry-run first, then apply once the diff looks right.

If you are upgrading for the 1.0 contract rather than replaying the original v0.2 cutover, read upgrading-to-v1_0.md first and then come back here for the codemod specifics.

  1. Ensure you have the igniter dependency installed in your mix.exs:
def deps do
  [
    {:igniter, "~> 0.7", only: [:dev, :test]}
  ]
end
  1. Fetch the dependency:
mix deps.get
  1. Preview the rewrite:
mix mailglass.upgrade.v0_2
  1. Apply the rewrite:
mix mailglass.upgrade.v0_2 --apply
  1. Compile and run your test suite before committing the change:
mix compile
mix test

Ambiguous Cases / Recipes

The codemod rewrites only the eight setters above. If you use another Swoosh.Email function, the task leaves that call in place and emits a warning with the migration-guide URL and the supported escape hatch.

Skipping unknown Swoosh.Email function: put_provider_option/2. Review https://hexdocs.pm/mailglass/guides/upgrading-from-v0_1.html for ambiguous-case migration guidance and the Mailglass.Message.update_swoosh/2 escape hatch.

If you still need advanced Swoosh capabilities that are not native setters, keep the common path on Mailglass.Message and use Mailglass.Message.update_swoosh/2 only around the unsupported call:

new()
|> to("user@example.com")
|> Mailglass.Message.update_swoosh(fn email ->
  Swoosh.Email.put_provider_option(email, :template_id, "my-template")
end)
|> Mailglass.Message.put_function(:welcome)

New in v0.2

Per-Domain Rate Limiting

v0.2 introduces a multi-bucket rate limiter to protect your sender reputation. Outbound messages (except those on the :transactional stream) are now checked against:

  • :tenant_recipient limits (100/min default)
  • :global_recipient limits (1000/min default)
  • :sender_domain limits (500/min default)

If you see {:error, %Mailglass.RateLimitError{}}, your message was throttled. See the current rate-limiting guide in the published Mailglass docs for configuration overrides.

Enhanced Test Assertions

The testing surface has been modernized. import Mailglass.TestAssertions now provides:

  • assert_mail_sent(params)
  • last_mail()
  • wait_for_mail(params)

These replace manual mailbox inspections and work seamlessly with the new Mailglass.Adapters.Fake.

Dependency Matrix

To use this upgrade codemod successfully, ensure your dependencies meet the minimum versions:

  • mailglass: ~> 0.2
  • phoenix: ~> 1.8
  • phoenix_live_view: ~> 1.1
  • igniter: ~> 0.7

For the latest supported 0.x to 1.0 release posture, support horizon, and matched sibling-package expectations, defer to upgrading-to-v1_0.md and compatibility-and-deprecations.md.

Troubleshooting

Codemod skips my mailables

  • Ensure your mailables use the use Mailglass.Mailable macro.
  • The codemod targets direct Swoosh.Email calls. If you have aliased Swoosh.Email or are using qualified calls that don't match the expected patterns, you may need to update them manually.

"RateLimitError" after upgrading

  • v0.2 enables rate limiting by default for :bulk and :operational streams.
  • If your existing volume exceeds the new defaults, configure overrides in config/runtime.exs or move time-sensitive alerts to the :transactional stream.

Tests fail with "no mail sent"

Last updated: 2026-05-03 (Phase 31 ships at v0.1).