Send emails with Ruby on Rails

# config/environments/production.rb  (works on Rails 6, 7 and 8)
Rails.application.configure do
  config.action_mailer.delivery_method = :smtp
  config.action_mailer.smtp_settings = {
    address:              "smtp.poststack.dev",
    port:                 587,
    user_name:            "poststack",                     # any non-empty value
    password:             ENV.fetch("POSTSTACK_API_KEY"),  # sk_live_... / sk_test_...
    authentication:       :plain,
    enable_starttls_auto: true,                            # STARTTLS on 587 (port 465: use tls: true instead)
    open_timeout:         5,
    read_timeout:         10
  }
  config.action_mailer.raise_delivery_errors = true
  config.action_mailer.default_url_options = { host: "app.yourdomain.com", protocol: "https" }
end

# app/mailers/application_mailer.rb
class ApplicationMailer < ActionMailer::Base
  default from: "Acme <hello@yourdomain.com>"   # must be on a verified domain
  layout "mailer"
end

# app/mailers/user_mailer.rb
class UserMailer < ApplicationMailer
  def welcome
    @user = params[:user]
    mail(to: @user.email, subject: "Welcome to Acme")
  end
end

# app/views/user_mailer/welcome.html.erb  -> the HTML part
# app/views/user_mailer/welcome.text.erb  -> the plain-text part
# (with both present, Rails sends multipart/alternative automatically)

# anywhere in your app — e.g. a controller after sign-up
UserMailer.with(user: @user).welcome.deliver_later   # via Active Job
# UserMailer.with(user: @user).welcome.deliver_now   # synchronous

# config/initializers/action_mailer_retries.rb
# Retry transient SMTP failures from deliver_later — but not bad configuration.
Rails.application.config.to_prepare do
  ActionMailer::MailDeliveryJob.class_eval do
    # 4xx replies, timeouts and dropped connections: try again with backoff
    retry_on Net::SMTPServerBusy, Net::ReadTimeout, Net::OpenTimeout,
             Errno::ECONNRESET, wait: 30.seconds, attempts: 5
    # 535 = bad API key; 5xx = permanent rejection. Retrying will not help.
    discard_on Net::SMTPAuthenticationError, Net::SMTPFatalError do |job, error|
      Rails.logger.error("PostStack rejected #{job.arguments.first}: #{error.message}")
    end
  end
end

class InvoiceMailer < ApplicationMailer
  def receipt
    @order = params[:order]

    attachments["invoice-#{@order.number}.pdf"] = @order.invoice_pdf   # binary string
    attachments["terms.pdf"] = File.read(Rails.root.join("public/terms.pdf"))
    attachments.inline["logo.png"] = File.read(Rails.root.join("app/assets/images/logo.png"))
    # in the view: <%= image_tag attachments["logo.png"].url %>

    headers["X-PostStack-Tags"] = "receipt,transactional"
    headers["X-PostStack-Idempotency-Key"] = "receipt-#{@order.id}"

    mail(
      to: @order.email,
      cc: "accounts@example.com",
      reply_to: "billing@yourdomain.com",
      subject: "Receipt for order ##{@order.number}"
    )
  end
end

# config/environments/development.rb
config.action_mailer.delivery_method = :letter_opener   # gem "letter_opener"
config.action_mailer.perform_deliveries = true

# config/environments/test.rb (Rails default)
config.action_mailer.delivery_method = :test

# test/mailers/user_mailer_test.rb
class UserMailerTest < ActionMailer::TestCase
  test "welcome" do
    user = users(:alice)
    email = UserMailer.with(user: user).welcome
    assert_emails(1) { email.deliver_now }
    assert_equal ["hello@yourdomain.com"], email.from
    assert_equal "Welcome to Acme", email.subject
  end
end

# staging: same SMTP settings as production, with an sk_test_ key

require "net/http"
require "json"
require "securerandom"

class Poststack
  URI_EMAILS = URI("https://api.poststack.dev/emails")

  def self.send_email(payload, idempotency_key: SecureRandom.uuid, attempts: 3)
    attempts.times do |attempt|
      res = Net::HTTP.start(URI_EMAILS.host, URI_EMAILS.port, use_ssl: true,
                            open_timeout: 5, read_timeout: 10) do |http|
        req = Net::HTTP::Post.new(URI_EMAILS)
        req["Authorization"]   = "Bearer #{ENV.fetch('POSTSTACK_API_KEY')}"
        req["Content-Type"]    = "application/json"
        req["Idempotency-Key"] = idempotency_key   # same key on every retry
        req.body = payload.to_json
        http.request(req)
      end

      case res.code.to_i
      when 200..299 then return JSON.parse(res.body)   # => {"id"=>"em_..."}
      when 429, 500..599
        sleep(res["retry-after"]&.to_i || 2**attempt)
      else
        # 400 invalid payload, 401/403 key problem, 422 unverified domain / suppressed
        raise "PostStack #{res.code}: #{res.body} (request #{res['x-request-id']})"
      end
    end
    raise "PostStack: retries exhausted"
  end
end

Poststack.send_email({   # braces: a positional hash, not keyword arguments
  from: "Acme <hello@yourdomain.com>",
  to: ["user@example.com"],
  subject: "Hello from Ruby!",
  html: "<h1>Welcome!</h1>",
  text: "Welcome!"
})