cloudflare-email_service 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfedd8bad6300247c099669c46ecc795a2fb19faee035a1edf039717836a12b9
-  data.tar.gz: 44c03575adca32ba9e85ab037f140051fbc933afcaec13581ebcf3326df6d8ac
+  metadata.gz: ae0f87f99efee9db13b22ae4cd2560f75878ee141ce0c34797da94dbb387a37c
+  data.tar.gz: 23cd36dc8c771b45a649d93d6d9385ab76751755b72ffcd795840280c359a53f
 SHA512:
-  metadata.gz: 2c879194227a7591df1568a59857aba63d2d26b153db4ea7f4b0a5d3bb0ae38759be74429343403640e720a40b9a7c3782eeb6d6463f7796cf204980955032f3
-  data.tar.gz: 527048e68ef2e504228eeeb11df7efb55a8531fd0d11c92cf833b64a1c916e22d9feedb422636881695e4df41fb0ed89ead512a3f586e544ab6c826e1fc34ebe
+  metadata.gz: d5d2e2efb6a2fa418400b2b0d4f26558ef3a647f880d89c81ee71ba1a278d7182ccb8c0db68116a9b106284fb0587b8ebac96a6ba0678aa3da61e7ac6b97b910
+  data.tar.gz: c1db350ec8e6323eb9b7b9f3b5db198c1cf1801c3f790567d0d53c8f34c29ed7d9e2108a9601d9ad9c5b4ba7d9076bcee627856961cbdfb7ea2725f875484b7d

data/CHANGELOG.md

@@ -6,6 +6,27 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-06-19
+
+### Added
+- The bundled Email Worker template now answers `GET /` with a
+  `{ ok, configured }` health check, so the worker URL no longer errors and you
+  can confirm its vars are set.
+
+### Changed
+- The bundled Email Worker template reads the ingress URL from a
+  `CLOUDFLARE_EMAIL_INGRESS_URL` Worker var instead of a hardcoded URL, so it
+  deploys unchanged across apps/environments.
+- The inbound ingress secret is now `config.ingress_secret` on the gem
+  configuration (defaulting from `CLOUDFLARE_EMAIL_INGRESS_SECRET`), set in the
+  same `configure` block as the other credentials — instead of an ad-hoc env /
+  Rails-credentials lookup in the controller.
+
+### Fixed
+- Read the inbound request body via `request.raw_post`, which is consistent
+  across Puma, Falcon, and Unicorn and nil-safe. The previous `request.body.read`
+  raised on servers (e.g. Falcon) that hand back no body object.
+
 ## [0.1.0] - 2026-06-18
 
 ### Added

data/README.md

@@ -1,13 +1,15 @@
 # Cloudflare Email Service
 
-A small Ruby client for sending transactional email through the
-[Cloudflare Email Service](https://developers.cloudflare.com/email-service/).
+A small Ruby client for the [Cloudflare Email Service](https://developers.cloudflare.com/email-service/):
+send transactional email from any Ruby app, and — in Rails — receive it through
+Action Mailbox.
 
-Two interchangeable transports: **REST** (default — zero dependencies, just
-`net/http`) and **SMTP** (optional, via the [`mail`](https://rubygems.org/gems/mail)
-gem). Same `send_email` call either way; pick the transport in configuration.
+Sending uses one of two interchangeable transports: **REST** (the default — zero
+dependencies, just `net/http`) or **SMTP** (optional, via the
+[`mail`](https://rubygems.org/gems/mail) gem). The same `send_email` call works
+for both.
 
-Developed at [Primevise](https://primevise.com).
+Battle-tested at [Rinkta](https://rinkta.com). Developed at [Primevise](https://primevise.com).
 
 <a href="https://github.com/elvinaspredkelis/cloudflare-email_service/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/elvinaspredkelis/cloudflare-email_service/actions/workflows/ci.yml/badge.svg"></a>
 <a href="https://rubygems.org/gems/cloudflare-email_service"><img alt="Gem Version" src="https://img.shields.io/gem/v/cloudflare-email_service?color=10b981&include_prereleases&logo=ruby&logoColor=f43f5e"></a>
@@ -17,19 +19,19 @@ Developed at [Primevise](https://primevise.com).
 
 ## Installation
 
-```
+```sh
 bundle add cloudflare-email_service
 ```
 
 Requires Ruby 3.2+. For the SMTP transport, also add the `mail` gem:
 
-```
+```sh
 bundle add mail
 ```
 
 ---
 
-## Usage
+## Quick start
 
 Configure once with your Cloudflare API token (plus an account id for REST),
 then send:
@@ -54,28 +56,15 @@ response.success?   # => true
 response.delivered  # => ["recipient@example.com"]
 ```
 
-`Response` also exposes `#queued`, `#permanent_bounces`, `#errors`, `#status`,
-and the raw parsed `#body`.
-
-> [!TIP]
-> `from`, `to`, `cc`, `bcc`, and `reply_to` accept a string
-> (`"a@x.com"` or `"Display Name <a@x.com>"`), a hash (`{ email:, name: }`), or —
-> for `to` / `cc` / `bcc` — an array of either. Add files with
-> `attachments: [{ content: Base64.strict_encode64(bytes), filename:, type: }]`
-> and arbitrary headers with `headers: { "In-Reply-To" => "<id>" }`.
-
-> [!CAUTION]
-> The total message size (body + attachments) must not exceed **5 MiB**.
-
-Skip the global config and pass credentials per client when you send from more
-than one account:
+Need to send from more than one account? Skip the global config and build a
+client directly:
 
 ```ruby
 Cloudflare::EmailService::Client.new(account_id: "...", api_token: "...")  # REST
 Cloudflare::EmailService::SMTPClient.new(api_token: "...")                 # SMTP
 ```
 
-#### Credentials
+### Credentials
 
 Set credentials in `configure` (above) or through the environment:
 
@@ -89,11 +78,50 @@ no account id.
 
 ---
 
+## Messages
+
+`send_email` accepts these keywords (`from`, `to`, `subject`, and one of
+`html` / `text` are required):
+
+| Keyword | Description |
+| ------- | ----------- |
+| `from` | Sender. A string or `{ email:, name: }` hash. |
+| `to` / `cc` / `bcc` | Recipients. A string, a hash, or an array of either. |
+| `reply_to` | Reply-To address (string or hash). |
+| `subject` | Subject line. |
+| `html` / `text` | Body. Provide either or both. |
+| `attachments` | Array of `{ content:, filename:, type:, disposition: }`. |
+| `headers` | Hash of custom headers, e.g. `{ "In-Reply-To" => "<id>" }`. |
+
+In an address hash, `:address` aliases `:email`. Attachment `content` is Base64:
+
+```ruby
+Cloudflare::EmailService.send_email(
+  from: "reports@yourdomain.com",
+  to: "recipient@example.com",
+  subject: "Your report",
+  text: "See attached.",
+  attachments: [
+    {
+      content: Base64.strict_encode64(File.read("report.pdf")),
+      filename: "report.pdf",
+      type: "application/pdf",
+      disposition: "attachment", # optional
+    },
+  ],
+)
+```
+
+> [!CAUTION]
+> The total message size (body + attachments) must not exceed **5 MiB**.
+
+---
+
 ## Transports
 
 Both transports accept the same `send_email` call and return the same
-`Response` — they differ only in how the message reaches Cloudflare. Choose one
-with `config.transport`.
+[`Response`](#response) — they differ only in how the message reaches Cloudflare.
+Choose one with `config.transport`.
 
 **REST** (`:rest`, the default) posts JSON to the Cloudflare API over HTTPS
 using only `net/http` from the standard library — no MIME assembly, no gems.
@@ -130,8 +158,8 @@ config.action_mailer.delivery_method = :cloudflare
 ```
 
 Credentials come from `CLOUDFLARE_ACCOUNT_ID` / `CLOUDFLARE_API_TOKEN` in the
-environment. To set them in code (or pick the SMTP transport), add an
-initializer:
+environment. To set them in code, choose the SMTP transport, or receive inbound
+mail, use a single initializer:
 
 ```ruby
 # config/initializers/cloudflare_email_service.rb
@@ -139,6 +167,15 @@ Cloudflare::EmailService.configure do |c|
   c.account_id = Rails.application.credentials.dig(:cloudflare, :account_id)
   c.api_token  = Rails.application.credentials.dig(:cloudflare, :api_token)
   # c.transport = :smtp   # optional; defaults to :rest
+
+  # Inbound (Action Mailbox) only — must match the Worker's signing secret:
+  c.ingress_secret = Rails.application.credentials.dig(:cloudflare, :ingress_secret)
+end
+
+# Inbound (Action Mailbox) only — load the :cloudflare ingress. In `to_prepare`
+# so its controller superclass is autoloadable regardless of boot order.
+Rails.application.config.to_prepare do
+  require "cloudflare/email_service/action_mailbox"
 end
 ```
 
@@ -161,17 +198,10 @@ so first enable
 on your domain (it adds the MX/SPF/DKIM records). Then a Worker forwards each
 message to a `:cloudflare`
 [Action Mailbox](https://guides.rubyonrails.org/action_mailbox_basics.html)
-ingress that ships with the gem. Three steps:
+ingress that ships with the gem. The initializer above loads the ingress and
+sets the signing secret; then:
 
-**1. Require the ingress** — opt-in, so it stays out of send-only apps:
-
-```ruby
-# config/initializers/cloudflare_email_service.rb
-require "cloudflare/email_service/action_mailbox"
-```
-
-**2. Select it** and set the shared signing secret — either
-`CLOUDFLARE_EMAIL_INGRESS_SECRET` or the `cloudflare.ingress_secret` credential:
+**1. Select the ingress:**
 
 ```ruby
 # config/environments/production.rb
@@ -180,21 +210,42 @@ config.action_mailbox.ingress = :cloudflare
 
 The route `POST /rails/action_mailbox/cloudflare/inbound_emails` is registered
 for you, and every request is verified by an HMAC-SHA256 signature with replay
-protection.
+protection. The ingress reads the body via `request.raw_post`, so it works under
+any Rack server — Puma, Falcon, or Unicorn.
 
-**3. Deploy an Email Worker** that signs and forwards each message, and bind it
-to an Email Routing rule (or catch-all). One ships with the gem — set your app
-URL and give it the same `CLOUDFLARE_EMAIL_INGRESS_SECRET`, then deploy:
+**2. Deploy an Email Worker** that signs and forwards each message, and bind it
+to an Email Routing rule (or catch-all). One ships with the gem — deploy it
+unchanged and set two Worker vars: `CLOUDFLARE_EMAIL_INGRESS_URL` (the route
+above) and `CLOUDFLARE_EMAIL_INGRESS_SECRET` (matching the app):
 
 - In this repo: [`templates/cloudflare_email_worker.js`](templates/cloudflare_email_worker.js)
 - From the installed gem: `Cloudflare::EmailService.worker_template_path`
 
+Visiting the worker's URL returns a `{ ok, configured }` health check — a quick
+way to confirm it's deployed and both vars are set.
+
 > [!NOTE]
 > The Worker sends `Content-Type: message/rfc822`; the ingress rejects anything
 > else with `415 Unsupported Media Type`.
 
 ---
 
+## Response
+
+`send_email` returns a `Cloudflare::EmailService::Response`:
+
+| Method               | Returns                                       |
+| -------------------- | --------------------------------------------- |
+| `#success?`          | `true` when Cloudflare accepted the request   |
+| `#delivered`         | array of accepted recipient addresses         |
+| `#queued`            | array of queued recipient addresses           |
+| `#permanent_bounces` | array of permanently bounced addresses        |
+| `#errors`            | array of Cloudflare error objects             |
+| `#status`            | HTTP status code                              |
+| `#body`              | the raw parsed JSON body                      |
+
+---
+
 ## Errors
 
 Non-2xx responses (and unsuccessful payloads) raise a typed error — every one a
@@ -210,19 +261,38 @@ subclass of `Cloudflare::EmailService::Error`:
 | `ServerError`         | HTTP 5xx                                    |
 | `NetworkError`        | connection, timeout, and TLS failures      |
 
-API errors also carry `#status` and `#errors` for context.
+The API errors (`AuthenticationError`, `RequestError`, `RateLimitError`,
+`ServerError`) inherit from `APIError` and carry `#status` and `#errors`:
+
+```ruby
+begin
+  Cloudflare::EmailService.send_email(from: "a@x.com", to: "b@y.com", subject: "Hi", text: "Hello")
+rescue Cloudflare::EmailService::APIError => e
+  e.status   # => 403
+  e.errors   # => [{ "code" => 10000, "message" => "Authentication error" }]
+  e.message  # => "[10000] Authentication error"
+end
+```
 
 ---
 
 ## Development
 
 ```sh
+bundle install            # install dependencies
 bundle exec rake test     # run the Minitest suite
 bundle exec rubocop       # lint
 ```
 
 ---
 
+## Contributing
+
+Bug reports and pull requests welcome on
+[GitHub](https://github.com/elvinaspredkelis/cloudflare-email_service).
+
+---
+
 ## License
 
 Released under the [MIT License](LICENSE.txt).

data/lib/cloudflare/email_service/action_mailbox.rb

@@ -4,9 +4,11 @@ require "cloudflare/email_service"
 require "cloudflare/email_service/inbound"
 
 # Opt-in Action Mailbox ingress: forwards inbound mail from a Cloudflare Email
-# Worker into Action Mailbox. Not loaded by the core gem — require it explicitly
-# and select it with `config.action_mailbox.ingress = :cloudflare`. The route is
-# registered automatically. See the README for setup and the Worker snippet.
+# Worker into Action Mailbox. Not loaded by the core gem — require it from an
+# initializer (inside `Rails.application.config.to_prepare`, so the controller's
+# superclass is autoloadable) and select it with
+# `config.action_mailbox.ingress = :cloudflare`. The route is registered
+# automatically. See the README for setup and the Worker snippet.
 if defined?(ActionMailbox)
   module ActionMailbox
     module Ingresses
@@ -49,18 +51,17 @@ if defined?(ActionMailbox)
           end
 
           # Read once, as binary, so the bytes match exactly what the Worker
-          # signed and what Action Mailbox stores.
+          # signed and what Action Mailbox stores. `raw_post` is ActionDispatch's
+          # body reader — consistent across Puma, Falcon, and Unicorn, and nil-safe
+          # (`request.body` can be nil/non-rewindable on some servers).
           def raw_body
-            @raw_body ||= begin
-              request.body.rewind if request.body.respond_to?(:rewind)
-              request.body.read.to_s.b
-            end
+            @raw_body ||= request.raw_post.to_s.b
           end
 
-          # Shared HMAC secret, from the environment or Rails credentials.
+          # Shared HMAC secret, from the gem configuration
+          # (`config.ingress_secret` / CLOUDFLARE_EMAIL_INGRESS_SECRET).
           def signing_secret
-            ENV["CLOUDFLARE_EMAIL_INGRESS_SECRET"] ||
-              ::Rails.application.credentials.dig(:cloudflare, :ingress_secret).to_s
+            ::Cloudflare::EmailService.configuration.ingress_secret.to_s
           end
         end
       end

data/lib/cloudflare/email_service/configuration.rb

@@ -29,6 +29,10 @@ module Cloudflare
       attr_accessor :open_timeout
       # @return [Integer] read timeout in seconds.
       attr_accessor :timeout
+      # @return [String, nil] HMAC secret used to verify inbound Action Mailbox
+      #   requests (CLOUDFLARE_EMAIL_INGRESS_SECRET). Must match the value the
+      #   Cloudflare Email Worker signs with.
+      attr_accessor :ingress_secret
 
       def initialize
         @transport = ENV.fetch("CLOUDFLARE_EMAIL_TRANSPORT", "rest").to_sym
@@ -39,6 +43,7 @@ module Cloudflare
         @smtp_port = Integer(ENV.fetch("CLOUDFLARE_SMTP_PORT", DEFAULT_SMTP_PORT))
         @open_timeout = DEFAULT_TIMEOUT
         @timeout = DEFAULT_TIMEOUT
+        @ingress_secret = ENV.fetch("CLOUDFLARE_EMAIL_INGRESS_SECRET", nil)
       end
     end
   end

data/lib/cloudflare/email_service/version.rb

@@ -2,6 +2,6 @@
 
 module Cloudflare
   module EmailService
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/templates/cloudflare_email_worker.js

@@ -1,30 +1,44 @@
 // Cloudflare Email Worker for cloudflare-email_service inbound (Action Mailbox).
 //
-// Forwards each received message to your Rails app's :cloudflare ingress, signed
-// with HMAC-SHA256 over "<timestamp>.<body>" so the ingress can verify it and
-// reject replays.
+// - email(): forwards each received message to your Rails app's :cloudflare
+//   ingress, signed with HMAC-SHA256 over "<timestamp>.<body>".
+// - fetch(): a GET health check. Email Workers have no HTTP API, so visiting the
+//   worker URL would otherwise error; this returns whether the vars are set.
 //
-// Setup:
-//   1. Replace the URL below with your app's host.
-//   2. Set CLOUDFLARE_EMAIL_INGRESS_SECRET as a Worker secret, matching the
-//      app's CLOUDFLARE_EMAIL_INGRESS_SECRET (or cloudflare.ingress_secret).
-//   3. Bind the Worker to your Email Routing rule and deploy (e.g. wrangler).
+// Set two Worker secrets/vars, then bind the Worker to an Email Routing rule and
+// deploy (e.g. wrangler):
+//   - CLOUDFLARE_EMAIL_INGRESS_URL    full URL of the ingress, e.g.
+//       https://your-app.example.com/rails/action_mailbox/cloudflare/inbound_emails
+//   - CLOUDFLARE_EMAIL_INGRESS_SECRET same value as the app's
+//       config.ingress_secret (CLOUDFLARE_EMAIL_INGRESS_SECRET)
 
 export default {
+  async fetch(_request, env) {
+    const configured = Boolean(
+      env.CLOUDFLARE_EMAIL_INGRESS_URL && env.CLOUDFLARE_EMAIL_INGRESS_SECRET,
+    );
+    return Response.json({ ok: true, configured });
+  },
+
   async email(message, env) {
+    const { CLOUDFLARE_EMAIL_INGRESS_URL: url, CLOUDFLARE_EMAIL_INGRESS_SECRET: secret } = env;
+    if (!url || !secret) {
+      return message.setReject("CLOUDFLARE_EMAIL_INGRESS_URL / _SECRET not configured");
+    }
+
     // arrayBuffer (not text) preserves the raw bytes of non-UTF-8 messages.
     const raw = new Uint8Array(await new Response(message.raw).arrayBuffer());
     const ts = Math.floor(Date.now() / 1000).toString();
 
     const key = await crypto.subtle.importKey(
-      "raw", new TextEncoder().encode(env.CLOUDFLARE_EMAIL_INGRESS_SECRET),
+      "raw", new TextEncoder().encode(secret),
       { name: "HMAC", hash: "SHA-256" }, false, ["sign"],
     );
     const signed = new Uint8Array([...new TextEncoder().encode(ts + "."), ...raw]);
     const digest = await crypto.subtle.sign("HMAC", key, signed);
     const sig = [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
 
-    const response = await fetch("https://your-app.example.com/rails/action_mailbox/cloudflare/inbound_emails", {
+    const response = await fetch(url, {
       method: "POST",
       headers: {
         "Content-Type": "message/rfc822",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cloudflare-email_service
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Elvinas Predkelis