Letter Opener

To use Letter Opener in a Rails application, add the gem to your development group and configure Action Mailer to use the :letter_opener delivery method. This will cause emails to pop up in your default browser instead of being sent.

1. Add the gem to your Gemfile:

gem "letter_opener", group: :development

2. Run bundle install.
3. Configure config/environments/development.rb:

config.action_mailer.delivery_method = :letter_opener
config.action_mailer.perform_deliveries = true

By default, messages are stored in tmp/letter_opener.

You can customize the behavior of Letter Opener using the LetterOpener.configure block. Available configuration options include:

• location: The directory where email messages are stored. Defaults to tmp/letter_opener.
• message_template: Determines how the email is rendered. :default renders a styled message with metadata. Use :light to render only the message body without metadata or extra styling.
• file_uri_scheme: Sets the default file URI scheme. This is useful for environments like WSL (Windows Subsystem for Linux) where the default scheme might not work.

If you are running your application in a Docker container or a VM without a browser, you may encounter a Launchy::CommandNotFoundError. To prevent this error and allow the process to continue without attempting to open a browser, set the following environment variables:

• LAUNCHY_DRY_RUN=true
• BROWSER=/dev/null

To use Letter Opener with the Pony gem, configure the Pony.options with LetterOpener::DeliveryMethod and provide the location in via_options.

require "letter_opener"
Pony.options = {
  via: LetterOpener::DeliveryMethod,
  via_options: {location: File.expand_path('../tmp/letter_opener', __FILE__)}
}

If you are using ActionMailer directly without the Rails framework, you must manually add the delivery method and set it as the default.

require "letter_opener"
ActionMailer::Base.add_delivery_method :letter_opener, LetterOpener::DeliveryMethod, :location => File.expand_path('../tmp/letter_opener', __FILE__)
ActionMailer::Base.delivery_method = :letter_opener

If you are not using Rails, you can integrate Letter Opener with the Mail gem by setting the delivery method and specifying a storage location.

require "letter_opener"
Mail.defaults do
  delivery_method LetterOpener::DeliveryMethod, location: File.expand_path('../tmp/letter_opener', __FILE__)
end

The deliver! method performs validation on the mail object. The following errors may be raised:

• ArgumentError: Raised if the smtp_envelope_from or smtp_envelope_to addresses are blank or empty.
• LetterOpener::DeliveryMethod::InvalidOption: Raised during initialization if the :location option is missing.

When initializing or rendering messages, you can pass specific options to control the output. Note that location and message_template must be provided if they are not already set in the global LetterOpener.configuration.

Available options:

• location: The directory where message files will be stored (e.g., tmp/letter_opener).
• part: A specific part of the mail to render (e.g., mail.html_part).
• message_template: The name of the ERB template to use for rendering (must correspond to a file in the project's templates/ directory).

To render one or more email messages as files, use the LetterOpener::Message.rendered_messages class method. This method takes a mail object and an optional options hash.

It automatically handles different parts of the email:

• If the mail has an html_part, it renders that.
• If the mail has a text_part, it renders that.
• If neither is present, it renders the main mail object.

Returned messages are sorted by type (rich before plain).

The LetterOpener::DeliveryMethod accepts the following configuration options during initialization:

• :location (Required): The directory path where message files are stored. If not provided, an InvalidOption error is raised.
• :message_template: Determines how the message is rendered. Common values include :default (renders a styled message with metadata).
• :file_uri_scheme: The URI scheme used to open the file (e.g., file://). This is useful for resolving path issues in environments like WSL (Windows Subsystem for Linux).