mailbounce 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e07f3db5d808f4a1d3d9f4b53fe83f3f78f619008e14de533d4101cfe1f99a6e
+  data.tar.gz: b2a4341195772ea43fe13a282a27dbcff914da3dbd232f7f0ad7ecbd144a1a59
+SHA512:
+  metadata.gz: f404a22a31ce871ab3e6fb948b0dc8ed5e1dafe9a85b74822fd5e30230f7d2b8ecfedea124370a349f4a139bbc7c136ea519f5ac46ad4f6f8c84518d74436abc
+  data.tar.gz: fd63774ff78d90ef852e94a1994e1282beef51b23daffae422041c0a70a3d02a4e0beb9330639d821093fdcc391afc22855f0efcf5d8a743ddb8a526765c94f1

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- Delivery status report parsing (RFC 3464), every per-recipient block of a `multipart/report`
+- Enhanced status codes (RFC 3463), with the class read apart from the condition
+- Rejection classification into `:invalid`, `:full`, `:oversized`, `:blocked`, and `:unknown`
+- The sending address as a classification input, so a rejection quoting it reads as being about the sender

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PostRider
+
+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,135 @@
+# mailbounce
+
+📭 Email delivery failures for Ruby
+
+Answers one question about a rejected message: whose fault was it?
+
+**mailbounce** reads the two ways mail comes back: a rejection during the SMTP session, and a delivery status notification (RFC 3464) arriving afterwards. Pure Ruby, no dependencies beyond `mail`.
+
+## Features
+
+- Report parsing (RFC 3464), every per-recipient block of a `multipart/report`
+- Enhanced status codes (RFC 3463), read as class and condition apart
+- Classification - was the rejection about the recipient, or about you
+- No network, no state
+
+> It reports what a failure *is*, never what it *costs*. Retiring an address, retrying, and how long to remember either are yours to decide.
+
+## Contents
+
+- [Getting Started](#getting-started)
+- [Classifying a Rejection](#classifying-a-rejection)
+- [Categories](#categories)
+- [Permanent Is Not the Same as Final](#permanent-is-not-the-same-as-final)
+- [Reading a Report](#reading-a-report)
+- [Testing](#testing)
+- [History](#history)
+
+## Getting Started
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "mailbounce"
+```
+
+Requires Ruby >= 3.3.4
+
+## Classifying a Rejection
+
+```ruby
+rejection = MailBounce.classify(response: "550 5.1.1 <someone@example.com>: User unknown",
+  sending_ip: "203.0.113.9")
+
+rejection.category    # => :invalid
+rejection.status.to_s # => "5.1.1"
+rejection.permanent?  # => true
+rejection.about_us?   # => false
+```
+
+- **response** - the SMTP reply, or a diagnostic taken from a report
+- **sending_ip** - optional, the address the mail went out from
+
+## Categories
+
+| Category | What it means |
+| --- | --- |
+| `:invalid` | The mailbox doesn't exist - the one category that says something lasting about the address |
+| `:full` | The mailbox exists and is over quota |
+| `:oversized` | This message was too large; another might not be |
+| `:blocked` | Policy, reputation, or the network - about the exchange, not the address |
+| `:unknown` | Nothing matched |
+
+Classification reads the enhanced status code first, then falls back to wording, since plenty of servers pair a bare `5.0.0` with a diagnostic that names the cause. The wording it knows is what Postfix, Exim, and Sendmail say by default - there's no per-provider table, since those go stale silently.
+
+Unmatched rejections come back `:unknown` rather than as a guess.
+
+Giving `sending_ip` is what makes the interesting case work. A server quoting the address the mail came from is describing the sender, so it classifies `:blocked` however firmly it talks about the recipient:
+
+```ruby
+MailBounce.classify(response: "550 5.1.1 rejected because 203.0.113.9 is on a blocklist",
+  sending_ip: "203.0.113.9").category
+# => :blocked, not :invalid
+```
+
+Without it, that response reads as a recipient failure - and retiring an address over someone else's opinion of your IP is the mistake this library exists to prevent.
+
+## Permanent Is Not the Same as Final
+
+`permanent?` reports what the server claimed: a 5xx is permanent, per RFC 3463. `category` reports what the rejection was about. They disagree exactly where it matters:
+
+```ruby
+rejection = MailBounce.classify(response: "550 5.7.1 Service unavailable; client host blocked")
+
+rejection.permanent?  # => true - the server said so
+rejection.category    # => :blocked - but a listing lapses
+```
+
+Both are reported so a caller can decide which to believe. This library doesn't decide for you.
+
+## Reading a Report
+
+```ruby
+report = MailBounce.parse(raw_bounce)
+
+report.any?         # => true, when there's a machine-readable part to read
+report.recipients   # => [#<MailBounce::Recipient ...>]
+
+recipient = report.for("someone@example.com")
+recipient.action             # => "failed"
+recipient.status.to_s        # => "5.1.1"
+recipient.permanent?         # => true
+recipient.permanent_failure? # => true - failed, and permanently
+recipient.diagnostic_code    # => "smtp; 550 5.1.1 ... User unknown"
+recipient.remote_mta         # => "dns; mx.example.com"
+```
+
+Reports announce delays and successes by the same route and in the same shape, so `permanent_failure?` is usually the question worth asking - `Action: delayed` is not a bounce however permanent the covering message reads.
+
+A report naming several recipients speaks for a given address only when it names it; one covering a single recipient needn't name anyone. Nothing raises: a report with no machine-readable part, or bytes that aren't a message at all, reports nothing.
+
+## Testing
+
+```sh
+bundle install
+rake
+```
+
+Nothing touches the network. Fixtures in `test/fixtures/` are complete bounce messages covering permanent failure, delay, transient failure, several recipients, an unnamed recipient, and a report with no machine-readable part at all.
+
+## History
+
+View the changelog
+
+## Contributing
+
+Everyone is encouraged to help improve this project:
+
+- [Report bugs](https://github.com/example/mailbounce/issues)
+- Fix bugs and submit pull requests
+- Write, clarify, or fix documentation
+- Suggest or add new features
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/mailbounce/recipient.rb

@@ -0,0 +1,102 @@
+require "mailbounce/status"
+
+module MailBounce
+  # One per-recipient block of a delivery status report (RFC 3464 §2.3).
+  class Recipient
+    FAILED_ACTION = "failed".freeze
+
+    attr_reader :final_recipient, :original_recipient, :action, :diagnostic_code, :remote_mta
+
+    def initialize(final_recipient: nil, original_recipient: nil, failed_recipient: nil,
+                   action: nil, status: nil, diagnostic_code: nil, remote_mta: nil)
+      @final_recipient = final_recipient
+      @original_recipient = original_recipient
+      @failed_recipient = failed_recipient
+      @action = action
+      @status = status
+      @diagnostic_code = diagnostic_code
+      @remote_mta = remote_mta
+    end
+
+    WRAPPED = /\A["'<]|[">']\z/
+
+    # RFC 3464 §2.3.2 wants Final-Recipient; also try Original-Recipient and
+    # X-Failed-Recipients so an address-less block is not treated as anonymous
+    # (anonymous answers every name).
+    def address
+      @address ||= sources.filter_map { |source| addressed(source) }.first.to_s
+    end
+
+    def anonymous?
+      address.empty?
+    end
+
+    def failed?
+      action.to_s.strip.casecmp?(FAILED_ACTION)
+    end
+
+    def permanent?
+      status&.permanent? || false
+    end
+
+    def permanent_failure?
+      failed? && permanent?
+    end
+
+    def status
+      @parsed_status ||= Status.parse(@status)
+    end
+
+    def addressed_to?(recipient)
+      named = recipient.to_s.strip
+
+      !named.empty? && named?(named)
+    end
+
+    private
+      def sources
+        [ @final_recipient, @original_recipient, @failed_recipient ]
+      end
+
+      # Type-tagged as `rfc822; someone@example.com`.
+      def addressed(source)
+        address = unwrapped(source.to_s.split(";", 2).last.to_s)
+
+        address unless address.empty?
+      end
+
+      # Strip outer brackets/quotes only. Quoted local-parts lose their quotes
+      # (safe miss — DSNs rarely carry that form).
+      def unwrapped(value)
+        address = value.strip
+
+        while address.match?(WRAPPED)
+          address = address.sub(/\A["'<]/, "").sub(/[">']\z/, "").strip
+        end
+
+        address
+      end
+
+      # An RFC 6533 address carries raw UTF-8, but the message it arrived in
+      # reads as bytes — the two only compare once their encodings agree.
+      def named?(named)
+        mine, theirs = comparable(address), comparable(named)
+
+        if mine.encoding == theirs.encoding
+          mine.casecmp?(theirs)
+        else
+          mine.b.casecmp?(theirs.b)
+        end
+      end
+
+      def comparable(value)
+        utf8 = value.dup.force_encoding(Encoding::UTF_8)
+
+        if utf8.valid_encoding?
+          utf8
+        else
+          value.b
+        end
+      end
+  end
+end

data/lib/mailbounce/rejection.rb

@@ -0,0 +1,115 @@
+require "ipaddr"
+
+require "mailbounce/status"
+
+module MailBounce
+  # Classifies an SMTP rejection: recipient fault vs sender/exchange.
+  class Rejection
+    REPLY_CODE = /\A\s*(?<code>[245]\d\d)\b/
+
+    # RFC 3463 §3.2, class dropped. 1.2 is the system; permanently reported it
+    # is as dead as a mailbox (transient 4.1.2 is merely unreachable).
+    INVALID_CONDITIONS = %w[ 1.1 1.2 1.3 1.6 2.1 ].freeze
+
+    FULL_CONDITIONS = %w[ 2.2 ].freeze
+
+    OVERSIZED_CONDITIONS = %w[ 2.3 3.4 ].freeze
+
+    # RFC 3463 §3.2: sender's address, not the recipient's.
+    SENDER_CONDITIONS = %w[ 1.7 1.8 ].freeze
+
+    # Network, system, protocol, policy — the exchange, not the mailbox.
+    BLOCKED_SUBJECTS = %w[ 3 4 5 7 ].freeze
+
+    # Common MTA wording when no enhanced status is present. No bare
+    # "does not exist": that predicate takes any noun, so "sender address does
+    # not exist" would read as a dead recipient.
+    # No "mailbox unavailable": RFC 5321 §4.2.3 uses that phrase for both 450
+    # (busy / temp policy) and 550 (not found / no access / policy).
+    INVALID_TEXT = /user unknown|unknown user|no such (?:user|recipient)|recipient not found|invalid recipient/i
+
+    FULL_TEXT = /mailbox full|over quota/i
+
+    BLOCKED_TEXT = /blocked|blacklist|spam|denied/i
+
+    QUAD = /(?:\d{1,3}\.){3}\d{1,3}/
+
+    # Mapped form first: otherwise `\h*(?::\h*){2,}` stops at `::ffff:203`.
+    ADDRESS = /\h*(?::\h*)+:#{QUAD}|#{QUAD}|\h*(?::\h*){2,}/
+
+    attr_reader :response
+
+    def initialize(response:, sending_ip: nil)
+      @response = response.to_s
+      @sending_ips = Array(sending_ip).compact
+    end
+
+    # Prefer :unknown over a guess — a wrongful retire is worse than extra retries.
+    def category
+      @category ||=
+        if about_us?
+          :blocked
+        else
+          categorized_by_status || categorized_by_text || :unknown
+        end
+    end
+
+    # What the server claimed (5xx / class 5), not what we made of it.
+    def permanent?
+      if status
+        status.permanent?
+      else
+        reply_code.to_s.start_with?(Status::PERMANENT_CLASS)
+      end
+    end
+
+    def about_us?
+      ours.any? { |ip| quoted_addresses.include?(ip) }
+    end
+
+    def status
+      @status ||= Status.parse(@response)
+    end
+
+    private
+      # Unrecognized conditions fall through so bare 5.0.0 can use the diagnostic text.
+      def categorized_by_status
+        if status
+          case status.condition
+          when *INVALID_CONDITIONS then :invalid
+          when *FULL_CONDITIONS then :full
+          when *OVERSIZED_CONDITIONS then :oversized
+          when *SENDER_CONDITIONS then :blocked
+          else :blocked if BLOCKED_SUBJECTS.include?(status.subject)
+          end
+        end
+      end
+
+      def categorized_by_text
+        case @response
+        when INVALID_TEXT then :invalid
+        when FULL_TEXT then :full
+        when BLOCKED_TEXT then :blocked
+        end
+      end
+
+      def reply_code
+        @response[REPLY_CODE, :code]
+      end
+
+      def ours
+        @ours ||= @sending_ips.filter_map { |ip| address_for(ip) }
+      end
+
+      def quoted_addresses
+        @quoted_addresses ||= @response.scan(ADDRESS).filter_map { |token| address_for(token) }
+      end
+
+      # `.native` so ::ffff:203.0.113.9 and 203.0.113.9 compare equal.
+      def address_for(value)
+        IPAddr.new(value.to_s).native
+      rescue StandardError
+        nil
+      end
+  end
+end

data/lib/mailbounce/report.rb

@@ -0,0 +1,122 @@
+require "mail"
+
+require "mailbounce/recipient"
+
+module MailBounce
+  # Machine-readable half of a bounce (RFC 3464). Unreadable input reports nothing.
+  class Report
+    # RFC 6533 adds the global type for internationalized addresses.
+    DELIVERY_STATUS_TYPES = %w[ message/delivery-status message/global-delivery-status ].freeze
+
+    # RFC 3464 §2.1.
+    BLANK_LINE = /\r?\n[ \t]*\r?\n/
+
+    FIELD_NAME = /\A(?<name>[A-Za-z][A-Za-z0-9\-]*)[ \t]*:/
+
+    # Value stays on its line so an empty field cannot swallow the next.
+    FIELDS = {
+      action: /^Action[ \t]*:[ \t]*(?<value>.+)$/i,
+      status: /^Status[ \t]*:[ \t]*(?<value>.+)$/i,
+      final_recipient: /^Final-Recipient[ \t]*:[ \t]*(?<value>.+)$/i,
+      original_recipient: /^Original-Recipient[ \t]*:[ \t]*(?<value>.+)$/i,
+      diagnostic_code: /^Diagnostic-Code[ \t]*:[ \t]*(?<value>.+)$/i,
+      remote_mta: /^Remote-MTA[ \t]*:[ \t]*(?<value>.+)$/i
+    }.freeze
+
+    def self.parse(raw)
+      new(raw)
+    end
+
+    def initialize(raw)
+      @mail = Mail.new(raw.to_s)
+    rescue StandardError
+      @mail = nil
+    end
+
+    def recipients
+      @recipients ||= reported_blocks.map { |block| recipient_from(block) }
+    end
+
+    # One unnamed recipient may stand in for any address; a named report only
+    # for the address it names.
+    def for(address = nil)
+      if named = recipients.find { |recipient| recipient.addressed_to?(address) }
+        named
+      else
+        sole_recipient_for(address)
+      end
+    end
+
+    def any?
+      recipients.any?
+    end
+
+    private
+      def sole_recipient_for(address)
+        if recipients.one? && (recipients.first.anonymous? || address.to_s.strip.empty?)
+          recipients.first
+        end
+      end
+
+      def blocks
+        delivery_status.to_s.split(BLANK_LINE).flat_map { |chunk| per_recipient(chunk) }
+      end
+
+      # Per-recipient blocks carry Action; the report preamble does not.
+      def reported_blocks
+        @reported_blocks ||= blocks.select { |block| unfolded(block).match?(FIELDS[:action]) }
+      end
+
+      # X-Failed-Recipients only when one block and one address — no positional guess.
+      def attributable_address
+        failed_recipients.first if reported_blocks.one? && failed_recipients.one?
+      end
+
+      def failed_recipients
+        @failed_recipients ||= failed_recipient_headers.flat_map { |header| header.split(",") }.map(&:strip).reject(&:empty?)
+      end
+
+      def failed_recipient_headers
+        Array(@mail&.[]("X-Failed-Recipients")).map(&:to_s)
+      rescue StandardError
+        []
+      end
+
+      # A block ends when a field it already has reappears (order is not fixed).
+      def per_recipient(chunk)
+        chunk.lines.each_with_object([]) do |line, blocks|
+          if blocks.last && continues?(blocks.last, line)
+            blocks.last << line
+          else
+            blocks << +line
+          end
+        end
+      end
+
+      def continues?(block, line)
+        if name = line[FIELD_NAME, :name]
+          !block.match?(/^#{Regexp.escape(name)}[ \t]*:/i)
+        else
+          true
+        end
+      end
+
+      def recipient_from(block)
+        fields = FIELDS.transform_values { |pattern| unfolded(block)[pattern, :value]&.strip }
+
+        Recipient.new(**fields, failed_recipient: attributable_address)
+      end
+
+      def unfolded(block)
+        block.gsub(/\r?\n[ \t]+/, " ")
+      end
+
+      # The mail gem parses and decodes lazily, so unreadable input raises here
+      # rather than at construction.
+      def delivery_status
+        @mail&.all_parts&.find { |part| DELIVERY_STATUS_TYPES.include?(part.mime_type) }&.body&.decoded
+      rescue StandardError
+        nil
+      end
+  end
+end

data/lib/mailbounce/status.rb

@@ -0,0 +1,58 @@
+module MailBounce
+  # Enhanced status code (RFC 3463): class.subject.detail.
+  class Status
+    # Only where a status belongs — not dotted quads in diagnostics (5.1.1.10
+    # is an address). Misses a bare `smtp; 5.1.1 …`; that deferral is cheaper
+    # than retiring a mailbox over a host IP read as a status.
+    PATTERN = /
+      (?: \A[ \t]* | [245]\d\d[ \t\-]+ | ^Status[ \t]*:[ \t]* )
+      (?<code>[245]\.\d{1,3}\.\d{1,3}) (?!\.\d)
+    /xi
+
+    PERMANENT_CLASS = "5".freeze
+
+    TRANSIENT_CLASS = "4".freeze
+
+    def self.parse(text)
+      if code = text.to_s[PATTERN, :code]
+        new(code)
+      end
+    end
+
+    attr_reader :code
+
+    def initialize(code)
+      @code = code.to_s
+    end
+
+    def permanent?
+      status_class == PERMANENT_CLASS
+    end
+
+    def transient?
+      status_class == TRANSIENT_CLASS
+    end
+
+    # Class dropped: 5.1.1 and 4.1.1 share condition "1.1".
+    def condition
+      parts.drop(1).join(".")
+    end
+
+    def subject
+      parts[1].to_s
+    end
+
+    def to_s
+      code
+    end
+
+    private
+      def status_class
+        parts.first.to_s
+      end
+
+      def parts
+        @parts ||= code.split(".")
+      end
+  end
+end

data/lib/mailbounce/version.rb

@@ -0,0 +1,3 @@
+module MailBounce
+  VERSION = "0.1.0"
+end

data/lib/mailbounce.rb

@@ -0,0 +1,17 @@
+require "mailbounce/version"
+require "mailbounce/status"
+require "mailbounce/rejection"
+require "mailbounce/recipient"
+require "mailbounce/report"
+
+# Reads delivery failures: bounce reports (RFC 3464) and SMTP rejections.
+# Reports what a failure is; retiring or retrying is the caller's decision.
+module MailBounce
+  def self.classify(response:, sending_ip: nil)
+    Rejection.new(response: response, sending_ip: sending_ip)
+  end
+
+  def self.parse(raw)
+    Report.parse(raw)
+  end
+end

data/mailbounce.gemspec

@@ -0,0 +1,34 @@
+$LOAD_PATH.push File.expand_path('lib', __dir__)
+require_relative "lib/mailbounce/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "mailbounce"
+  spec.version = MailBounce::VERSION
+  spec.platform = Gem::Platform::RUBY
+  spec.required_ruby_version = ">= 3.3.4"
+  spec.authors = [ "Simon Lev" ]
+  spec.email = [ "support@postrider.dev" ]
+
+  spec.summary = "RFC 3464 delivery status notifications, parsed and classified, in pure Ruby."
+  spec.description = "Answers one question about a rejected message: whose fault was it?"
+
+  spec.homepage = "https://github.com/mailpiece/mailbounce"
+  spec.license = "MIT"
+
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Explicit list: `git ls-files` is empty before the first commit.
+  spec.files = Dir[
+    "lib/**/*.rb",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE",
+    "mailbounce.gemspec"
+  ]
+  spec.require_paths = [ "lib" ]
+
+  spec.add_dependency "mail", ">= 2.7"
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: mailbounce
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Simon Lev
+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: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+description: 'Answers one question about a rejected message: whose fault was it?'
+email:
+- support@postrider.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/mailbounce.rb
+- lib/mailbounce/recipient.rb
+- lib/mailbounce/rejection.rb
+- lib/mailbounce/report.rb
+- lib/mailbounce/status.rb
+- lib/mailbounce/version.rb
+- mailbounce.gemspec
+homepage: https://github.com/mailpiece/mailbounce
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/mailpiece/mailbounce
+  changelog_uri: https://github.com/mailpiece/mailbounce/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/mailpiece/mailbounce/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.4
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: RFC 3464 delivery status notifications, parsed and classified, in pure Ruby.
+test_files: []