Documentation

Send email in Ruby.

Works with: Ruby 3.0 or newer, standard library only.

Install

Get a key under API keys in the dashboard and verify a sending domain first (how). Then add the library:

Terminal

1gem install mailtruss

Send an email

This sends one message and passes an idempotency key, so repeating the request can never deliver it twice. Pass an idempotency key and the same key never sends twice, so a retry after a timeout is safe.

send.rb

1client = Mailtruss::Client.new(ENV.fetch("MAILTRUSS_API_KEY"))
2client.emails.send({ from: "hello@yourdomain.com", to: "ana@example.com", subject: "Welcome", html: "<p>Hi Ana</p>" }, idempotency_key: "welcome-ana")

More on what you can put in a message (cc, bcc, attachments, tags, templates, scheduling) is under Sending.

Rails

With the gem in your Gemfile, :mailtruss is registered as an Action Mailer delivery method, so existing mailers need no change.

production.rb

1config.action_mailer.delivery_method = :mailtruss
2config.action_mailer.mailtruss_settings = { api_key: ENV["MAILTRUSS_API_KEY"] }

Verify webhook signatures

Mailtruss signs every webhook with the Standard Webhooks scheme. Check the signature before you trust a request. Use request.raw_post so the signature is checked against the exact bytes received.

webhooks_controller.rb

1event = Mailtruss.verify_webhook(request.raw_post, request.headers, ENV.fetch("MAILTRUSS_WEBHOOK_SECRET"))

Events, payloads and retries are on the Webhooks page.

Handle errors

Failures are Mailtruss::Error with name, status and request_id. Every error name, with its cause and fix, is in the error catalogue.