URI::SMTP

Extends Ruby's URI with support for SMTP-uri's.
This allows for more concise SMTP-config:

# config/environments/production.rb
config.action_mailer.delivery_method = :smtp
- config.action_mailer.smtp_settings = {
-   address:         "smtp.gmail.com",
-   port:            587,
-   domain:          "example.com",
-   user_name:       Rails.application.credentials.dig(:smtp, :user_name),
-   password:        Rails.application.credentials.dig(:smtp, :password),
-   authentication:  "plain",
-   enable_starttls: true,
-   open_timeout:    5,
-   read_timeout:    5
- }
# given ENV["SMPT_URL"]:
# "smtp://user_name:password@smtp.gmail.com?open_timeout=5&read_timeout=5#example.com"
+ config.action_mailer.smtp_settings = URI(ENV.fetch("SMTP_URL")).to_h(format: :am)

Installation

Install the gem and add to the application's Gemfile by executing:

bundle add uri-smtp

If bundler is not being used to manage dependencies, install the gem by executing:

gem install uri-smtp

Usage

parse

u = URI("smtps+login://user%40gmail.com:p%40ss@smtp.gmail.com#sender.org")

url.scheme           #=> "smtps+login"
url.auth             #=> "login"
url.starttls         #=> false
url.starttls?        #=> false
url.tls?             #=> true
url.userinfo         #=> "user%40gmail.com:p%40ss"
url.decoded_userinfo #=> "user@gmail.com:p@ss"
url.decoded_user     #=> "user@gmail.com"
url.user             #=> "user%40gmail.com"
url.decoded_password #=> "p@ss"
url.password         #=> "p%40ss"
url.host             #=> "smtp.gmail.com"
url.port             #=> 465
url.domain           #=> "sender.org"

to_h

URI("smtps+login://user%40gmail.com:p%40ss@smtp.gmail.com?domain=sender.org").to_h
#=>
{auth: "login",
 domain: "sender.org",
 host: "smtp.gmail.com",
 port: 587,
 scheme: "smtps+login",
 starttls: :always,
 tls: false,
 user: "user@gmail.com",
 password: "p@ss"}

For ActionMailer configuration, use format: :action_mailer (or :am):

URI("smtps+login://user%40gmail.com:p%40ss@smtp.gmail.com#sender.org").to_h(format: :am)
#=>
{address: "smtp.gmail.com",
 authentication: "login",
 domain: "sender.org",
 enable_starttls: :always,
 port: 587,
 user_name: "user@gmail.com",
 password: "p@ss"}

Besides renaming some keys, this also works around a quirk in v2.8.1 of the mail-gem (e.g. tls: false skips setting up STARTTLS).

Full Rails config:

    # config/environments/development.rb
    config.action_mailer.delivery_method = :smtp
    # [mailcatcher](https://github.com/sj26/mailcatcher) fallback:
    config.action_mailer.smtp_settings = URI(ENV.fetch("SMTP_URL", "smtp://127.0.0.1:1025")).to_h(format: :am)

Credentials separately

Credentials in the URL must be uri-escaped (e.g. user@gmail.com → user%40gmail.com), which is easy to get wrong and makes the (env-var) value hard to read. To avoid this, leave them out of the URL and pass them to to_h instead:

config.action_mailer.smtp_settings =
  URI("smtps+login://smtp.gmail.com#sender.org")
    .to_h(format: :am, user: ENV["SMTP_USERNAME"], password: ENV["SMTP_PASSWORD"])
#=>
{address: "smtp.gmail.com",
 authentication: "login",
 domain: "sender.org",
 port: 465,
 tls: true,
 user_name: "...",
 password: "..."}

The URL carries the connection shape; the env-vars carry the secrets. Note auth still resolves from the scheme (+login) even though the URL has no userinfo, and the overrides take precedence over any credentials in the URL.

SMTP-URI

There's no official specification for SMTP-URIs. There's some prior work though. This implementation is heavily inspired by aerc.

<scheme>[+<auth>]://[<user>[:<password>]@]<host>[:<port>][?<query>][#<fragment>]

scheme

• smtp
  SMTP with STARTTLS (i.e. url.starttls #=> :always).
• smtp+insecure
  SMTP without STARTTLS (i.e. url.starttls #=> false)..
• smtps
  SMTP with TLS.
• smtps+insecure
  SMTP with TLS, skipping certificate verification (i.e. url.tls_verify #=> false).

[!NOTE] to get url.starttls #=> :auto, provide it in the query: smtp://user:pw@foo?auth=auto. In that case net-smtp uses STARTTLS when the server supports it (but won't halt like when using :always).

auth

Any value for auth that passes the URI-parser is acceptable. Though the following values have special meaning:

• none
  No authentication is required.
• plain
  Authenticate with a username and password using AUTH PLAIN. This is the default behavior when no authentication is provided.

[!NOTE] any query's value for auth takes precedence.

Examples

SMTP URI	TLS?	Port	STARTTLS	Auth Method	Notes
smtp://smtp.example.com	❌	587	⚡	none	Standard submission with STARTTLS :always
smtp+insecure://smtp.example.com	❌	587	❌	none	Standard submission without STARTTLS
smtp+insecure+login://user:pass@smtp.example.com	❌	587	❌	login	Authenticate insecurely using LOGIN auth
smtp://smtp.example.com?starttls=auto	❌	587	🔄	none	Standard submission with STARTTLS :auto
smtp://smtp.example.com:1025	❌	1025	⚡	none	Standard submission with STARTTLS :always on custom port
smtp://user:pass@mail.example.com	❌	587	⚡	plain	STARTTLS :always with (default) PLAIN auth
smtp+login://user:pass@mail.example.com	❌	587	⚡	login	STARTTLS :always with LOGIN auth
smtp+none://mail.example.com	❌	587	🔄	none	Explicit no authentication
smtps://mail.example.com	✅	465	❌	none	Direct TLS connection
smtps+insecure://mail.example.com	✅	465	❌	none	Direct TLS, skipping certificate verification
smtps://mail.example.com?domain=sender.org&read_timeout=5&open_timeout=5	✅	465	❌	none	domain, read_timeout and open_timeout set
smtps+login://user@imap.gmail.com	✅	465	❌	login	Direct TLS with LOGIN auth
smtps://user%40gmail.com:p%40ss@imap.gmail.com	✅	465	❌	login	Direct TLS with encoded userinfo user@gmail.com:p@ss
smtp://localhost	❌	25	❌	none	Local delivery (no encryption)
smtp://127.0.0.1	❌	25	❌	none	Local delivery (no encryption)

Legend

STARTTLS

• ⚡ = :always
  Require STARTTLS (i.e. net-smtp aborts when server doesn't support STARTTLS).
• 🔄 = :auto
  Use STARTTLS if supported by server.
• ❌ = false
  No STARTTLS. This is always the case when using TLS.

Development

mise recommended. This sets the right version of Ruby and adds bin to PATH.

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment. Use bin/yard server --reload when working on documentation.

To install this gem onto your local machine, run bin/rake install.

Releasing

The gem is published automatically by GitHub Actions (.github/workflows/release.yml) when a v* tag is pushed: CI builds the gem, publishes it to rubygems.org as a trusted publisher (with build provenance), and creates the GitHub release. The gem is never pushed from your machine, and CI never writes back to the repo.

To cut a release:

1. Bump the version: sh bin/rake 'gem:write_version[0.7.3]' This rewrites lib/uri/smtp/version.rb and updates Gemfile.lock.
2. Finalize CHANGELOG.md (rename ## [Unreleased] to the new version + date).
3. Commit and push, then confirm CI is green.
4. Build, tag and push: sh bin/rake release This builds the gem locally (verifying it builds), creates the v0.7.3 tag, and pushes it to origin — which triggers the release workflow. Pushing to rubygems is disabled via gem_push=no (set in mise.toml); outside mise, run gem_push=no bin/rake release.

Tags use a v prefix; a fourth version segment (e.g. v0.7.3.rc1) is published as a pre-release.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/eval/uri-smtp.

License

The gem is available as open source under the terms of the MIT License.