naijacloud-email 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 07014ab220bebb646b9afa26fbe3529f85a067f17bef42ff1c9fc6a2a601cde9
+  data.tar.gz: 5259d09d2ac514de8cd8845d020e30a4598f2a0a48e3b58f47a13e86477d57da
+SHA512:
+  metadata.gz: 570e205a0d015e549c0fbc2e5a3d05940b1736736a4af577b8e2a1337b210d41a26b7e933df1d491b9ef1125d5ee552f92f680d8da84ef4b0f42494d9eed4fea
+  data.tar.gz: 30bd2808294bfeb93ab181fe51c127dbe36505793953618cc6d9a8e4b807056ebecbcd4e12547005394234a5282479575b59072c8e8c4629b28e3bc8e6032e51

data/CHANGELOG.md

@@ -0,0 +1,116 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-10-07
+
+Conformance pass across the five Naijamail SDKs (TGL-741). Where they had drifted
+apart, each now does what the SDK contract settles on.
+
+### Changed
+
+- The 10 MiB limit is measured the way the server measures it: the UTF-8 bytes of
+  `html` and `text` plus the raw (decoded) attachment bytes, instead of the whole
+  encoded JSON. Attachments between ~7.5 and 10 MiB are no longer refused locally.
+- Any unmapped 4xx (405, 415, 451…) raises `ValidationError` instead of the base
+  `Error`.
+- A `base_url` with a query string or fragment is refused (it used to be kept,
+  with every request path appended after it).
+- A blank `NAIJAMAIL_BASE_URL` is treated as unset instead of failing
+  construction.
+- An empty `idempotency_key:` generates one, as if it were omitted, instead of
+  raising. The 255 limit is counted in UTF-8 bytes, not characters.
+- An `nc_pat_…` key is refused with a message saying it is a personal access
+  token and which keys to use, instead of "does not look like a Naijamail key".
+- `max_retries` above 10 is refused.
+- `timeout` is now a deadline on the whole attempt (connect, send, and reading
+  the full response), not a per-socket-read timeout.
+- `Webhooks.verify`: a negative or non-numeric `tolerance` raises
+  `ValidationError` (`0` remains strict); `t` must be 1–12 ASCII digits.
+- Forbidden custom headers are matched on the trimmed name, so `" From"` is
+  refused as an override rather than as an invalid name.
+
+### Added
+
+- `Error#raw_body` (the response text, same as `#body`) and `Error#parsed_body`
+  (the JSON-decoded body, or `nil`).
+
+### Fixed
+
+- A `http://[::1]` base URL could not connect: Net::HTTP was given the bracketed
+  host. It now uses the bare address.
+- `Webhooks.verify` accepts upper-case hex signatures.
+- `Webhooks.verify` raises on a verified payload that is not a JSON object (an
+  array used to come back as an empty event).
+- A send response with no `id` raises `ServerError` instead of returning a
+  response whose `id` is `nil`.
+- Text that is not valid UTF-8 raises `ValidationError` instead of
+  `JSON::GeneratorError` or `ArgumentError`.
+
+## [0.2.0] - 2026-10-04
+
+The first version published to RubyGems (`gem install naijacloud-email`).
+0.1.0 was written up here but never pushed, so its entries below are part of
+this release too.
+
+### Added
+
+- Accept a workspace API key (`nc_live_…`) alongside the Naijamail keys. It is
+  the credential from **Settings → API keys**, and it reaches the mail API when
+  it carries the **Email send** scope — so a team that already has one for
+  deploys and the platform API does not need a second secret to send mail.
+  Redaction knows the new prefix, so a dump still shows which kind of credential
+  a process is holding. `nc_pat_…` platform tokens remain refused: they predate
+  the scope and the API rejects them on the mail routes.
+- `Email#sandbox` / `#sandbox?` on a retrieved email: true for a message sent with a test key,
+  which is recorded but never delivered, so a simulated bounce can be told from
+  a real one.
+
+### Fixed
+
+- `YAML.dump` of a client or its `emails` resource raises instead of writing
+  the API key.
+- A 413 (request too large) is a `ValidationError`.
+- Tag length is counted in UTF-16 units, the way the server counts it.
+- Test keys (`nmail_test_…`) are sandboxed by the API, not refused with a 403.
+  The README said otherwise.
+
+## 0.1.0 - 2026-08-29 (never published)
+
+First release. Implements the Naijamail SDK contract for Ruby.
+
+### Added
+
+- `NaijaCloud::Email::Client` with `api_key`, `base_url`, `timeout`,
+  `max_retries` and `user_agent_suffix`. The key defaults to `NAIJAMAIL_API_KEY`
+  and the base URL to `NAIJAMAIL_BASE_URL`, else `https://api.naijacloud.com`.
+- `emails.send_email` (aliased `create`) for `POST /v1/emails`, accepting
+  keywords or a single Hash.
+- `emails.get(id)` for `GET /v1/emails/{id}`.
+- Response objects `SendEmailResponse`, `Email`, `RejectedRecipient` and
+  `WebhookEvent`, all of which ignore unknown fields so a new server field does
+  not break an installed gem. `rejected` is always an array.
+- `MessageStatus` constants, with unknown statuses passing through as strings.
+- Error hierarchy under `NaijaCloud::Email::Error` carrying `status_code`,
+  `error_label`, `request_id` and `body`; `RateLimitError#retry_after`.
+- Retries: 3 attempts, full-jitter exponential backoff (500ms base, 8s cap), only
+  on 429/408/5xx/connection/timeout, with `Retry-After` honoured in both its
+  forms and clamped to 60s.
+- An `Idempotency-Key` generated once per send call and reused across that call's
+  retries, so a retry after a timeout cannot double-mail.
+- `Webhooks.verify` for the `NC-Signature` scheme, with constant-time comparison
+  and a 300-second default replay tolerance. Naija Cloud emits these events;
+  the scheme is shared with every other Naijamail SDK, so all of them verify
+  identically.
+- Security enforcement described in SECURITY.md: HTTPS-only base URLs, no
+  redirect following, key redaction, header-injection rejection, forbidden
+  header names, client-side limits and bytes-only attachments.
+
+[Unreleased]: https://github.com/naijacloud/nc-email-ruby/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/naijacloud/nc-email-ruby/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/naijacloud/nc-email-ruby/releases/tag/v0.2.0

data/CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Contributing
+
+## Setup
+
+Nothing to install. The gem has no runtime dependencies, and minitest and rake
+ship with Ruby.
+
+```sh
+rake test
+```
+
+or, without bundler or rake at all:
+
+```sh
+ruby -Ilib -Itest test/emails_send_test.rb
+```
+
+`bundle install` is only needed if you want a lockfile; the `Gemfile` exists so
+`bundle exec rake test` works, not because anything requires it.
+
+## Tests
+
+The suite runs **offline**. `test/test_helper.rb` starts a small HTTP server on
+`127.0.0.1` with an ephemeral port, built on raw `TCPServer` — webrick left the
+standard library in Ruby 3.0, so building on it would mean a fresh checkout
+could not be tested without a network. There is no WebMock and no VCR, and no
+test makes an outbound connection.
+
+Scripting a response:
+
+```ruby
+@server.enqueue(status: 429, body: { "statusCode" => 429, "message" => "Too many requests" },
+                headers: { "Retry-After" => "3" })
+@server.enqueue(status: 202, body: { "id" => "m1", "status" => "queued" })
+```
+
+`hang:` holds a connection open without answering, which is how the client-side
+deadline is tested without waiting out the 30-second default.
+
+Retry timing is asserted, not slept through: `capture_sleeps(client)` replaces
+the transport's `sleeper` and pins its `jitter` at the ceiling, and returns the
+array of intervals that would have been slept.
+
+**Never commit a real key.** Tests use the literal
+`nmail_live_test0000000000000000`, which is the value nominated by the SDK
+contract and has never been a real key.
+
+## What to keep in mind when changing this gem
+
+- **The SDK contract is binding.** `email-sdks/spec/SDK-CONTRACT.md` is the same
+  document every other Naijamail SDK implements, so a behaviour change here is a
+  change to all of them. If the contract and the control plane disagree, the
+  control plane wins and the contract gets fixed.
+- **Do not invent endpoints.** The server has two: `POST /v1/emails` and
+  `GET /v1/emails/{id}`.
+- **Zero runtime dependencies.** See SECURITY.md for why this is not negotiable.
+- **Every rule in section 5 of the contract is a security rule.** Loosening one
+  needs a reason written down, not a commit message saying "simplify".
+- **Ruby 2.7 is the floor.** No endless method definitions, no `Data.define`, no
+  rightward assignment, no `Hash#except`. CI runs 2.7, 3.0, 3.2 and 3.3.
+
+## House style
+
+Comments explain **why** — the decision, the failure it prevents, the trap it
+avoids. A comment that restates the code is noise and will be asked about in
+review. `# frozen_string_literal: true` at the top of every file.
+
+## Releasing
+
+Releases come from CI, on a tag, with RubyGems trusted publishing: the gemspec
+requires MFA to push, and the short-lived key the workflow gets from
+rubygems.org is what satisfies that without anyone typing a code.
+
+1. Update `lib/naijacloud/email/version.rb`.
+2. Move the `Unreleased` changelog entries under `## [x.y.z] - YYYY-MM-DD` and
+   update the link definitions at the foot of the file.
+3. Tag and push: `git tag v<version> && git push origin v<version>`.
+
+`.github/workflows/release.yml` runs the CI matrix, refuses a tag that disagrees
+with `VERSION` or has no changelog section, builds and pushes the gem, then
+creates the GitHub release from the changelog section.
+
+### One-time setup
+
+- **rubygems.org → Settings → Trusted publishers → Create a pending trusted
+  publisher** (before the first push; afterwards it is on the gem's own page):
+  gem name `naijacloud-email`, repository owner `naijacloud`, repository
+  `nc-email-ruby`, workflow `release.yml`, environment `rubygems`.
+- **GitHub → Settings → Environments → New environment `rubygems`.** Add
+  required reviewers to make a push wait for a human.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NaijaCloud
+
+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,357 @@
+<p align="center">
+  <a href="https://www.naijacloud.com">
+    <img alt="Naijamail — Ruby SDK" src="https://raw.githubusercontent.com/naijacloud/nc-email-ruby/main/.github/assets/banner.png" width="100%">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/naijacloud-email"><img alt="gem" src="https://img.shields.io/badge/gem-naijacloud--email-008751?style=flat-square&labelColor=0A0E0C"></a>
+  <img alt="ruby" src="https://img.shields.io/badge/ruby-%3E%3D_2.7-E0483F?style=flat-square&labelColor=0A0E0C">
+  <img alt="dependencies" src="https://img.shields.io/badge/dependencies-0-46C98A?style=flat-square&labelColor=0A0E0C">
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-8A988F?style=flat-square&labelColor=0A0E0C"></a>
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> ·
+  <a href="#the-api-surface">The API surface</a> ·
+  <a href="#client-options">Client options</a> ·
+  <a href="#errors">Errors</a> ·
+  <a href="#retries">Retries</a> ·
+  <a href="#webhooks">Webhooks</a> ·
+  <a href="#security">Security</a>
+</p>
+
+# naijacloud-email
+
+The official Ruby SDK for **Naijamail**, the transactional email API of
+[Naija Cloud](https://www.naijacloud.com).
+
+Zero runtime dependencies. Standard-library `net/http` only.
+
+```ruby
+require "naijacloud/email"
+
+nm = NaijaCloud::Email::Client.new           # reads NAIJAMAIL_API_KEY
+
+sent = nm.emails.send_email(
+  from: "Acme <hello@acme.com>",
+  to: "customer@example.com",
+  subject: "Your receipt",
+  html: "<p>Thanks for your order.</p>",
+)
+
+puts sent.id                                  # => "5b1e..."
+puts sent.status                              # => "queued"
+
+email = nm.emails.get(sent.id)
+puts email.status                             # => "delivered"
+```
+
+## Install
+
+```ruby
+gem "naijacloud-email"
+```
+
+Ruby 2.7 or newer.
+
+## The API surface
+
+This release wraps two endpoints, send and retrieve. The API also has batch send,
+a message list, limits, domains and suppressions
+([API docs](https://naijacloud.com/docs/api/email)); they are not wrapped yet.
+
+| | |
+| --- | --- |
+| `nm.emails.send_email(...)` | `POST /v1/emails`, returns `SendEmailResponse` |
+| `nm.emails.create(...)` | alias of `send_email` |
+| `nm.emails.get(id)` | `GET /v1/emails/{id}`, returns `Email` |
+| `NaijaCloud::Email::Webhooks.verify(...)` | verifies a signed webhook delivery |
+
+`Email#created_at` and `#delivered_at` are the ISO-8601 **Strings** the server
+sent (`delivered_at` is `nil` until delivery); `#created_at_time` and
+`#delivered_at_time` parse them into `Time` on demand. Other SDKs surface a
+native date type here — that difference is deliberate, not a bug.
+
+`send_email`, not `send`: `send` is `Object#send`, and shadowing it on a resource
+object means anything that dispatches by name against it — including some mocking
+libraries — tries to mail a message instead.
+
+Both call styles work, on every supported Ruby:
+
+```ruby
+nm.emails.send_email(from: "...", to: "...", subject: "Hi")
+nm.emails.send_email({ from: "...", to: "...", subject: "Hi" })
+```
+
+### Send options
+
+| Option | Type | Notes |
+| --- | --- | --- |
+| `from:` | String | **required.** `"Name <a@b.com>"` or a bare address. The domain must be verified for your team. |
+| `to:` | String or Array | **required.** At least one. |
+| `cc:`, `bcc:` | String or Array | |
+| `reply_to:` | String or Array | Sent on the wire as `reply_to`. |
+| `subject:` | String | Always sent; defaults to `""`. |
+| `html:`, `text:` | String | |
+| `headers:` | Hash | At most 25. `From`, `To`, `Cc`, `Bcc`, `Subject`, `DKIM-Signature` and `Received` are refused, matched case-insensitively on the name with surrounding whitespace trimmed (`" From"` is refused too). |
+| `attachments:` | Array of Hashes | `{ filename:, content:, content_type:, content_id: }`. `content` is a String of **raw bytes**; it must not be empty. |
+| `tags:` | Hash | At most 10, key ≤ 64 chars, value ≤ 256. |
+| `idempotency_key:` | String | Optional; one is generated per call if you do not pass one, or pass an empty one. At most 255 bytes of UTF-8. Sent as the `Idempotency-Key` header only. |
+
+An unknown option raises `ValidationError` rather than being dropped, so
+`htlm:` fails on your machine instead of sending a blank email to a customer.
+
+### Attachments
+
+Pass **bytes**, not a path, and do not base64-encode them yourself:
+
+```ruby
+nm.emails.send_email(
+  from: "Acme <billing@acme.com>",
+  to: "customer@example.com",
+  subject: "Invoice #1024",
+  html: "<p>Attached.</p>",
+  attachments: [
+    { filename: "invoice-1024.pdf",
+      content: File.binread("invoice-1024.pdf"),   # you read the file, not us
+      content_type: "application/pdf" },
+  ],
+)
+```
+
+`content` is always taken as raw bytes — in Ruby the String *is* the byte type
+(`File.binread`, `IO#read` in binary mode). It is never interpreted as base64: a
+String you have already base64-encoded is sent as those characters, encoded a
+second time. (The SDKs for languages with a separate byte type — Node, Python,
+Go — read a text string as base64; Ruby and PHP cannot tell the two apart, so
+they do not try.) An empty attachment is refused locally, as the server would
+refuse it.
+
+The SDK never opens a file on your behalf. An SDK that reads whatever path it is
+handed becomes a local-file-disclosure primitive the moment a web handler passes
+user input into it — so you read your own file and hand over the bytes.
+
+### Rejected recipients
+
+A `202` can still name recipients we refused (the suppression list). It is not an
+error: the rest of the message went.
+
+```ruby
+sent = nm.emails.send_email(...)
+sent.rejected.each { |r| puts "#{r.address}: #{r.reason}" }
+```
+
+`rejected` is always an array, never `nil`, even though the server omits the key
+when it is empty.
+
+### Statuses
+
+`queued`, `sent`, `delivered`, `bounced`, `deferred`, `complained`, `rejected`,
+`failed` — as `NaijaCloud::Email::MessageStatus::DELIVERED` and so on. A status
+we have not seen before comes through as a plain String rather than raising, so a
+new server status does not break an installed gem:
+
+```ruby
+NaijaCloud::Email::MessageStatus.known?(email.status)
+```
+
+Delivery is not a state machine. A message can go `delivered` and then
+`complained`, and providers deliver events out of order often enough that no
+client should assume otherwise.
+
+## Client options
+
+```ruby
+nm = NaijaCloud::Email::Client.new(
+  api_key: ENV["NAIJAMAIL_API_KEY"],   # default: ENV["NAIJAMAIL_API_KEY"]
+  base_url: nil,                       # default: ENV["NAIJAMAIL_BASE_URL"] or https://api.naijacloud.com
+  timeout: 30,                         # seconds, per attempt; must be > 0
+  max_retries: 2,                      # 3 attempts in total; 0 to 10
+  user_agent_suffix: "acme-billing/2.1",
+)
+```
+
+- `timeout` is a deadline on the **whole attempt** — connect, send and reading
+  the entire response — not a per-socket-read timeout, so a server trickling a
+  byte at a time cannot hold a request open past it. Each retry gets a fresh one.
+- A blank `NAIJAMAIL_BASE_URL` (set but empty) counts as unset.
+- A `base_url` with a query string or fragment is refused: every path the SDK
+  appends would land after it.
+- The key is trimmed of surrounding whitespace (a trailing newline from a secrets
+  file is common) before it is checked.
+
+### Which key
+
+Two kinds work, and the SDK cannot tell them apart once it has one:
+
+- **`nc_live_…`** — a workspace API key from **Settings → API keys**, ticked for
+  the **Email send** scope. Most teams already have one: it is the same
+  credential CI deploys with. Add **Platform API** as well if the key also needs
+  to manage sending domains or suppressions.
+- **`nmail_live_…` / `nmail_test_…`** — a Naijamail-only key from **Email**. The
+  test variant is **sandboxed**: the API accepts the send, returns a real id
+  and a final status, and never hands the message to a mail server. Use one in
+  staging and CI. Send from any domain you have added, or from
+  `…@test.mail.naijacloud.dev`; send *to* `delivered@`, `bounced@` or
+  `complained@test.mail.naijacloud.dev` to get that outcome. A message sent
+  this way comes back from `get` with `sandbox` set to true. There is no test
+  variant of a workspace key.
+
+An `nc_pat_…` platform token is not accepted: those predate the Email send scope
+and the API refuses them on the mail routes, so the SDK refuses them at
+construction rather than a request later, with a message saying so — "this is a
+personal access token (nc_pat_…), which cannot send mail; use a mail API key
+(nmail_live_… or nmail_test_…) or a workspace API key with the Email send scope
+(nc_live_…)".
+
+Everything lives on the instance. There is no global configuration, so two
+clients holding two teams' keys can run in one process without one borrowing the
+other's credential.
+
+A client is safe to share across threads: each request opens its own connection
+and the client keeps no per-request state.
+
+## Errors
+
+Every failure is a `NaijaCloud::Email::Error`, so one `rescue` covers the lot:
+
+```ruby
+begin
+  nm.emails.send_email(from: "...", to: "...", subject: "Hi", html: "<p>Hi</p>")
+rescue NaijaCloud::Email::PermissionError => e
+  # Unverified domain, a key without the right scope, or a quota.
+  warn "#{e.message} (request #{e.request_id})"
+rescue NaijaCloud::Email::RateLimitError => e
+  warn "rate limited, retry after #{e.retry_after}s"
+rescue NaijaCloud::Email::Error => e
+  warn "#{e.class}: #{e.message} (HTTP #{e.status_code})"
+end
+```
+
+| HTTP | Class | Retried |
+| --- | --- | --- |
+| 400 | `ValidationError` (`NotFoundError` when the message is `message not found`) | no |
+| 401 | `AuthenticationError` | no |
+| 403 | `PermissionError` | no |
+| 404 | `NotFoundError` | no |
+| 408 | `TimeoutError` | yes |
+| 409 | `ConflictError` | no |
+| 413, 422 | `ValidationError` | no |
+| any other 4xx (405, 415, 451…) | `ValidationError` | no |
+| 429 | `RateLimitError` (`#retry_after`) | yes |
+| 5xx | `ServerError` | yes |
+| 3xx | `ServerError` ("unexpected redirect") | no |
+| 2xx that is not a JSON object, or a send response with no `id` | `ServerError` ("malformed response") | no |
+| socket / DNS / TLS | `ConnectionError` | yes |
+| client-side deadline | `TimeoutError` | yes |
+| bad input, caught locally | `ValidationError`, `status_code == 0` | n/a |
+
+Every error carries `message`, `status_code`, `error_label` (the server's short
+label), `request_id` (from `x-request-id`), the response text exactly as received
+(`raw_body`, also available as `body`) and that text parsed as JSON
+(`parsed_body`, `nil` when it was not JSON). Quote the `request_id` in a support
+ticket.
+
+A `400` for an id that does not exist is a known control-plane quirk — the
+retrieve endpoint raises `BadRequestException('message not found')` instead of a
+404. The SDK maps that one case to `NotFoundError`, so your code keeps working
+when the server is fixed.
+
+## Retries
+
+Three attempts by default, with full-jitter exponential backoff — `base` 500ms,
+`cap` 8s — retried only on `429`, `408`, `5xx`, and connection or timeout
+failures. A `Retry-After` header (integer seconds or an HTTP date) on any
+retried response — a `429` or a `503` alike — overrides the computed backoff and
+is clamped to 60 seconds; `RateLimitError#retry_after` reports the clamped value.
+
+A `403` on an unverified domain is never retried. It will not become verified
+between two attempts, and retrying only burns your rate limit.
+
+Retrying a `POST` is safe because the SDK generates a UUIDv4 **once per
+`send_email` call** and sends it as `Idempotency-Key` on every attempt of that
+call. Without it, a timeout followed by a retry mails your customer twice — you
+cannot tell "never arrived" from "arrived, response lost". Pass your own
+`idempotency_key:` (derived from an order id, say) and it is used verbatim and
+never regenerated.
+
+## Security
+
+The full list is in [SECURITY.md](SECURITY.md). In short:
+
+- **HTTPS is enforced** at construction. A plaintext `base_url` is refused unless
+  the host is `localhost`, `127.0.0.1` or `::1`.
+- **Redirects are never followed.** Following one would re-send your
+  `Authorization` header to whatever host the response named.
+- **The key is never printed.** `inspect`, `to_s` and any dump of the client's
+  instance variables show `nmail_live_***`. The client does not even keep the key
+  as one of its own instance variables. There is no verbose mode, because a
+  verbose mode is a way to print an `Authorization` header.
+- **Header injection is rejected locally** — a `\r`, `\n` or NUL in `from`, any
+  address, `subject`, a custom header name or value, or an attachment
+  filename, `content_type` or `content_id`.
+- **Limits are checked before the round trip**: 50 recipients, 25 headers, 10
+  tags, and 10 MiB of message — measured as the server measures it: the UTF-8
+  bytes of `html` and `text` plus the raw (not base64) attachment bytes.
+- **Webhook signatures are compared in constant time.**
+
+## Webhooks
+
+> **Live.** Naija Cloud delivers these events to endpoints you register, signed
+> exactly as below. Two details this verifier already handles: the timestamp is
+> taken per delivery *attempt*, so a retry never arrives outside the tolerance
+> window; and during a secret rotation the header carries two `v1=` values for
+> 24 hours, which is why any match is accepted.
+
+```ruby
+# Rails
+class NaijamailWebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def create
+    event = NaijaCloud::Email::Webhooks.verify(
+      request.raw_post,                       # the RAW body, not params
+      request.headers["NC-Signature"],
+      ENV.fetch("NAIJAMAIL_WEBHOOK_SECRET"),
+    )
+
+    ProcessEmailEvent.perform_later(event.type, event.email_id)
+    head :ok
+  rescue NaijaCloud::Email::WebhookVerificationError
+    head :bad_request
+  end
+end
+```
+
+Pass the raw bytes. A parsed-and-re-serialized body produces different bytes than
+the ones that were signed (key order, unicode escaping, whitespace), the
+signature then fails for every legitimate delivery, and the usual "fix" for that
+is to stop verifying. `Webhooks.verify` refuses a Hash outright for this reason.
+
+Header format: `NC-Signature: t=1756468800,v1=<hex sha256 hmac>`. The signed
+payload is `"<t>.<raw body>"`, HMAC-SHA256 with the endpoint secret, hex
+lowercase (the verifier accepts either case). The default replay tolerance is 300
+seconds (`tolerance:`); `0` is strict (only the current second passes), and a
+negative or non-numeric tolerance raises `ValidationError`. `t` must be 1–12
+ASCII digits. A payload that verifies but is not a JSON object (an array, say)
+raises `WebhookVerificationError`. Several `v1=` values may appear at once during
+a secret rotation; any match is accepted.
+
+## Local development against a dev control plane
+
+```ruby
+nm = NaijaCloud::Email::Client.new(
+  api_key: ENV["NAIJAMAIL_API_KEY"],
+  base_url: "http://localhost:3000",
+)
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The test suite runs offline against a
+mock HTTP server on `127.0.0.1`; it makes no outbound connection.
+
+## License
+
+MIT. Copyright (c) 2026 Naija Cloud.