Rails Action Mailer SMTP setup for transactional email

Action Mailer delivers over SMTP with the settings in config.action_mailer.smtp_settings. This guide keeps the API key in Rails encrypted credentials and uses STARTTLS on port 587. Tested with Rails 8.1.

Before you start

Sign in and verify the domain you send from. Viesti accepts a message only when its From address is on a domain verified in your workspace and the envelope sender (MAIL FROM), which most libraries take from the From address, is on the same domain. DNS setup lists the records.
Create an API key on the Credentials page of the dashboard. It is shown once. The key is the SMTP password; the username is apikey.

Setting	Value
Host	`smtp.viesti.email`
Port	`587` with STARTTLS, or `465` with TLS from the first byte
Username	`apikey`
Password	Your API key: `mr_` followed by 64 hex characters
Authentication	PLAIN, offered only once the connection is encrypted

Store the API key

Run bin/rails credentials:edit and add:

viesti:
  api_key: mr_your_api_key

If your platform injects secrets as environment variables instead, use ENV.fetch("VIESTI_API_KEY") wherever the credentials lookup appears below.

Configure Action Mailer

In config/environments/production.rb, replace the commented smtp_settings block Rails generates with:

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  user_name: "apikey",
  password: Rails.application.credentials.dig(:viesti, :api_key),
  address: "smtp.viesti.email",
  port: 587,
  authentication: :plain,
  enable_starttls: true,
  open_timeout: 5,
  read_timeout: 5
}

enable_starttls: true requires the STARTTLS upgrade and fails if it does not happen. authentication: :plain is the mechanism Viesti offers.

Set the sender

In app/mailers/application_mailer.rb:

class ApplicationMailer < ActionMailer::Base
  default from: ENV.fetch("MAIL_FROM")
  layout "mailer"
end

export MAIL_FROM="Acme <[email protected]>"

Send an email

A minimal mailer in app/mailers/receipt_mailer.rb. A real one would render views from app/views/receipt_mailer/ instead of passing body:.

class ReceiptMailer < ApplicationMailer
  def receipt(email)
    mail(to: email, subject: "Your receipt", body: "Thanks for your order.")
  end
end

In application code, call ReceiptMailer.receipt(user.email).deliver_later so the SMTP round trip happens in a background job.

Test it

The settings above live in the production environment, so run the test there:

RAILS_ENV=production bin/rails runner 'ReceiptMailer.receipt("[email protected]").deliver_now'

No output means Viesti accepted the message; a refusal raises an exception with the server's reply. Check Activity in the dashboard.

Port 465

Set port: 465, add tls: true, and remove enable_starttls. The mail gem refuses both together.

Common errors

Error	Cause and fix
`ArgumentError: SMTP-AUTH requested but missing secret phrase`	The password is `nil`: the `viesti: api_key` entry is missing from the credentials this environment loads.
`OpenSSL::SSL::SSLError` … `wrong version number`	`tls: true` or `ssl: true` on port 587. Use `enable_starttls: true` for 587.
`Net::ReadTimeout`	`enable_starttls` on port 465. Use `tls: true` for 465.
`ArgumentError: :enable_starttls and :tls are mutually exclusive.`	Both are set. Keep the one that matches the port.
`Net::SMTPSyntaxError: 504 5.7.4 Unsupported authentication mechanism`	`authentication: :login` or `:cram_md5`. Use `:plain`.
`Net::SMTPAuthenticationError: 523 5.7.10 TLS is required`	STARTTLS is turned off, so the key would have been sent in plain text. Set `enable_starttls: true`.
`Net::SMTPFatalError: 550 5.0.0 sending not permitted`	`MAIL_FROM` is not on a domain verified in your workspace.

Replies from Viesti

Whatever the library, its error includes the server's reply. These are the ones caused by your setup or account:

Reply	Meaning
`535 5.7.8 Authentication failed`	The API key is wrong, revoked or empty. After ten failed attempts from one client address within ten minutes, that address is refused for ten minutes with `454 Too many failed authentications; retry later`.
`525 5.7.13 Workspace suspended; contact support`	The key is valid, but the workspace is suspended or under review. Write to [email protected]; a new key does not help.
`550 5.0.0 sending not permitted`	The From domain is not verified in this workspace, the envelope sender is on a different domain than the From header, or the workspace is not active.
`550 5.0.0 recipient suppressed`	The recipient is on your suppression list after a bounce or complaint; see Bounces.
`451 4.0.0 submission quota exceeded`	The free plan's 75 emails per UTC day or 2,000 per UTC month are used up; see Limits. It is temporary: retry after the reset or upgrade.
`452 4.5.3 Maximum limit of 50 recipients reached`	One message can have at most 50 recipients. Split the send.
`552 5.0.0 message too large`	The message, attachments included, is over 10 MB.
`554 5.0.0 rejected by content audit`	Content screening found the message in violation of the Terms of Service. It is not relayed.

A 250 reply means Viesti accepted the message. Content screening runs before relay; mail it flags is held for review and shows as quarantined on the Activity page.

Next steps

DNS setup: DKIM, SPF, DMARC and return-path records for your domain.
SMTP reference: ports, TLS and authentication in detail.
HTTP API: send the same message as JSON over HTTPS.
Limits and Bounces: quotas, message size and suppressions.

Option names are from the Rails guide Action Mailer Basics; tested with Rails 8.1.4 and the mail 2.9.1 gem. Checked 26 September 2026.