cloudflare-email_service 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e223425c0900fe465d1f698fa9a1cd8ae030e2e48c2c658216a0a2a87605ec12
+  data.tar.gz: ec9b3749cccfd800c335e16ec9b1c044d97fd993524abd44f578686cff03eaba
+SHA512:
+  metadata.gz: 76f656827c724a23ae557cb71a375eeb1cf4a85497a2d260733c7f775a7d520375fc80fbb3f19db7ec24374dd8aca018b4d3a4ddeef838048a563f1118a741e3
+  data.tar.gz: ee6b18139c3eef6372ec19a916317b76819d6ea2ee5d605aaa727d784ce2fe0abfea5944f618b369398af4c47eabc06b360727d2edd1d0178eb7f5175289ee3c

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/), and this project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [0.0.1] - 2026-06-17
+
+### Added
+- Initial release.
+- REST transport: `Cloudflare::EmailService::Client#send_email` sends via
+  `POST /accounts/{account_id}/email/sending/send` using only the standard
+  library — zero runtime dependencies.
+- SMTP transport: `Cloudflare::EmailService::SMTPClient#send_email` submits over
+  `smtp.mx.cloudflare.net:465` (implicit TLS). MIME is built with the `mail`
+  gem, an optional dependency loaded lazily only when SMTP is used.
+- Transport selection via `config.transport = :rest | :smtp`; `send_email`,
+  `Response`, and the error classes are identical across transports.
+- Optional, opt-in Rails integration (`require "cloudflare/email_service/rails"`)
+  registering a `:cloudflare` ActionMailer delivery method. The core gem stays
+  Rails-free; nothing Rails-related loads unless the adapter is required.
+- `Cloudflare::EmailService.smtp_settings` helper for pointing ActionMailer's
+  built-in `:smtp` delivery (or any `mail` client) at Cloudflare.
+- Global configuration via `Cloudflare::EmailService.configure` and the
+  `Cloudflare::EmailService.send_email` convenience method.
+- Address normalization for strings, `{ email:, name: }` hashes, and arrays
+  (to / cc / bcc).
+- Support for `reply_to`, attachments, and custom headers.
+- Typed error classes (`ConfigurationError`, `ValidationError`,
+  `AuthenticationError`, `RequestError`, `RateLimitError`, `ServerError`,
+  `NetworkError`) and a `Response` wrapper.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elvinas Predkelis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,285 @@
+# cloudflare-email_service
+
+[![CI](https://github.com/elvinaspredkelis/cloudflare-email_service/actions/workflows/ci.yml/badge.svg)](https://github.com/elvinaspredkelis/cloudflare-email_service/actions/workflows/ci.yml)
+
+A small Ruby client for sending transactional email through the
+[Cloudflare Email Service](https://developers.cloudflare.com/email-service/),
+over either of two transports:
+
+- **REST** (default) — talks to the send endpoint directly with the Ruby
+  standard library (`net/http`). **Zero dependencies.** No Rails, no HTTP gems.
+
+  ```
+  POST https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/send
+  ```
+
+- **SMTP** — submits over `smtp.mx.cloudflare.net:465` (implicit TLS). MIME is
+  built with the [`mail`](https://rubygems.org/gems/mail) gem, which is an
+  **optional** dependency loaded only when you actually use SMTP.
+
+Same `send_email` call either way — pick the transport in configuration.
+
+## Installation
+
+Add it to your `Gemfile`:
+
+```ruby
+gem "cloudflare-email_service"
+
+# Only if you use the SMTP transport:
+gem "mail"
+```
+
+Then run `bundle install`. Or install directly:
+
+```sh
+gem install cloudflare-email_service
+```
+
+Requires Ruby 3.1+.
+
+## Credentials
+
+You need a Cloudflare **API token**, plus an **account id** for the REST
+transport. Token scope depends on the transport:
+
+| Transport | account id | API token scope        |
+| --------- | ---------- | ---------------------- |
+| REST      | required   | `Email Sending: Send`  |
+| SMTP      | not used   | `Email Sending: Edit`  |
+
+Provide them through the environment:
+
+```sh
+export CLOUDFLARE_ACCOUNT_ID="your-account-id"   # REST only
+export CLOUDFLARE_API_TOKEN="your-api-token"
+export CLOUDFLARE_EMAIL_TRANSPORT="rest"         # or "smtp" (default: rest)
+```
+
+or explicitly in code (see below).
+
+## Choosing a transport
+
+The transport is selected once, in configuration; everything else — the
+`send_email` call, the returned `Response`, the error classes — is identical.
+
+```ruby
+# REST (default) — zero dependencies
+Cloudflare::EmailService.configure do |config|
+  config.transport  = :rest
+  config.account_id = ENV["CLOUDFLARE_ACCOUNT_ID"]
+  config.api_token  = ENV["CLOUDFLARE_API_TOKEN"]
+end
+
+# SMTP — requires the `mail` gem
+Cloudflare::EmailService.configure do |config|
+  config.transport = :smtp
+  config.api_token = ENV["CLOUDFLARE_API_TOKEN"] # account_id not needed
+end
+```
+
+SMTP defaults to `smtp.mx.cloudflare.net:465` (implicit TLS); override with
+`config.smtp_host` / `config.smtp_port` if needed. If you select `:smtp` without
+the `mail` gem installed, a `ConfigurationError` is raised telling you to add it.
+
+You can also build a transport client directly:
+
+```ruby
+Cloudflare::EmailService::Client.new(account_id: "...", api_token: "...")     # REST
+Cloudflare::EmailService::SMTPClient.new(api_token: "...")                    # SMTP
+```
+
+## Usage
+
+### Global configuration
+
+```ruby
+require "cloudflare/email_service"
+
+Cloudflare::EmailService.configure do |config|
+  config.account_id = ENV["CLOUDFLARE_ACCOUNT_ID"]
+  config.api_token  = ENV["CLOUDFLARE_API_TOKEN"]
+  config.timeout    = 30 # seconds (optional)
+end
+
+response = Cloudflare::EmailService.send_email(
+  from: "welcome@yourdomain.com",
+  to: "recipient@example.com",
+  subject: "Welcome!",
+  html: "<h1>Welcome</h1><p>Thanks for signing up.</p>",
+  text: "Welcome! Thanks for signing up.",
+)
+
+response.success?   # => true
+response.delivered  # => ["recipient@example.com"]
+```
+
+### Explicit client
+
+Skip the global configuration and pass credentials per client — handy when you
+send from more than one account:
+
+```ruby
+client = Cloudflare::EmailService::Client.new(
+  account_id: ENV["CLOUDFLARE_ACCOUNT_ID"],
+  api_token: ENV["CLOUDFLARE_API_TOKEN"],
+)
+
+client.send_email(
+  from: "welcome@yourdomain.com",
+  to: "recipient@example.com",
+  subject: "Welcome!",
+  text: "Thanks for signing up.",
+)
+```
+
+### Addresses
+
+`from`, `to`, `cc`, `bcc`, and `reply_to` accept:
+
+- a plain string — `"user@example.com"` or `"Display Name <user@example.com>"`
+- a hash — `{ email: "user@example.com", name: "Display Name" }`
+  (`:address` is accepted as an alias for `:email`)
+- `to` / `cc` / `bcc` also accept an array of any of the above
+
+```ruby
+Cloudflare::EmailService.send_email(
+  from: { email: "welcome@yourdomain.com", name: "Acme" },
+  to: ["a@example.com", { email: "b@example.com", name: "B" }],
+  cc: "team@yourdomain.com",
+  reply_to: "support@yourdomain.com",
+  subject: "Hi",
+  text: "Hello",
+)
+```
+
+### Attachments
+
+Attachments are base64-encoded. The total message size (body + attachments)
+must not exceed **5 MiB**.
+
+```ruby
+require "base64"
+
+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
+    },
+  ],
+)
+```
+
+### Custom headers
+
+```ruby
+Cloudflare::EmailService.send_email(
+  from: "a@yourdomain.com",
+  to: "b@example.com",
+  subject: "Re: thread",
+  text: "Reply body",
+  headers: { "In-Reply-To" => "<msg-123@yourdomain.com>" },
+)
+```
+
+## Rails / ActionMailer (optional)
+
+The core gem is Rails-agnostic. Rails integration is **opt-in** and loaded only
+when you require it — it registers a `:cloudflare` ActionMailer delivery method
+backed by whichever transport you configured.
+
+```ruby
+# config/initializers/cloudflare_email_service.rb
+require "cloudflare/email_service/rails"
+
+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
+end
+```
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :cloudflare
+```
+
+Your mailers then send through Cloudflare unchanged:
+
+```ruby
+class WelcomeMailer < ApplicationMailer
+  def welcome(user)
+    mail(from: "welcome@yourdomain.com", to: user.email, subject: "Welcome")
+  end
+end
+```
+
+Prefer ActionMailer's built-in SMTP delivery instead? Point it at Cloudflare
+with the provided settings helper — no adapter required:
+
+```ruby
+config.action_mailer.delivery_method = :smtp
+config.action_mailer.smtp_settings   = Cloudflare::EmailService.smtp_settings(
+  api_token: Rails.application.credentials.dig(:cloudflare, :api_token),
+)
+```
+
+## 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`             | the HTTP status code                               |
+| `#body`               | the raw parsed JSON body                           |
+
+## Errors
+
+Non-2xx responses (and unsuccessful payloads) raise a typed error. All inherit
+from `Cloudflare::EmailService::Error`:
+
+| Class                  | When                                          |
+| ---------------------- | --------------------------------------------- |
+| `ConfigurationError`   | missing `account_id` / `api_token`            |
+| `ValidationError`      | the message is missing required fields        |
+| `AuthenticationError`  | HTTP 401 / 403                                |
+| `RequestError`         | HTTP 400 / 422 and other 4xx                  |
+| `RateLimitError`       | HTTP 429                                      |
+| `ServerError`          | HTTP 5xx                                      |
+| `NetworkError`         | connection failures and timeouts              |
+
+API errors carry extra context:
+
+```ruby
+begin
+  Cloudflare::EmailService.send_email(...)
+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
+bundle exec rake test     # run the Minitest suite
+bundle exec rubocop       # lint
+```
+
+## License
+
+Released under the [MIT License](LICENSE.txt).

data/lib/cloudflare/email_service/client.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Cloudflare
+  module EmailService
+    # HTTP client for the Cloudflare Email Service send endpoint.
+    #
+    #   client = Cloudflare::EmailService::Client.new(
+    #     account_id: "...", api_token: "..."
+    #   )
+    #   client.send_email(from: "a@x.com", to: "b@y.com",
+    #                     subject: "Hi", text: "Hello")
+    class Client
+      attr_reader :account_id, :api_token, :api_base, :open_timeout, :timeout
+
+      def initialize(account_id: nil, api_token: nil, api_base: nil,
+                     open_timeout: nil, timeout: nil)
+        config = EmailService.configuration
+        @account_id = account_id || config.account_id
+        @api_token = api_token || config.api_token
+        @api_base = api_base || config.api_base
+        @open_timeout = open_timeout || config.open_timeout
+        @timeout = timeout || config.timeout
+
+        raise ConfigurationError, "no account_id configured" if @account_id.to_s.empty?
+        raise ConfigurationError, "no api_token configured" if @api_token.to_s.empty?
+      end
+
+      # Builds and sends a message. Accepts the same keyword arguments as
+      # {Message#initialize}.
+      # @return [Response]
+      def send_email(**kwargs)
+        deliver(Message.new(**kwargs))
+      end
+
+      # Sends a pre-built {Message}.
+      # @return [Response]
+      def deliver(message)
+        post(send_uri, message.validate!.to_h)
+      end
+
+      private
+
+      def send_uri
+        URI("#{api_base}/accounts/#{account_id}/email/sending/send")
+      end
+
+      def post(uri, payload)
+        request = Net::HTTP::Post.new(uri)
+        request["Authorization"] = "Bearer #{api_token}"
+        request["Content-Type"] = "application/json"
+        request["Accept"] = "application/json"
+        request["User-Agent"] = "cloudflare-email_service/#{VERSION} (ruby)"
+        request.body = JSON.generate(payload)
+
+        handle(http(uri).request(request))
+      rescue Timeout::Error, Errno::ECONNREFUSED, Errno::ECONNRESET,
+             Errno::EHOSTUNREACH, Errno::ETIMEDOUT, SocketError, IOError => e
+        raise NetworkError, "request failed: #{e.class}: #{e.message}"
+      end
+
+      def http(uri)
+        client = Net::HTTP.new(uri.host, uri.port)
+        client.use_ssl = uri.scheme == "https"
+        client.open_timeout = open_timeout
+        client.read_timeout = timeout
+        client
+      end
+
+      def handle(http_response)
+        status = http_response.code.to_i
+        response = Response.new(status: status, body: parse(http_response.body))
+        return response if status.between?(200, 299) && response.success?
+
+        raise_error(status, response)
+      end
+
+      def parse(raw)
+        return {} if raw.nil? || raw.empty?
+
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        { "success" => false, "errors" => [{ "message" => "non-JSON response body" }] }
+      end
+
+      def raise_error(status, response)
+        raise error_class_for(status).new(
+          summarize(response.errors),
+          status: status,
+          errors: response.errors,
+          response: response,
+        )
+      end
+
+      def error_class_for(status)
+        case status
+        when 401, 403 then AuthenticationError
+        when 429 then RateLimitError
+        when 500..599 then ServerError
+        else RequestError
+        end
+      end
+
+      # Collapses the Cloudflare "errors" array into a single human-readable line,
+      # prefixing each entry with its numeric code when one is present.
+      def summarize(errors)
+        lines = Array(errors).filter_map { |entry| describe_error(entry) }
+        lines.empty? ? "Cloudflare rejected the request" : lines.join(" | ")
+      end
+
+      def describe_error(entry)
+        return entry.to_s.empty? ? nil : entry.to_s unless entry.is_a?(Hash)
+
+        code = entry["code"]
+        text = entry["message"].to_s
+        return nil if text.empty? && code.nil?
+
+        code ? "[#{code}] #{text}".strip : text
+      end
+    end
+  end
+end

data/lib/cloudflare/email_service/configuration.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Cloudflare
+  module EmailService
+    # Holds the transport selection, credentials, and connection options used
+    # when a client is built without explicit arguments. Defaults are read from
+    # the environment.
+    class Configuration
+      DEFAULT_API_BASE = "https://api.cloudflare.com/client/v4"
+      DEFAULT_SMTP_HOST = "smtp.mx.cloudflare.net"
+      DEFAULT_SMTP_PORT = 465
+      DEFAULT_TIMEOUT = 30
+
+      # @return [Symbol] :rest (default) or :smtp.
+      attr_accessor :transport
+      # @return [String, nil] Cloudflare account id (CLOUDFLARE_ACCOUNT_ID).
+      #   Required for the REST transport; unused by SMTP.
+      attr_accessor :account_id
+      # @return [String, nil] API token (CLOUDFLARE_API_TOKEN). REST needs the
+      #   "Email Sending: Send" scope; SMTP needs "Email Sending: Edit".
+      attr_accessor :api_token
+      # @return [String] base URL of the Cloudflare REST API.
+      attr_accessor :api_base
+      # @return [String] SMTP submission host.
+      attr_accessor :smtp_host
+      # @return [Integer] SMTP submission port (465, implicit TLS).
+      attr_accessor :smtp_port
+      # @return [Integer] connection-open timeout in seconds.
+      attr_accessor :open_timeout
+      # @return [Integer] read timeout in seconds.
+      attr_accessor :timeout
+
+      def initialize
+        @transport = ENV.fetch("CLOUDFLARE_EMAIL_TRANSPORT", "rest").to_sym
+        @account_id = ENV.fetch("CLOUDFLARE_ACCOUNT_ID", nil)
+        @api_token = ENV.fetch("CLOUDFLARE_API_TOKEN", nil)
+        @api_base = ENV.fetch("CLOUDFLARE_API_BASE", DEFAULT_API_BASE)
+        @smtp_host = ENV.fetch("CLOUDFLARE_SMTP_HOST", DEFAULT_SMTP_HOST)
+        @smtp_port = Integer(ENV.fetch("CLOUDFLARE_SMTP_PORT", DEFAULT_SMTP_PORT))
+        @open_timeout = DEFAULT_TIMEOUT
+        @timeout = DEFAULT_TIMEOUT
+      end
+    end
+  end
+end

data/lib/cloudflare/email_service/errors.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Cloudflare
+  module EmailService
+    # Base class for every error raised by this gem.
+    class Error < StandardError; end
+
+    # Raised when required configuration (account_id / api_token) is missing.
+    class ConfigurationError < Error; end
+
+    # Raised when a message is missing required fields before it is sent.
+    class ValidationError < Error; end
+
+    # Base class for errors returned by the Cloudflare API.
+    class APIError < Error
+      # @return [Integer, nil] the HTTP status code.
+      attr_reader :status
+      # @return [Array] the Cloudflare "errors" array, when present.
+      attr_reader :errors
+      # @return [Response, nil] the wrapped API response.
+      attr_reader :response
+
+      def initialize(message = nil, status: nil, errors: nil, response: nil)
+        @status = status
+        @errors = errors || []
+        @response = response
+        super(message)
+      end
+    end
+
+    # 401 / 403 — missing, invalid, or insufficiently scoped API token.
+    class AuthenticationError < APIError; end
+
+    # 400 / 422 and other 4xx — the request was rejected as invalid.
+    class RequestError < APIError; end
+
+    # 429 — too many requests.
+    class RateLimitError < APIError; end
+
+    # 5xx — Cloudflare-side failure.
+    class ServerError < APIError; end
+
+    # Connection refused/reset, timeouts, DNS failures, etc.
+    class NetworkError < Error; end
+  end
+end

data/lib/cloudflare/email_service/message.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Cloudflare
+  module EmailService
+    # Validates and serializes an outbound email into the JSON payload expected
+    # by the Cloudflare Email Service "send" endpoint.
+    #
+    # Addresses may be given as:
+    #   * a String — "user@example.com" or "Display Name <user@example.com>"
+    #   * a Hash   — { email: "user@example.com", name: "Display Name" }
+    #                (:address is accepted as an alias for :email)
+    #   * an Array of any of the above (for to / cc / bcc)
+    class Message
+      attr_reader :from, :to, :cc, :bcc, :reply_to, :subject,
+                  :html, :text, :attachments, :headers
+
+      def initialize(from:, to:, subject:, html: nil, text: nil, cc: nil,
+                     bcc: nil, reply_to: nil, attachments: nil, headers: nil)
+        @from = from
+        @to = to
+        @cc = cc
+        @bcc = bcc
+        @reply_to = reply_to
+        @subject = subject
+        @html = html
+        @text = text
+        @attachments = attachments
+        @headers = headers
+      end
+
+      # @return [self]
+      # @raise [ValidationError] when the message cannot be sent.
+      def validate!
+        raise ValidationError, "from is required" if blank?(from)
+        raise ValidationError, "to is required" if blank?(to)
+        raise ValidationError, "subject is required" if blank?(subject)
+        if blank?(html) && blank?(text)
+          raise ValidationError, "provide html and/or text body content"
+        end
+
+        self
+      end
+
+      # @return [Hash] the request body, with nil/empty fields omitted.
+      def to_h
+        {
+          from: normalize_address(from),
+          to: normalize_recipients(to),
+          subject: subject,
+          cc: optional_recipients(cc),
+          bcc: optional_recipients(bcc),
+          reply_to: optional_address(reply_to),
+          html: presence(html),
+          text: presence(text),
+          headers: presence(headers),
+          attachments: optional_attachments(attachments),
+        }.compact
+      end
+
+      private
+
+      def optional_recipients(value)
+        blank?(value) ? nil : normalize_recipients(value)
+      end
+
+      def optional_address(value)
+        blank?(value) ? nil : normalize_address(value)
+      end
+
+      def optional_attachments(value)
+        blank?(value) ? nil : value.map { |a| normalize_attachment(a) }
+      end
+
+      def presence(value)
+        blank?(value) ? nil : value
+      end
+
+      def normalize_recipients(value)
+        list = value.is_a?(Array) ? value : [value]
+        normalized = list.reject { |v| blank?(v) }.map { |v| normalize_address(v) }
+        normalized.length == 1 ? normalized.first : normalized
+      end
+
+      def normalize_address(value)
+        return value if value.is_a?(String)
+        raise ValidationError, "unsupported address: #{value.inspect}" unless value.is_a?(Hash)
+
+        email = address_field(value, :email, :address)
+        raise ValidationError, "address hash must include an :email value" if blank?(email)
+
+        name = address_field(value, :name)
+        name ? "#{name} <#{email}>" : email
+      end
+
+      def address_field(hash, *keys)
+        keys.each do |key|
+          candidate = hash[key] || hash[key.to_s]
+          return candidate unless blank?(candidate)
+        end
+        nil
+      end
+
+      def normalize_attachment(att)
+        raise ValidationError, "attachment must be a Hash" unless att.is_a?(Hash)
+
+        h = att.transform_keys(&:to_sym)
+        raise ValidationError, "attachment requires :content" if blank?(h[:content])
+        raise ValidationError, "attachment requires :filename" if blank?(h[:filename])
+
+        out = { content: h[:content], filename: h[:filename] }
+        out[:type] = h[:type] if h[:type]
+        out[:disposition] = h[:disposition] if h[:disposition]
+        out
+      end
+
+      def blank?(value)
+        value.nil? || (value.respond_to?(:empty?) && value.empty?)
+      end
+    end
+  end
+end

data/lib/cloudflare/email_service/rails.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "cloudflare/email_service"
+
+module Cloudflare
+  module EmailService
+    # Opt-in Rails / ActionMailer integration.
+    #
+    # This file is NOT loaded by the core gem — require it explicitly (e.g. from
+    # an initializer) to register a `:cloudflare` ActionMailer delivery method
+    # backed by the configured transport:
+    #
+    #   # config/initializers/cloudflare_email_service.rb
+    #   require "cloudflare/email_service/rails"
+    #
+    #   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)
+    #   end
+    #
+    #   # config/environments/production.rb
+    #   config.action_mailer.delivery_method = :cloudflare
+    module Rails
+      # Converts an ActionMailer-built Mail::Message into the keyword arguments
+      # accepted by {Message#initialize}.
+      module MessageMapping
+        module_function
+
+        def call(mail)
+          {
+            from: single_address(mail[:from]),
+            to: address_list(mail[:to]),
+            cc: address_list(mail[:cc]),
+            bcc: address_list(mail[:bcc]),
+            reply_to: single_address(mail[:reply_to]),
+            subject: mail.subject,
+            text: text_body(mail),
+            html: html_body(mail),
+            attachments: attachments(mail),
+            headers: custom_headers(mail),
+          }
+        end
+
+        def single_address(field)
+          field&.formatted&.first
+        end
+
+        def address_list(field)
+          field&.formatted
+        end
+
+        def text_body(mail)
+          return mail.text_part.decoded if mail.text_part
+          return nil if mail.multipart? || mail.mime_type == "text/html"
+
+          presence(mail.body.decoded)
+        end
+
+        def html_body(mail)
+          return mail.html_part.decoded if mail.html_part
+          return nil unless mail.mime_type == "text/html"
+
+          presence(mail.body.decoded)
+        end
+
+        def presence(string)
+          string.nil? || string.empty? ? nil : string
+        end
+
+        def attachments(mail)
+          return nil if mail.attachments.empty?
+
+          mail.attachments.map do |part|
+            {
+              content: [part.body.decoded].pack("m0"),
+              filename: part.filename,
+              type: part.mime_type,
+              disposition: part.inline? ? "inline" : "attachment",
+            }
+          end
+        end
+
+        # Forwarded headers: anything custom (X-*) plus threading headers. The
+        # structural headers (From/To/Subject/Content-Type/...) are mapped above.
+        PASSTHROUGH_HEADERS = %w[in-reply-to references].freeze
+
+        def custom_headers(mail)
+          headers = {}
+          mail.header.fields.each do |field|
+            name = field.name.to_s
+            forwardable = name.downcase.start_with?("x-") ||
+                          PASSTHROUGH_HEADERS.include?(name.downcase)
+            headers[name] = field.value if forwardable
+          end
+          headers.empty? ? nil : headers
+        end
+      end
+
+      # ActionMailer delivery method. Credentials and transport come from
+      # {Cloudflare::EmailService.configure}; this just maps the message and
+      # hands it to the configured transport client. Inject `client:` in
+      # settings to override (used in tests).
+      class DeliveryMethod
+        attr_reader :settings
+
+        def initialize(settings = {})
+          @settings = settings || {}
+        end
+
+        # @param mail [Mail::Message] the message ActionMailer built.
+        # @return [Response]
+        def deliver!(mail)
+          client.deliver(Message.new(**MessageMapping.call(mail)))
+        end
+
+        private
+
+        def client
+          @client ||= settings[:client] || EmailService.client
+        end
+      end
+    end
+  end
+end
+
+# Register the delivery method when ActionMailer is present. Guarded so this
+# file is safe to require in a non-Rails process.
+if defined?(ActiveSupport)
+  ActiveSupport.on_load(:action_mailer) do
+    add_delivery_method :cloudflare, Cloudflare::EmailService::Rails::DeliveryMethod
+  end
+elsif defined?(ActionMailer::Base)
+  ActionMailer::Base.add_delivery_method(
+    :cloudflare, Cloudflare::EmailService::Rails::DeliveryMethod
+  )
+end

data/lib/cloudflare/email_service/response.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Cloudflare
+  module EmailService
+    # Wraps the JSON body returned by the Cloudflare send endpoint.
+    class Response
+      # @return [Integer] the HTTP status code.
+      attr_reader :status
+      # @return [Hash] the parsed JSON body.
+      attr_reader :body
+
+      def initialize(status:, body:)
+        @status = status
+        @body = body || {}
+      end
+
+      # @return [Boolean] whether Cloudflare reported success.
+      def success?
+        body["success"] == true
+      end
+
+      # @return [Array] Cloudflare error objects, e.g.
+      #   [{ "code" => 1001, "message" => "..." }].
+      def errors
+        body["errors"] || []
+      end
+
+      # @return [Array] informational messages from the API.
+      def messages
+        body["messages"] || []
+      end
+
+      # @return [Hash] the "result" object.
+      def result
+        body["result"] || {}
+      end
+
+      # @return [Array<String>] addresses Cloudflare accepted for delivery.
+      def delivered
+        result["delivered"] || []
+      end
+
+      # @return [Array<String>] addresses queued for later delivery.
+      def queued
+        result["queued"] || []
+      end
+
+      # @return [Array<String>] addresses that permanently bounced.
+      def permanent_bounces
+        result["permanent_bounces"] || []
+      end
+    end
+  end
+end

data/lib/cloudflare/email_service/smtp_client.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Cloudflare
+  module EmailService
+    # Delivers a {Message} over Cloudflare's SMTP submission endpoint
+    # (smtp.mx.cloudflare.net:465, implicit TLS).
+    #
+    # MIME assembly is delegated to the `mail` gem, which is an *optional*
+    # dependency: it is required lazily the first time an SMTP client is built,
+    # so the REST transport stays dependency-free.
+    #
+    #   client = Cloudflare::EmailService::SMTPClient.new(api_token: "...")
+    #   client.send_email(from: "a@x.com", to: "b@y.com",
+    #                     subject: "Hi", text: "Hello")
+    class SMTPClient
+      # Cloudflare requires the literal string "api_token" as the SMTP username;
+      # the password is the API token itself.
+      SMTP_USERNAME = "api_token"
+
+      attr_reader :api_token, :host, :port, :open_timeout, :timeout
+
+      def initialize(api_token: nil, host: nil, port: nil,
+                     open_timeout: nil, timeout: nil)
+        config = EmailService.configuration
+        @api_token = api_token || config.api_token
+        @host = host || config.smtp_host
+        @port = port || config.smtp_port
+        @open_timeout = open_timeout || config.open_timeout
+        @timeout = timeout || config.timeout
+
+        raise ConfigurationError, "no api_token configured" if @api_token.to_s.empty?
+
+        load_dependencies!
+      end
+
+      # Builds and sends a message. Accepts the same keyword arguments as
+      # {Message#initialize}.
+      # @return [Response]
+      def send_email(**kwargs)
+        deliver(Message.new(**kwargs))
+      end
+
+      # Sends a pre-built {Message} over SMTP.
+      # @return [Response]
+      def deliver(message)
+        message.validate!
+        envelope = build_envelope(message)
+        envelope.delivery_method(:smtp, smtp_settings)
+        transmit(envelope)
+        accepted(envelope)
+      rescue Net::SMTPAuthenticationError => e
+        raise AuthenticationError, e.message
+      rescue Net::SMTPError => e
+        # Every other SMTP protocol error (busy, syntax, fatal, unknown, ...).
+        raise ServerError, e.message
+      rescue Timeout::Error, Errno::ECONNREFUSED, Errno::ECONNRESET,
+             Errno::EHOSTUNREACH, Errno::ETIMEDOUT, SocketError, IOError => e
+        raise NetworkError, "SMTP delivery failed: #{e.class}: #{e.message}"
+      end
+
+      private
+
+      def smtp_settings
+        EmailService.smtp_settings(
+          api_token: api_token, host: host, port: port,
+          open_timeout: open_timeout, timeout: timeout
+        )
+      end
+
+      # Seam for testing: the actual network send lives here on its own.
+      def transmit(envelope)
+        envelope.deliver!
+      end
+
+      def build_envelope(message)
+        body = message.to_h
+        envelope = Mail.new
+        apply_addresses(envelope, body)
+        envelope.subject = body[:subject]
+        apply_body(envelope, body[:text], body[:html])
+        apply_attachments(envelope, body[:attachments])
+        apply_headers(envelope, body[:headers])
+        envelope
+      end
+
+      def apply_addresses(envelope, body)
+        envelope.from = body[:from]
+        envelope.to = body[:to]
+        envelope.cc = body[:cc] if body[:cc]
+        envelope.bcc = body[:bcc] if body[:bcc]
+        envelope.reply_to = body[:reply_to] if body[:reply_to]
+      end
+
+      def apply_body(envelope, text, html)
+        if text && html
+          envelope.text_part = mime_part("text/plain", text)
+          envelope.html_part = mime_part("text/html", html)
+        elsif html
+          envelope.content_type = "text/html; charset=UTF-8"
+          envelope.body = html
+        else
+          envelope.body = text
+        end
+      end
+
+      def mime_part(type, content)
+        part = Mail::Part.new
+        part.content_type = "#{type}; charset=UTF-8"
+        part.body = content
+        part
+      end
+
+      def apply_attachments(envelope, attachments)
+        Array(attachments).each do |attachment|
+          options = {
+            mime_type: attachment[:type],
+            # Our attachment content is base64; hand `mail` the raw bytes.
+            # unpack1("m") is the stdlib base64 decode (no extra dependency).
+            content: attachment[:content].unpack1("m"),
+          }
+          # Honor :disposition so SMTP matches REST (e.g. "inline" vs "attachment").
+          options[:content_disposition] = attachment[:disposition] if attachment[:disposition]
+          envelope.attachments[attachment[:filename]] = options
+        end
+      end
+
+      def apply_headers(envelope, headers)
+        (headers || {}).each { |key, value| envelope[key.to_s] = value }
+      end
+
+      # SMTP gives no delivery report, so synthesize a Response that mirrors the
+      # REST one: every recipient (to + cc + bcc, as bare addresses) is reported
+      # accepted for delivery.
+      def accepted(envelope)
+        Response.new(
+          status: 202,
+          body: {
+            "success" => true,
+            "result" => {
+              "delivered" => envelope.destinations,
+              "queued" => [],
+              "permanent_bounces" => [],
+            },
+          },
+        )
+      end
+
+      def load_dependencies!
+        require "mail"
+        require "net/smtp"
+      rescue LoadError => e
+        raise ConfigurationError,
+              "the SMTP transport needs the `mail` gem — add `gem \"mail\"` " \
+              "to your Gemfile (#{e.message})"
+      end
+    end
+  end
+end

data/lib/cloudflare/email_service/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Cloudflare
+  module EmailService
+    VERSION = "0.0.1"
+  end
+end

data/lib/cloudflare/email_service.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "email_service/version"
+require_relative "email_service/errors"
+require_relative "email_service/configuration"
+require_relative "email_service/message"
+require_relative "email_service/response"
+require_relative "email_service/client"
+require_relative "email_service/smtp_client"
+
+module Cloudflare
+  # Send transactional email through the Cloudflare Email Service, over either
+  # the REST or the SMTP transport.
+  module EmailService
+    class << self
+      # @return [Configuration] the global default configuration.
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      # Yields the global {Configuration} for setup.
+      #
+      #   Cloudflare::EmailService.configure do |c|
+      #     c.account_id = ENV["CLOUDFLARE_ACCOUNT_ID"]
+      #     c.api_token  = ENV["CLOUDFLARE_API_TOKEN"]
+      #   end
+      #
+      # @return [Configuration]
+      def configure
+        yield configuration if block_given?
+        configuration
+      end
+
+      # Resets the global configuration. Mainly useful in tests.
+      # @return [Configuration]
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+
+      # Builds the client for the configured transport (:rest or :smtp).
+      # @return [Client, SMTPClient]
+      def client
+        case configuration.transport
+        when :rest then Client.new
+        when :smtp then SMTPClient.new
+        else
+          raise ConfigurationError, "unknown transport #{configuration.transport.inspect}"
+        end
+      end
+
+      # Convenience: build a {Client} from the global config and send.
+      # Accepts the same keyword arguments as {Message#initialize}.
+      # @return [Response]
+      def send_email(**kwargs)
+        client.send_email(**kwargs)
+      end
+
+      # Cloudflare SMTP submission settings, in the shape both {SMTPClient} and
+      # ActionMailer's built-in `:smtp` delivery method expect. Defaults come
+      # from the global configuration; pass keywords to override.
+      # @return [Hash]
+      def smtp_settings(api_token: nil, host: nil, port: nil,
+                        open_timeout: nil, timeout: nil)
+        config = configuration
+        {
+          address: host || config.smtp_host,
+          port: port || config.smtp_port,
+          user_name: SMTPClient::SMTP_USERNAME,
+          password: api_token || config.api_token,
+          authentication: :plain,
+          enable_starttls_auto: false,
+          tls: true,
+          open_timeout: open_timeout || config.open_timeout,
+          read_timeout: timeout || config.timeout,
+        }
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: cloudflare-email_service
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Elvinas Predkelis
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A small Ruby client for sending transactional email via the Cloudflare
+  Email Service. The REST transport is dependency-free; the optional SMTP transport
+  uses the `mail` gem only when selected.
+email:
+- elvinas@trip1.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/cloudflare/email_service.rb
+- lib/cloudflare/email_service/client.rb
+- lib/cloudflare/email_service/configuration.rb
+- lib/cloudflare/email_service/errors.rb
+- lib/cloudflare/email_service/message.rb
+- lib/cloudflare/email_service/rails.rb
+- lib/cloudflare/email_service/response.rb
+- lib/cloudflare/email_service/smtp_client.rb
+- lib/cloudflare/email_service/version.rb
+homepage: https://github.com/elvinaspredkelis/cloudflare-email_service
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/elvinaspredkelis/cloudflare-email_service
+  changelog_uri: https://github.com/elvinaspredkelis/cloudflare-email_service/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Send email through the Cloudflare Email Service (REST or SMTP).
+test_files: []