SwooshCloudflare

Swoosh adapter for Cloudflare Email Service.

Note: Cloudflare Email Service is currently in beta. The API may change before general availability. Check the official documentation for the latest updates.

Installation

def deps do
  [
    {:swoosh_cloudflare, "~> 0.2"}
  ]
end

Getting your Cloudflare credentials

You need two values: an Account ID and an API Token.

Account ID

  1. Log in to the Cloudflare dashboard
  2. Select any domain (or go to the account home page)
  3. Your Account ID is shown on the right sidebar under "Account ID"

API Token

You need a token with permission to send emails via the Email Service API.

  1. Go to My Profile → API Tokens
  2. Click Create Token
  3. Use Create Custom Token
  4. Add the permission: Account → Email Sending — Send
  5. Under Account Resources, select your account
  6. Click Continue to summary → Create Token
  7. Copy the token — it is shown only once

Set both values as environment variables:

CLOUDFLARE_EMAIL_TOKEN=your_api_token_here
CLOUDFLARE_ACCOUNT_ID=your_account_id_here

Configuration

config :my_app, MyApp.Mailer,
  adapter: Swoosh.Adapters.Cloudflare,
  api_token: System.get_env("CLOUDFLARE_EMAIL_TOKEN"),
  account_id: System.get_env("CLOUDFLARE_ACCOUNT_ID")

Define your mailer module:

defmodule MyApp.Mailer do
  use Swoosh.Mailer, otp_app: :my_app
end

Usage

import Swoosh.Email

new()
|> to({"Alice", "alice@example.com"})
|> from({"My App", "noreply@yourdomain.com"})
|> subject("Welcome!")
|> html_body("<h1>Hello, Alice!</h1>")
|> MyApp.Mailer.deliver()

Success response

deliver/2 returns a map with three fields:

{:ok, %{
  delivered: ["alice@example.com"],
  permanent_bounces: [],
  queued: []
}}

Error handling

deliver/2 returns {:error, {http_status, reason}} on most errors.

For 429 rate limiting, a third element carries the Retry-After value in seconds (or nil if the header was absent):

{:error, {429, :rate_limited, 60}}

Full error table:

Reason HTTP Cloudflare code
:authentication_error 401 10000
:invalid_request 400 10001
:message_too_large 400/413 10202
:sending_disabled 403 10203
:rate_limited 429 10004
:server_error 500 10002
:unknown_error any —

If you receive :authentication_error, verify that:

Limitations

Resources

License

MIT