Send email from Ruby on Rails with an email API
Send email from Ruby on Rails over HTTPS instead of SMTP: one Net::HTTP call from a service object, an id back, delivery on a webhook.
# app/services/shipping_mailer.rb# net/http and json are in the standard library.require "net/http"require "json"
uri = URI("https://api.rasket.com/emails")key = ENV.fetch("RASKET_API_KEY")
request = Net::HTTP::Post.new(uri)request["Authorization"] = "Bearer #{key}"# Required: a request with no User-Agent is# refused before it reaches your account.request["User-Agent"] = "acme-billing/1.0"request["Content-Type"] = "application/json"request["Idempotency-Key"] = "order-1042"request.body = { from: "Acme <orders@send.acme.example>", to: ["ronald.williams@example.com"], subject: "Your order has shipped", html: "<p>Order 1042 shipped today.</p>"}.to_json
response = Net::HTTP.start( uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
unless response.is_a?(Net::HTTPSuccess) raise "Rasket answered #{response.code}"end
puts JSON.parse(response.body)["id"]What sending from Ruby on Rails actually involves
To send email from Ruby on Rails you would normally configure Action Mailer with an SMTP host. Posting to an email API instead removes that configuration: one request from a service object or a job, and an id you can store on the record. There is no Ruby SDK, so the sample below uses Net::HTTP from the standard library — nothing to add to your Gemfile.
Last updated 2026-09-16. Every field, header and limit below is the one the emails reference carries.
What you get with the key
Five things that arrive with the first request rather than with a later plan.
Idempotent sends
Put an Idempotency-Key on a send and repeat it as often as you like. For 24 hours the same key and payload return the first response instead of a second email, and a different payload under that key is refused rather than sent.
Signed webhooks you can replay
Delivery, bounce, complaint, open and click posted to your endpoint with a timestamp and a signature, retried on failure and replayable from the dashboard.
Inbound mail on your own domain
Receive at your domain on every plan. Each message arrives on a signed webhook with its headers, text and HTML, and its attachments behind signed links.
Templates with typed variables
Publish a template, then send it by ID or alias with the values it declares. Every email records the exact version it was rendered from.
Broadcasts and automations
Contacts with typed properties, topics people subscribe to, and per-contact workflows that wait, branch and send — through the same pipeline as the rest of your mail.
How to send email from Ruby on Rails
Six steps, in this order. Everything before the fifth is done once, and only the fifth is about the language you write in.
- 1
Create an API key
Open API keys in the dashboard and create one. It is shown once and stored hashed, so copy it then. Put it in your environment as RASKET_API_KEY and read it from there; a key committed to a repository is a key you have to rotate.
- 2
Add a sending domain
POST /domains with a domain you control. A subdomain such as send.acme.example is the usual choice, because it keeps this mail's reputation separate from the address your people write from. The response carries a records array.
- 3
Publish the DNS records
Every row of records goes into your DNS: the DKIM TXT record at rasket._domainkey, and the two records that give the domain its own return path. Nothing sends from the domain until they resolve.
- 4
Verify the domain
POST /domains/{domain_id}/verify. The domain comes back with a status on each record, and once it reads verified you can send from any address on it. An unverified sender is refused rather than quietly dropped.
- 5
Send your first email from Ruby on Rails
Post the message with the sample above. Carry an Idempotency-Key — yours or your queue's retry cannot then turn into a second email — and a User-Agent, which every request has to have. A 200 with an id means we have taken responsibility for the message.
- 6
Subscribe a webhook and check its signature
POST /webhooks with an https endpoint and the events you care about. Delivery, bounce, complaint, open and click arrive there with svix-id, svix-timestamp and svix-signature; verify against the raw body before anything parses it.
Verify webhooks in Ruby on Rails
request.raw_post is the body as it arrived; read it before params or any JSON middleware touches the request, and rewind the stream if something later needs it. The svix gem's Webhook#verify takes those bytes and request.env. A controller that reads params first has already parsed, and the signature is over the original string.
The five steps a verifier performs, in seven languages, are on the webhooks reference.
Read the long version
Sending email from Ruby on Rails: the full guide covers attachments, scheduling, suppressions and what to do when a message bounces.
Questions about Ruby on Rails
Do I need an SMTP server to send email from Rails?
No. Action Mailer's delivery methods exist to speak SMTP, and an HTTPS API replaces that layer: no host, no port, no TLS settings. Rasket has no SMTP relay, so a Rails app that must keep using an :smtp delivery method is not a fit for it.
Is there a Ruby SDK?
Not today. The sample above uses Net::HTTP and JSON from the standard library, which is the whole of what a send needs: a bearer token, a User-Agent, a JSON body and one header for safe retries. The API reference documents every field the body can carry.
Where do I keep the API key in a Rails app?
In the environment, read as ENV.fetch("RASKET_API_KEY") — fetch rather than [], so a missing key raises at boot instead of sending a request with an empty bearer. Rails credentials work too; what matters is that the value is not in the repository.
How do I stop a retry from sending the same email twice?
Set the Idempotency-Key header from the record the mail is about, and reuse it on every retry. Active Job retries are exactly the case this covers: for 24 hours the same key with the same payload returns the first response rather than sending a second message.
How do I verify a Rasket webhook in Rails?
gem install svix, read request.raw_post as the first line of the action, and pass it with request.env to Svix::Webhook#verify. Skip the CSRF check on that action — the request comes from us, and the signature is what authenticates it — and answer 400 when verification raises.
Keep reading
Make your first send
Create a key, verify a domain, and post your first message from Ruby on Rails. The free plan does not expire.