bouncy 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53898594f15af4d949909e5c3c60f0c16a85120b56e8945d805f886317ffd60e
-  data.tar.gz: 703257ecf36fa011180854ce6f163eda5e3a7d1a7590af6483807e0e878363fa
+  metadata.gz: 25620e7678f2db3d1aeae8f633654ae92205277b171eea5bddbbd3c3d4d898e1
+  data.tar.gz: f898b5f8180190136a031469ca2a6bd62f4930929378afedd0cae4d3f9a19f4a
 SHA512:
-  metadata.gz: e02efcae835f67cd48aa70fd5e4ecb2234ad0d0ea86ae7cf189397f9e419f6ce2ec9c83886a413c0271580719e1f5ada7086338498024ef7911608db4b256a08
-  data.tar.gz: 0e79f6c1ae9fa9752f08c33f395e64873dbe519a566a3458c900eac07390bef3e5dcd540a9c601ed349a5684085ef8cd3777c2cdfe6b5ac106047d166a375fea
+  metadata.gz: d9ebee34cdc50548f939a80ab07cfc3e26cd0284d0c46f5b608f032dd8b41b9b92d7e5101a77b2d7b0107d8fd977aaa2f58da8e822b580362692900f1fd345d2
+  data.tar.gz: 16c591e6c5e1d51d08bd34d8273a2afbc9d08e605f30520635e509b5519104e3b1f13917a740378e88106e3890ef8743606756117a0338087b11a8ee48f5fff1

data/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-10-25
+
+Three gaps that the first app to move its own suppression table to Bouncy found. There is no new migration.
+
+### Added
+
+- `Bouncy.import!(email, reason:, at:, note: nil, actor: nil)` records a block that another system recorded, with its reason (`:hard_bounce`, `:complaint` or `:manual`) and its time, as one `imported` event; it calls no hook, writes nothing when it repeats, never weakens a block in force and changes nothing after a later release, because an app that carried its old suppressions had to call the internal `Bouncy::Ingestor`, which treats each call as new webhook feedback. `Bouncy::Ingestor` keeps its 0.2.0 call shape and is now marked internal.
+- `Status#blocked_at` is the time the block in force began (for an import, its `at:` time) and `nil` when the address is not blocked, because an app that shows "not deliverable since" had to read the suppression row itself; a block that follows an expired soft hold now starts at its own time, not at the soft hold's.
+
+### Changed
+
+- The 90-day freshness rule (`config.maximum_event_age`) applies to webhook feedback only, not to imports or manual holds, because it exists to stop a late notification from blocking, while a block that another system kept for a year is still a block: an import dated a year ago drops mail, and a webhook bounce dated a year ago still does not.
+
+## [0.2.0] - 2026-10-25
+
+Eight features that apps need to replace a hand-rolled SES integration with Bouncy. There is no new migration: the address lock uses database locks, not a column.
+
+### Added
+
+- `config.ses.configuration_set` stamps `X-SES-CONFIGURATION-SET` on every message that names no set of its own, whatever the interception mode, and adds the set to the sending-policy check, so SES publishes each mail's events to the app's topic without a header in every mailer.
+- `Bouncy.hold(email) { ... }` takes a shared lock per address around an app's own check and send, and every Bouncy write takes it exclusively until its transaction ends, so a new bounce or complaint cannot land between the check and the send; inside a PostgreSQL REPEATABLE READ or SERIALIZABLE transaction it raises, because that snapshot cannot see a block committed during the wait.
+- `config.on_notification` receives every SES notification synchronously (`type`, `recipients`, `message_id`, `occurred_at`, `tags`, `raw`) after its state commits and before the receiver answers, so an app can track its own Send and Delivery events, and a raise answers 503 so that SNS delivers again; the `after_*` hooks are unchanged.
+- `config.ses.subscription_confirmation = :subscribe_url` confirms an SNS subscription by visiting the signed `SubscribeURL` on the topic's own SNS host and answers 503 unless that visit gets a 2xx, so credentials without `sns:ConfirmSubscription` can confirm; the default `:api` is unchanged.
+- `config.require_fresh_sync = false` lets a webhook block drop mail with no sync at all, so an app on an SES account that other apps share need not mirror their suppression lists; the default `true` keeps the 0.1 rule.
+- `config.webhook_blocking = :strict` blocks every Permanent bounce, whatever its subtype, and every recipient a complaint names, because without a sync nothing else reads the account list and a complaint does not say who complained; it is the default when `require_fresh_sync` is `false`, and `:cautious`, the 0.1 rule, stays the default while a sync runs.
+- The SNS signing certificate is cached for the process (at most 16 URLs, one hour each, cached only once it parses as X.509 with an RSA key, and fetched again once when a signature fails on a certificate older than a minute), because each request builds a new verifier and an app that subscribes to Send and Delivery events got one HTTPS download per mail.
+- The receiver logs one warning per refused message or failed confirmation, with the status and the reason, plus the topic ARN and `SubscribeURL` host only when they pass strict SNS validation (`<invalid>` otherwise), so no raw field of an unauthenticated body reaches the log, because a silent 4xx or 503 left a dead subscription undiagnosable.
+- `Bouncy::SyncJob` and `Bouncy::PruneJob` return early with one info line while `config.scope` is unset, because a scheduled job in an app with the feature off failed every run and filled the failed-jobs list; `Bouncy.sync!` still raises.
+- `Bouncy::BodyLimit` is Rack middleware (300 KB by default, configurable) that cuts the receiver's body before Rails reads a whole chunked body or parses it for its log; the receiver's own 2 MiB limit stays.
+
+### Changed
+
+- The recipient check moved to the delivery method that Mail calls after every interceptor and mailer callback, so a message that `:drop` left with no recipient reaches no transport, `deliver_now!` and `deliver_later!` included, and a recipient that a later callback or interceptor adds is checked too.
+- The interceptor keeps each remaining To, Cc, Bcc and SMTP envelope entry as written, display name included, because it looks up only the entry's bare address.
+- The `after_*` hooks run after the commit of the outermost transaction and after the enclosing `Bouncy.hold`, so a hook never runs while Bouncy holds an address; a rollback drops them, and Rails transactional tests keep 0.1's timing.
+- The sync's scope lock reads its answer without the query cache, so a second sync in one cached request cannot take the lock without locking.
+
 ## [0.1.0] - 2026-09-09
 
 Initial release of email bounce handling and suppression management for Rails, with Amazon SES support.

data/README.md

@@ -1,22 +1,21 @@
-# 📨 `bouncy`: know when your app's emails bounce
+# 📨 `bouncy` - Know when your app's emails bounce
 
-[![Tests](https://github.com/rameerez/bouncy/actions/workflows/test.yml/badge.svg)](https://github.com/rameerez/bouncy/actions/workflows/test.yml)
+[![Gem Version](https://badge.fury.io/rb/bouncy.svg)](https://badge.fury.io/rb/bouncy) [![Build Status](https://github.com/rameerez/bouncy/actions/workflows/test.yml/badge.svg)](https://github.com/rameerez/bouncy/actions/workflows/test.yml)
 
-**Email bounce handling and suppression management for Rails.** Your email provider knows which addresses it has blocked. Now your app can know too.
-
-“I never got the email.” The job succeeded, your mailer ran, and SES refused an address on its suppression list. `bouncy` brings that information into your app so you can see the restriction, stop repeated attempts and help the person recover.
+> [!TIP]
+> **🚀 Ship your next Rails app 10x faster!** I've built **[RailsFast](https://railsfast.com/?ref=bouncy)**, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks. Go [check it out](https://railsfast.com/?ref=bouncy)!
 
-```ruby
-Bouncy.blocked?("ada@example.com")
-# => true
+`bouncy` brings **email bounce handling and suppression management** into your Rails app.
 
-Bouncy.status("ada@example.com").reason
-# => :hard_bounce
+“I never got the email.” Your mailer ran, the job succeeded, but Amazon SES refused an address on its suppression list. Bouncy keeps a local mirror so you can see what happened, avoid repeated attempts, and release the address from your own admin.
 
-Bouncy.release!("ada@example.com", note: "Corrected and verified with the customer")
+```ruby
+Bouncy.blocked?("ada@example.com")             # => true
+Bouncy.status("ada@example.com").reason       # => :hard_bounce
+Bouncy.release!("ada@example.com", note: "Verified recovery with the customer")
 ```
 
-Works for every address your app sends to: customers, invitees, buyers and contacts. No `User` record required. Use the optional model macro when you have one:
+Works for every address your app sends to: customers, invitees, buyers and contacts. No `User` record required. If you have one, add a single line:
 
 ```ruby
 class User < ApplicationRecord
@@ -27,47 +26,48 @@ user.email_blocked?
 User.email_blocked
 ```
 
-> [!TIP]
-> **🚀 Ship your next Rails app 10x faster!** I've built **[RailsFast](https://railsfast.com/?ref=bouncy)**, a production-ready Rails boilerplate with authentication, payments, admin and the boring parts already wired up. It's the home of the gem ecosystem that Bouncy belongs to.
+Check out my other 💎 Ruby gems: [`nondisposable`](https://github.com/rameerez/nondisposable) · [`api_keys`](https://github.com/rameerez/api_keys) · [`usage_credits`](https://github.com/rameerez/usage_credits) · [`pricing_plans`](https://github.com/rameerez/pricing_plans)
 
-## Status
+## What you get
 
-**v0.1.0 is the first release.** Automated compatibility, packaged installation and host migration/rollback tests pass. Live SES lifecycle verification and independent installation validation remain outstanding. Start in observation mode and verify your sending setup before enabling interception.
+- A local mirror of the SES account suppression list, including restrictions from before installation and other apps on the same account.
+- Signed SNS webhooks for new bounces and complaints, with exact-topic authorization, per-recipient deduplication, a cached signing certificate and one log line per refused message.
+- Address status, model predicates and scopes, and batch lookups for badges on your lists.
+- Action Mailer interception that checks To, Cc, Bcc and the SMTP envelope, keeps display names, and stops bang deliveries too.
+- `Bouncy.hold` for senders that check an address and send in one step, and a synchronous hook for every SES event.
+- Audited support holds and provider-aware recovery that preserves exact address spelling.
+- Sync and pruning jobs, hooks, and read-only setup diagnostics. Use your existing scheduler and admin framework.
 
-Initial support: **Amazon SES, including SES SMTP**, one account and region, PostgreSQL/MySQL/SQLite, Rails 7.2–8.1 and Ruby 3.3/3.4/4.0. Other providers and a hosted dashboard are outside this release.
+## Requirements
 
-## What it does
+- Ruby **3.3+** and Rails **7.2.3.2+**, below Rails 9. Tested on Ruby 3.3/3.4/4.0 and Rails 7.2/8.0/8.1.
+- **PostgreSQL, MySQL or SQLite**, with bigint or UUID primary keys.
+- **Amazon SES**, one account and region. SES SMTP is supported; suppression management needs AWS API credentials.
 
-- Mirrors the complete SES account suppression list into two local tables.
-- Receives signed SNS feedback, authorizes the exact topic, and records each recipient independently.
-- Exposes local address status, model scopes and a compact event history.
-- Observes or drops blocked recipients through Action Mailer's normal delivery path, including Bcc and explicit SMTP envelopes.
-- Releases exact provider address variants before clearing local evidence. Manual holds remain independent.
-- Reconciles provider changes, retains release ordering information and reports incomplete or stale observations.
-
-Soft bounces are recorded without blocking an address, unless you opt into a threshold (`config.soft_bounce_threshold`). An ordinary complaint blocks locally only when SES names exactly one recipient; a complaint that lists several possible recipients is recorded as candidates and enforced once the provider lists the address at the next sync. Suppression-list refusal notices are recorded separately and never become new complaint blocks. Delivery means the receiving server accepted a message; it does not prove inbox placement or reading.
+Start in observation mode and verify your sending setup before enabling dropping. See [compatibility and validation](guides/compatibility.md) for the tested matrix and remaining validation limits.
 
 ## Installation
 
-Add the gem and the optional AWS SDKs used by the SES adapter:
+Add these lines to your application's Gemfile:
 
 ```ruby
-# Gemfile
-gem "bouncy", "~> 0.1.0"
+gem "bouncy", "~> 0.2.0"
 gem "aws-sdk-sesv2"
 gem "aws-sdk-sns"
 gem "aws-sdk-sts"
 ```
 
+Then install the gem and generate its tables and initializer:
+
 ```sh
 bundle install
 bin/rails generate bouncy:install
 bin/rails db:migrate
 ```
 
-The generator writes a migration and initializer. It prints the model line and scheduling instructions; your application owns its models, routes, scheduler and admin UI.
+The migration follows your app's primary-key setting and uses PostgreSQL JSONB or MySQL/SQLite JSON. See [database compatibility](guides/compatibility.md#migrations) for UUID configuration.
 
-Migrations follow the same conventions as `usage_credits`, `api_keys` and `nondisposable`: resolve the host's primary-key setting at migration time, use PostgreSQL JSONB or MySQL/SQLite JSON, and supply model defaults where MySQL requires them. UUID apps use native PostgreSQL UUIDs or application-generated UUID strings on MySQL/SQLite. See [database compatibility](guides/compatibility.md).
+Configure your actual account, region and sending paths:
 
 ```ruby
 # config/initializers/bouncy.rb
@@ -76,137 +76,240 @@ Bouncy.configure do |config|
   config.ses.region = "us-east-1"
   config.ses.topic_arns = ["arn:aws:sns:us-east-1:123456789012:feedback"]
   config.ses.identities = ["example.com"]
-  config.ses.configuration_sets = ["transactional"]
-  config.ses.all_sending_paths_listed = true # The two lists above are complete.
+  config.ses.configuration_sets = [] # List every set you use, if any.
+  config.ses.all_sending_paths_listed = true # Confirm both lists are complete.
   config.interception = :log
 end
+```
+
+The SDKs use the AWS credential chain. If your mailer uses Rails encrypted credentials, pass its AWS credential provider explicitly through `config.ses.credentials`. SMTP credentials cannot authenticate management calls. See [credentials and IAM](guides/amazon-ses.md#iam-and-sdk-dependencies).
 
+Mount the receiver in your routes:
+
+```ruby
 # config/routes.rb
 mount Bouncy::Engine => "/bouncy"
 ```
 
-Deploy the receiver with its allowlist before subscribing the topic. Follow the [Amazon SES setup guide](guides/amazon-ses.md), bootstrap with `bin/rails bouncy:sync`, and schedule `Bouncy::SyncJob` hourly and `Bouncy::PruneJob` daily using your existing job system.
+Cut oversized webhook bodies before Rails reads them. Rails reads a whole chunked body, and parses a JSON body for its log, before any route runs. SNS posts 256 KB at most:
 
-Until `config.scope` is set, Bouncy is inactive: mail is delivered untouched, every address reads as unrestricted, relations are empty, and one warning is logged. Sync, block and release raise `Bouncy::ConfigurationError`. That lets you add the gem before its environment variables exist without breaking mailer tests.
+```ruby
+# config/application.rb
+config.middleware.insert_before 0, Bouncy::BodyLimit, path: "/bouncy/webhooks/ses" # limit: 300.kilobytes by default
+```
 
-Run `bin/rails bouncy:doctor` to check the sending policy, then sync to import restrictions. An unverified policy leaves new imports in observation mode; `policy_reason` explains why. If verification later fails, historical restrictions remain queryable, but the interceptor stops dropping recipients based on provider or webhook evidence until a fresh, complete, verified sync succeeds. Independent manual holds still apply. Every sync records a summary; unchanged addresses create no additional events or hooks.
+Use the path your app routes to the receiver. The limit covers that path with a trailing slash or a format suffix, and also the full path when the app runs under a prefix; adjacent routes are untouched. The receiver keeps its own 2 MiB limit as well.
 
-SMTP credentials are not AWS API credentials. The optional SDKs use the usual AWS credential chain, `config.ses.credentials`, or injected clients. Rails encrypted credentials must be passed explicitly. Requiring the gem does not query your database or call AWS.
+The receiver logs one warning for each message it refuses, with the status, the reason and the topic ARN (or the `SubscribeURL` host of a failed confirmation). The topic and host appear only when they pass strict SNS validation, and as `<invalid>` otherwise, so no address, token or other raw field of the body reaches the log. That line is how a dead subscription shows up in production:
 
+```text
+[bouncy] refused an SNS message (401): SNS topic is not authorized; topic arn:aws:sns:us-east-1:999999999999:feedback
+```
 
-For a host migrating an existing suppression system, run `bin/rails bouncy:bootstrap` after importing legacy state and before starting mail workers. It requires a fresh complete sync with verified policy, performs one if needed, and raises on failure. `Bouncy.sync_fresh?` exposes the same health predicate the interceptor uses, so host health checks need no duplicated freshness logic. Run it explicitly at cutover, not on every application restart. Runtime fail-open behavior continues during later outages.
+Follow the [SES setup guide](guides/amazon-ses.md) to connect bounce and complaint notifications to **`POST /bouncy/webhooks/ses`**. Deploy the allowlisted receiver before subscribing the SNS topic. Bouncy does not create or change your AWS configuration.
+
+Check the policy and import the suppression list:
+
+```sh
+bin/rails bouncy:doctor
+bin/rails bouncy:sync
+```
 
-## Email status
+Schedule `Bouncy::SyncJob` **hourly** and `Bouncy::PruneJob` **daily** with your existing job system. The [operations guide](guides/operations.md) includes scheduling examples and monitoring checks. After reviewing a complete, verified sync and testing delivery in staging, change `config.interception` to `:drop`.
+
+Until `config.scope` is set, Bouncy is inactive: mail goes out untouched and status reports `:unconfigured`. Explicit sync, block, release and erasure operations raise. `Bouncy::SyncJob` and `Bouncy::PruneJob` skip with one info line instead, so a job you schedule before the feature is on does not fail every run. No database or AWS call runs just from loading the gem.
+
+## Usage
+
+### Check an address
 
 ```ruby
 status = Bouncy.status("ada@example.com")
-status.blocked?
-status.reasons       # All effective reasons, including an independent manual hold
-status.knowledge     # :observed, :no_known_block, :unavailable, :unconfigured
-status.provider_listed?   # the provider lists this address in the configured scope
-status.policy_unverified? # listed, but the latest sync did not verify the sending policy
-status.policy_reason      # why verification failed or is unknown; nil when verified or unlisted
-status.stale?
-status.observed_at
-status.last_event
+status.blocked?          # Any effective local restriction?
+status.reasons          # All reasons, including independent local holds
+status.knowledge        # :observed, :no_known_block, :unavailable, :unconfigured
+status.provider_listed?  # Exact provider identifiers are present locally
+status.policy_reason    # Why a listed address's sending policy is unverified
+status.stale?           # Address observation is missing or older than stale_after
+status.blocked_at       # When the block in force began, or nil when not blocked
 
 Bouncy.blocked
-Bouncy.events.for("ada@example.com").recent
+Bouncy.events.for("ada@example.com").recent.limit(20)
+```
+
+`blocked?` describes known restrictions, not guaranteed deliverability or whether this particular message will be dropped. Provider-derived dropping requires a fresh, complete, policy-verified sync, unless you [run without a sync](#run-without-a-sync). Independent manual and active soft holds apply even when the mirror is stale. Recognized database outages fail open; the status API exposes `:unavailable`.
 
-# Many addresses in one query, for a list view or a bulk check:
+For a list page, load all addresses in one query:
+
+```ruby
 statuses = Bouncy.statuses(users.map(&:email))
-statuses["Ada@Example.com"].blocked?   # look up by any spelling
-statuses.blocked                       # only the blocked ones, as [email, status] pairs
-status.record                          # the Bouncy::Suppression row, for linking to your admin page
+statuses["Ada@Example.com"].blocked?
+statuses.blocked # Hash of normalized addresses to blocked statuses
 ```
 
-`blocked?` asks about known local restrictions. An unknown address is not certified deliverable. Recognized database outages return `false` from the boolean API and `:unavailable` from the richer status API. Programming errors still raise.
+See the [API reference](guides/api.md) for all status readers, batch semantics and model scopes. Model scopes expect a trimmed lowercase stored column; use `bouncy :email, normalized_attribute: :canonical_email` if you keep a separate normalized value.
 
-Policy diagnostics use the latest sync in the address's scope, including failed checks. They do not erase historical evidence or replace the freshness check: `blocked?` can remain true while the interceptor lets mail through because verification failed or the sync is stale. Obtain a new status object after a sync to refresh its observations.
+### Stop repeated sends
 
-Model scopes expect the stored column to use Bouncy's trimmed lowercase comparison. For mixed-case display values, supply a persisted normalized column:
+Three modes: `:log` records what would be dropped while allowing delivery, `:drop` removes enforceable blocked recipients, and `:off` disables interception. The other recipients keep their entries as written, display names included. Bouncy decides where Mail hands the message to the transport, after every interceptor and every mailer callback, so it judges the recipients the transport would really get. A message with no recipient left reaches no transport, whether you call `deliver_now`, `deliver_now!`, `deliver_later` or `deliver_later!`.
+
+Direct SDK sends and custom transports have [separate boundaries](guides/delivery.md).
 
 ```ruby
-bouncy :email, normalized_attribute: :canonical_email
-bouncy :billing_email
+# An explicit exception for synchronous mail only:
+Bouncy.unblocked { SupportMailer.recovery(address).deliver_now }
 ```
 
-The macro adds `email_blocked?`, `email_bounced?`, `email_complained?`, `email_status`, and class scopes `email_blocked`, `email_bounced`, `email_unblocked`. The last excludes blank values and makes no deliverability claim.
+### Check and send in one step
 
-## Sending mail
+A sender that records its own outcome checks the address itself, then sends. Hold the address around both, so no new bounce or complaint can land between the check and the send:
 
-Start in `:log`. After reviewing a complete import and testing delivery in staging, set `config.interception = :drop`. `:off` disables interception.
+```ruby
+Bouncy.hold(order.email) do
+  next order.receipt_skipped! if Bouncy.blocked?(order.email)
+
+  ReceiptMailer.with(order:).receipt.deliver_now
+  order.receipt_sent!
+end
+```
 
-In drop mode, Bouncy checks both headers and the SMTP envelope, removes only blocked recipients, and prevents normal delivery if no recipients remain. Provider-derived dropping needs a fresh, complete sync; local administrative holds remain effective independently. Log mode applies the same rule, so its `skipped` events (`would_drop`, `stale_provider_evidence`) preview exactly what drop mode would do. A recognized database outage leaves the original message intact.
+Every Bouncy write to that address waits for the block. Inside a transaction, the hold lasts until the transaction commits, so the record of the send commits first. Senders to one address do not wait for each other on PostgreSQL and SQLite; on MySQL they take turns. The lock needs no migration.
+
+The check inside the hold must read the latest committed state. On MySQL, Bouncy's reads inside a hold are locking reads, which do that at any isolation level. PostgreSQL does it at READ COMMITTED, its default; inside a REPEATABLE READ or SERIALIZABLE transaction, `Bouncy.hold` raises `Bouncy::ConfigurationError`, because the transaction's snapshot is fixed before the lock is granted. For those, and on SQLite, hold the address outside the transaction, around it:
 
 ```ruby
-# A deliberate exception for synchronous mail in this execution context:
-Bouncy.unblocked { SupportMailer.recovery(address).deliver_now }
+Bouncy.hold(order.email) do
+  Order.transaction(isolation: :repeatable_read) do
+    # check, send and record here
+  end
+end
 ```
 
-This bypass does not travel with an enqueued job. Bang delivery methods bypass Mail's `perform_deliveries` check and may attempt transport with an empty envelope, causing an error. Direct SDK sends and custom senders need their own integration. See [delivery boundaries](guides/delivery.md).
+The hold then lasts for the whole block, and the transaction's snapshot starts after it. Hooks of a write made inside a hold run when the hold ends.
 
-## Support and recovery
+### Help someone recover
 
 ```ruby
-Bouncy.block!("ada@example.com", note: "Hold while support investigates", actor: "support:42")
-Bouncy.release!("ada@example.com", at: :local) # Remove local policy; retain provider evidence
-Bouncy.release!("ada@example.com", note: "Verified recovery", actor: "support:42")
+Bouncy.block!(address, note: "Support is investigating", actor: "support:42")
+Bouncy.release!(address, at: :local) # Clear manual/soft holds; retain provider/webhook evidence
+Bouncy.release!(address, note: "Verified recovery", actor: "support:42")
 ```
 
-Default recovery enumerates exact provider variants and confirms removal before clearing local state. Failures raise and leave local evidence available for review. A concurrent newer change can raise `Bouncy::ReleaseConflict`; review the latest state before retrying. Remote calls and your database cannot be one atomic transaction.
+Default release removes exact provider variants and verifies absence before clearing local state. Errors leave evidence available for review. Releasing an SES restriction can affect sister apps in that account and region; authorize the action in your app. Release does not resend mail or restore consent after a complaint. See [recovery and partial failures](guides/recovery.md).
+
+### Carry blocks from another system
 
-`Bouncy::ReleaseFailed#outcomes` identifies removed, already absent, failed and unattempted exact variants. The recovery audit records these outcomes too; a partial remote success never becomes a local success notice.
+An app that moves its own suppression table to Bouncy carries each block with its reason and the time the old table recorded it:
 
-Releasing an SES account restriction can affect sister apps in that account and region. Your host application must authorize the action and confirm appropriate permission before resuming contact after a complaint. Release does not resend a message or repair a mailbox.
+```ruby
+Bouncy.import!(address, reason: :hard_bounce, at: old_row.suppressed_at, note: "Carried from the old table", actor: "carry-task")
+```
+
+`reason` is `:hard_bounce`, `:complaint` or `:manual`. A bounce or a complaint is the same evidence as a webhook block, and a manual block is a manual hold. `at` can be of any age: the 90-day window for late webhook feedback does not apply. The import calls no hook, writes nothing when it repeats, never weakens a block in force, and changes nothing when the address was released after `at`, so a carry task is safe to run again. See [migrating](guides/migrating.md).
 
-Use any admin UI. Bouncy has **no Madmin dependency, generator or adapter**. An [optional admin recipe](guides/admin.md) shows how host-owned glue uses these APIs.
+Use any admin UI. Bouncy has **no Madmin dependency, generator or adapter**. The [admin recipe](guides/admin.md) covers host-owned recovery actions, badges and notifications.
 
-## Repeated soft bounces
+### Handle repeated mailbox-full bounces
 
-Soft bounces are recorded by default. Opt in to a temporary local hold for repeated SES `MailboxFull` events. Content, size, attachment, general and unknown failures stay record-only because they do not establish a mailbox problem:
+Soft bounces are record-only by default. To add a temporary local hold after repeated SES `MailboxFull` bounces:
 
 ```ruby
 Bouncy.configure do |config|
-  config.soft_bounce_threshold = 3       # nil (the default) keeps soft bounces record-only
-  config.soft_bounce_window = 30.days    # occurrences older than this stop counting
-  config.soft_bounce_block_for = 30.days # how long the resulting hold lasts
+  config.soft_bounce_threshold = 3
+  config.soft_bounce_window = 30.days
+  config.soft_bounce_block_for = 30.days
 end
 ```
 
-Thresholds must be between 1 and 50. The window really rolls: each occurrence time is retained, and one that ages out stops counting rather than accumulating forever. Redelivered notifications count once. The resulting hold reads as `:soft_bounces`, is local policy like a manual hold, and so applies even while a provider sync is stale — the provider never listed this address, your application did. `Bouncy.release!` clears the history and fences delayed pre-release soft feedback. Out-of-order events inside the current window still count; expired events cannot start a new hold.
+Only mailbox-full events count. Content, attachment-size and unknown failures never trigger this hold. See [bounce classification](guides/bounce-handling.md) and [configuration defaults](guides/configuration.md).
 
-Hard bounces and complaints keep their own reason when soft evidence accumulates underneath them.
-
-## Hooks and retention
+### React to changes
 
 ```ruby
 Bouncy.configure do |config|
   config.after_block = ->(event) { SupportNotificationJob.perform_later(event.id) }
-  config.after_release = ->(event) { Rails.logger.info("Email recovery recorded: #{event.id}") }
-  config.record_deliveries = true # Optional normalized server-acceptance events
+  config.after_release = ->(event) { Rails.logger.info("Email recovery: #{event.id}") }
+end
+```
+
+Your app defines the notification job. Hooks are best effort and run after the commit of the outermost transaction, once the connection holds no Bouncy lock: a rollback drops them, and inside `Bouncy.hold` they wait until the hold ends. One exception: in Rails transactional tests, whose fixture transaction only rolls back, hooks run when your app's own transaction commits, as in 0.1. Events default to 90-day retention; no raw message bodies or payloads are stored. See [hooks and monitoring](guides/operations.md#hooks-and-instrumentation) and [privacy](guides/privacy.md).
+
+To follow your own mail (sent, delivered, bounced), take every SES notification synchronously:
+
+```ruby
+Bouncy.configure do |config|
+  config.on_notification = lambda do |notification|
+    notification.type        # => "Delivery"
+    notification.message_id  # => SES message id
+    notification.recipients  # => ["ada@example.com"]
+    notification.occurred_at # => Time of this event
+    notification.tags        # => { "receipt" => ["42"] }
+    notification.raw         # => the SES event as a Hash
+  end
 end
 ```
 
-Hooks run after commit. A hook failure emits `hook_error.bouncy`; it does not undo ingestion. Hooks are best effort: use a host outbox for guaranteed external work.
+It runs for every event type, after Bouncy committed what it records, and before the receiver answers SNS. If it raises, the receiver answers 503 and SNS delivers the notification again, so make it safe to repeat.
+
+### Name the configuration set
+
+To publish SES events (Send, Delivery and the rest) through a configuration set, name it once:
+
+```ruby
+config.ses.configuration_set = "transactional"
+```
+
+Bouncy stamps `X-SES-CONFIGURATION-SET` on every message that does not name its own set, whatever the interception mode, and checks the set's suppression options with the rest of your [sending policy](guides/amazon-ses.md#supported-sending-policy).
+
+### Confirm the subscription without the SNS API
 
-Events default to 90-day retention. Raw payloads, subjects and message bodies are not stored. Inactive state rows retain release ordering metadata. `Bouncy.forget!(email)` erases local state and history only; it does not release SES, and a later sync may import the restriction again.
+By default the receiver confirms an SNS subscription with `sns:ConfirmSubscription`. If the app's credentials lack that grant, visit the signed `SubscribeURL` instead:
+
+```ruby
+config.ses.subscription_confirmation = :subscribe_url
+```
+
+Only an HTTPS URL on the topic's own SNS host is visited. Anything but a 2xx answer makes the receiver answer 503, so SNS sends the confirmation again.
+
+### Run without a sync
+
+By default a webhook block drops mail only while a recent sync verified the provider list. An app that never mirrors the account list, for example on an SES account that other apps share, can enforce what its own webhook records:
+
+```ruby
+config.require_fresh_sync = false
+```
+
+Every recorded block then drops mail with no `Bouncy::SyncJob` at all. Nothing clears a webhook block on its own. `Bouncy.forget!` removes the local record; `Bouncy.release!` also reads and changes the account's suppression list, which other apps on a shared account rely on.
+
+Without a sync, the webhook must also decide alone which notifications block, so `config.webhook_blocking` defaults to `:strict`:
+
+| Notification | `:strict` (default without a sync) | `:cautious` (default with a sync) |
+|---|---|---|
+| Permanent bounce, `General` or `NoEmail` | Blocks | Blocks |
+| Permanent bounce, any other subtype (`OnAccountSuppressionList`, `Suppressed`, `UnsubscribedRecipient`, ... and future ones) | Blocks | Recorded; the sync reads the account list |
+| Transient or Undetermined bounce | Recorded only | Recorded only |
+| Complaint naming one recipient | Blocks | Blocks |
+| Complaint naming several recipients | Blocks every one | Recorded as candidates; the sync confirms |
+| Complaint with a subtype such as `OnAccountSuppressionList` | Blocks | Recorded; the sync reads the account list |
+| Complaint marked `not-spam` | Recorded only | Recorded only |
+
+A complaint cannot tell you who complained. In [Amazon's words](https://docs.aws.amazon.com/ses/latest/dg/notification-contents.html#complained-recipients): "Most ISPs remove the email address of the recipient who submitted the complaint from their complaint notification. For this reason, this list contains information about recipients who might have sent the complaint, based on the recipients of the original message and the ISP from which we received the complaint." No field says which case a notification is, so `:strict` blocks every recipient it names: mailing someone who reported you costs more than missing one. Send one message per recipient, as Amazon advises, and a complaint names only that recipient. Set `config.webhook_blocking` yourself to choose either rule with any sync setting.
+
+## Documentation
+
+The [guide index](guides/README.md) covers setup, every configuration option and public API, scheduling, admin integration, recovery, migration and troubleshooting.
 
 ## Development
 
 ```sh
 bin/setup
 bundle exec rake test
+bundle exec rubocop
 bundle exec appraisal install
 bundle exec appraisal rake test
-DATABASE_URL=postgresql:///bouncy_test bundle exec rake test
 ```
 
-Tests use Minitest, SimpleCov (90% line and branch minimum), actual generated migrations, SDK stubs and real RSA-signed SNS messages. See [contributing](CONTRIBUTING.md) for the compatibility matrix and isolated database setup.
-
-## More Rails gems
-
-Pair Bouncy with [`nondisposable`](https://github.com/rameerez/nondisposable) for disposable-address validation, [`api_keys`](https://github.com/rameerez/api_keys) for API authentication, [`usage_credits`](https://github.com/rameerez/usage_credits) for usage billing, and [`pricing_plans`](https://github.com/rameerez/pricing_plans) for subscription plans.
+Tests use Minitest, SimpleCov with 90% line and branch minimums, generated migrations, SDK stubs and real RSA-signed SNS messages. See [contributing](CONTRIBUTING.md) for PostgreSQL/MySQL and UUID test runs. Report vulnerabilities through [private security reporting](SECURITY.md).
 
 ## License
 

data/guides/README.md

@@ -0,0 +1,20 @@
+# Bouncy guides
+
+These guides describe the **v0.2.0** API. Start with the [README installation steps](../README.md#installation), then connect SES and schedule the jobs.
+
+| Guide | What it covers |
+|---|---|
+| [Amazon SES setup](amazon-ses.md) | Credentials, IAM, SNS authorization, feedback routing and offline receiver tests |
+| [Configuration reference](configuration.md) | Every setting, its default and the supported scope |
+| [API reference](api.md) | Individual/batch status, model integration, queries, operations and errors |
+| [Operations](operations.md) | Jobs, scheduling, tasks, freshness, hooks and monitoring |
+| [Bounce handling](bounce-handling.md) | Hard/soft bounces, complaints and opt-in mailbox-full escalation |
+| [Action Mailer delivery](delivery.md) | Modes, SMTP envelopes, bang delivery, `Bouncy.hold`, the configuration set and unsupported send paths |
+| [Admin integration](admin.md) | Host-owned badges, recovery actions, Madmin and tenant authorization |
+| [Recovery](recovery.md) | SES suppression removal, local holds and partial failures |
+| [Troubleshooting](troubleshooting.md) | “The mailer says sent, but the email never arrived” and sync failures |
+| [Migrating](migrating.md) | Importing existing evidence, cutover and rollback |
+| [Compatibility](compatibility.md) | Ruby/Rails versions, bigint/UUID, JSON/JSONB and database locks |
+| [Privacy and retention](privacy.md) | Stored data, pruning and erasure |
+
+See also [release history](../CHANGELOG.md), [contributing](../CONTRIBUTING.md) and [security reporting](../SECURITY.md).

data/guides/admin.md

@@ -26,7 +26,7 @@ The same approach works with ActiveAdmin, RailsAdmin or a custom Rails controlle
 
 ## A badge on your own lists
 
-A user or customer list should show at a glance which addresses cannot be reached. Load the statuses for the page in one query and read each row's status by its address, in any spelling:
+A user or customer list should show at a glance which addresses have recorded delivery restrictions. Load the statuses for the page in one query and read each row's status by its address, in any spelling:
 
 ```ruby
 # controller
@@ -68,4 +68,4 @@ end
 
 Implement that job in the host. Load the event, resolve the responsible seller/operator through authorized host records, and use an idempotency key based on the event ID. Pick an in-app/admin notification or another suitable channel. Do not send an alert to the same blocked recipient, include another tenant's history, or create an alert-mail bounce loop. Handle a pruned/missing event gracefully.
 
-Hooks run after commit but are best effort. For guaranteed notifications, reconcile pending work in a host outbox; an enqueue exception cannot roll back an acknowledged bounce. Test the job and authorization policy with the app's actual customer/seller models before enabling it.
+Hooks run after the outermost commit but are best effort. For guaranteed notifications, reconcile pending work in a host outbox; an enqueue exception cannot roll back an acknowledged bounce. Test the job and authorization policy with the app's actual customer/seller models before enabling it.