Cloudflare Email

Send and receive email in Ruby and Rails through Cloudflare Email Service.

Use your existing Rails mailers, receive messages through Action Mailbox, and add persistent inboxes with Mailbox Kit. SQLite is supported. Database tenancy and the management UI are optional.

gem "cloudflare-email", "~> 0.4.0"

Mailbox Kit installs automatically. If you use another email provider, you can use Mailbox Kit on its own.

Requires Ruby 3.2+; Rails integrations support Rails 7.2–8.1. Use a current patch release. Plain Ruby sending does not require Rails or a database.

bundle install
bin/rails generate cloudflare:email:install --no-inbound

Verify a sending domain in Cloudflare and add your account ID and sending token:

export CLOUDFLARE_ACCOUNT_ID=your-account-id
export CLOUDFLARE_API_TOKEN=your-email-sending-token

Your regular mailers can now send through Cloudflare:

class HelloMailer < ApplicationMailer
  def hello(address)
    mail(from: "hello@mail.example.com", to: address, subject: "Hello") do |format|
      format.text { render plain: "Hello from Rails!" }
    end
  end
end

HelloMailer.hello("you@example.net").deliver_now

HTML templates, attachments, multipart messages, cc/bcc, and reply headers work through Action Mailer. Follow the Rails setup guide for receiving and delivery tracking.

The included Worker stores incoming email at Cloudflare and retries delivery while Rails is unavailable. Rails verifies each request and stores the original email through Action Mailbox.

Prepare Rails and deploy the Worker, then connect your receiving address in Cloudflare Email Routing.

The mailbox guide walks through creating inboxes and aliases, receiving mail, marking it read, archiving it, and sending replies.

Mount the optional management UI to manage mailboxes and read messages using your app's login and permissions. It is server-rendered and needs no frontend build.

For a runnable SQLite example, clone the hello-world Rails app.

require "cloudflare-email"

client = Cloudflare::Email::Client.new(
  account_id: ENV.fetch("CLOUDFLARE_ACCOUNT_ID"),
  api_token: ENV.fetch("CLOUDFLARE_API_TOKEN"),
)

response = client.send(
  from: "hello@mail.example.com",
  to: "you@example.net",
  subject: "Hello",
  text: "Hello from Ruby!",
)
response.message_id
response.accepted?

Acceptance is the start of delivery. Use delivery events to track delivered messages, bounces, and complaints. See the Ruby API reference for attachments, raw MIME, and configuration.

Security · Contributing · MIT license