Send email from Ruby on Rails

# Server-side only: your host's secret store, or .env with dotenv-rails.
YOURMAIL_API_KEY=yourmail_...

# app/services/yourmail_client.rb
require "net/http"
require "json"

class YourmailClient
  ENDPOINT = URI("https://api.yourmail.dev/v1/emails")

  class Error < StandardError
    attr_reader :status, :type, :retry_after

    def initialize(message, status:, type:, retry_after: nil)
      super(message)
      @status = status
      @type = type
      @retry_after = retry_after
    end
  end

  # 5xx, or a rate limit with a short Retry-After: worth another attempt.
  class TransientError < Error; end
  # Invalid field, unverified domain, suppressed recipient, quota or a
  # day-long cap: the same request fails the same way. Surface it.
  class PermanentError < Error; end

  def initialize(api_key: ENV.fetch("YOURMAIL_API_KEY"))
    @api_key = api_key
  end

  def send_email(**email)
    request = Net::HTTP::Post.new(ENDPOINT)
    request["Authorization"] = "Bearer #{@api_key}"
    request["Content-Type"] = "application/json"
    request.body = JSON.generate(email)

    response = Net::HTTP.start(
      ENDPOINT.host, ENDPOINT.port,
      use_ssl: ENDPOINT.scheme == "https", open_timeout: 5, read_timeout: 10
    ) { |http| http.request(request) }

    body = JSON.parse(response.body) rescue {}
    return body.fetch("id") if response.is_a?(Net::HTTPSuccess)

    error = body.fetch("error", {})
    status = response.code.to_i
    retry_after = response["Retry-After"]&.to_i
    # The daily caps answer 429 with the seconds until UTC midnight, so a
    # rate_limited is only transient when the wait is short.
    transient = status >= 500 ||
      (error["type"] == "rate_limited" && retry_after && retry_after <= 60)

    raise (transient ? TransientError : PermanentError).new(
      error["message"] || response.message,
      status: status, type: error["type"], retry_after: retry_after
    )
  end
end

id = YourmailClient.new.send_email(
  from: "Acme <hello@mail.acme.com>",
  to: "customer@example.com",
  subject: "Welcome aboard",
  html: "<p>Thanks for signing up.</p>",
  text: "Thanks for signing up."
)
puts "queued #{id}"

# app/jobs/welcome_email_job.rb
class WelcomeEmailJob < ApplicationJob
  queue_as :default

  # Retry what can succeed later: 5xx, short rate limits, timeouts.
  retry_on YourmailClient::TransientError, wait: :polynomially_longer, attempts: 5
  retry_on Net::OpenTimeout, Net::ReadTimeout, wait: :polynomially_longer, attempts: 5

  # Permanent: the same request will fail the same way. Record it and stop.
  discard_on YourmailClient::PermanentError do |job, error|
    Rails.logger.warn("YourMail rejected #{job.class.name}: #{error.type}: #{error.message}")
  end

  def perform(user)
    YourmailClient.new.send_email(
      from: "Acme <hello@mail.acme.com>",
      to: user.email,
      subject: "Welcome aboard",
      html: "<p>Thanks for signing up.</p>",
      text: "Thanks for signing up.",
      # Derived from the user, not generated per attempt: a retry after a lost
      # response returns the original id instead of sending twice.
      idempotency_key: "welcome:#{user.id}",
      tags: [{ name: "type", value: "welcome" }]
    )
  end
end

# After the user is created, e.g. in UsersController#create:
WelcomeEmailJob.perform_later(@user)

# Don't do this.
class WelcomeEmailJob < ApplicationJob
  # Retries every failure: a suppressed recipient fails all five times, and
  # a quota error is a ceiling for the rest of the day, not backpressure.
  retry_on StandardError, attempts: 5
end