Add inbound forward rules, forward outcomes, thread delivery and search

[mklocek]

Adds the inbound forwarding API: CRUD for an inbox's forward rules, the outcome of each forward on received messages, and the delivery outcome of sent thread messages. Also adds search to the threads list.

Breaking change: InboundThreadMessage no longer has delivery_status, delivered_at and bounced_at. Read them from the new delivery object instead.

Changes

• Mailtrap::InboundForwardRulesAPI with list, get, create, update and delete
• InboundForwardRule, InboundForwardRuleCondition, InboundForwardRuleDestination, InboundForwardOutcome and InboundThreadMessageDelivery structs
• forwards on InboundMessage and InboundThreadMessage
• delivery (to, status, delivered_at, bounced_at) on sent thread messages, replacing delivery_status, delivered_at and bounced_at
• search: keyword on InboundThreadsAPI#list, combinable with last_id:
• VCR cassettes for the new endpoints and fields; the VCR filter now also masks forward destinations and signed S3 URLs
• Forward rules example and README entry

Summary by CodeRabbit

• New Features
  • Added support for creating, listing, retrieving, updating, and deleting inbound forward rules.
  • Inbound messages and threads now include forwarding outcomes; thread messages include delivery details.
  • Added search support for filtering inbound threads and retrieving results with a cursor.
• Documentation
  • Added examples for managing forward rules, viewing forwarding outcomes, and searching threads.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: mailtrap/mailtrap-ruby/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: e7416467-3b41-4539-a395-a9e15c1a3be6

📥 Commits

Reviewing files that changed from the base of the PR and between 88aab08 and 78ff1b7.

📒 Files selected for processing (37)

• README.md
• examples/inbound_forward_rules_api.rb
• examples/inbound_messages_api.rb
• examples/inbound_threads_api.rb
• lib/mailtrap.rb
• lib/mailtrap/inbound_forward_outcome.rb
• lib/mailtrap/inbound_forward_rule.rb
• lib/mailtrap/inbound_forward_rule_condition.rb
• lib/mailtrap/inbound_forward_rule_destination.rb
• lib/mailtrap/inbound_forward_rules_api.rb
• lib/mailtrap/inbound_message.rb
• lib/mailtrap/inbound_messages_api.rb
• lib/mailtrap/inbound_thread_message.rb
• lib/mailtrap/inbound_thread_message_delivery.rb
• lib/mailtrap/inbound_threads_api.rb
• spec/fixtures/vcr_cassettes/Mailtrap_InboundForwardRulesAPI/_create/maps_response_data_to_an_InboundForwardRule_object.yml
• spec/fixtures/vcr_cassettes/Mailtrap_InboundForwardRulesAPI/_delete/returns_nil.yml
• spec/fixtures/vcr_cassettes/Mailtrap_InboundForwardRulesAPI/_delete/when_the_forward_rule_does_not_exist/raises_an_error.yml
• spec/fixtures/vcr_cassettes/Mailtrap_InboundForwardRulesAPI/_get/maps_response_data_to_an_InboundForwardRule_object.yml
• spec/fixtures/vcr_cassettes/Mailtrap_InboundForwardRulesAPI/_get/when_the_forward_rule_does_not_exist/raises_an_error.yml
• spec/fixtures/vcr_cassettes/Mailtrap_InboundForwardRulesAPI/_list/maps_response_data_to_InboundForwardRule_objects.yml
• spec/fixtures/vcr_cassettes/Mailtrap_InboundForwardRulesAPI/_update/maps_response_data_to_an_InboundForwardRule_object.yml
• spec/fixtures/vcr_cassettes/Mailtrap_InboundForwardRulesAPI/_update/when_clearing_conditions/returns_the_rule_without_conditions.yml
• spec/fixtures/vcr_cassettes/Mailtrap_InboundMessagesAPI/_get/with_forwards/maps_forwards_to_InboundForwardOutcome_objects.yml
• spec/fixtures/vcr_cassettes/Mailtrap_InboundThreadsAPI/_get/with_a_forwarded_message_and_a_sent_reply/maps_delivery_on_sent_messages_and_forwards_on_received_messages.yml
• spec/fixtures/vcr_cassettes/Mailtrap_InboundThreadsAPI/_list/with_search/passes_search_and_returns_the_matching_threads.yml
• spec/mailtrap/inbound_forward_outcome_spec.rb
• spec/mailtrap/inbound_forward_rule_condition_spec.rb
• spec/mailtrap/inbound_forward_rule_destination_spec.rb
• spec/mailtrap/inbound_forward_rule_spec.rb
• spec/mailtrap/inbound_forward_rules_api_spec.rb
• spec/mailtrap/inbound_message_spec.rb
• spec/mailtrap/inbound_messages_api_spec.rb
• spec/mailtrap/inbound_thread_message_delivery_spec.rb
• spec/mailtrap/inbound_thread_message_spec.rb
• spec/mailtrap/inbound_threads_api_spec.rb
• spec/spec_helper.rb

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The Ruby client adds inbox-scoped inbound forward-rule operations. Inbound messages and threads expose forwarding outcomes, and thread messages expose delivery details. Thread listing also accepts an optional search query.

Changes

Inbound forwarding and threads

Layer / File(s)	Summary
Forward-rule contracts and API lib/mailtrap/inbound_forward_rule*.rb, lib/mailtrap/inbound_forward_rules_api.rb, lib/mailtrap.rb, examples/inbound_forward_rules_api.rb, README.md, spec/mailtrap/inbound_forward_rule*_spec.rb, spec/mailtrap/inbound_forward_rules_api_spec.rb, spec/fixtures/vcr_cassettes/Mailtrap_InboundForwardRulesAPI/*, spec/spec_helper.rb	Adds typed forward-rule, condition, and destination objects. The API lists, retrieves, creates, updates, and deletes inbox rules. It validates create and update options and maps API responses to typed objects.
Inbound-message forwarding outcomes lib/mailtrap/inbound_forward_outcome.rb, lib/mailtrap/inbound_message.rb, lib/mailtrap/inbound_messages_api.rb, examples/inbound_messages_api.rb, spec/mailtrap/inbound_forward_outcome_spec.rb, spec/mailtrap/inbound_message*_spec.rb, spec/fixtures/vcr_cassettes/Mailtrap_InboundMessagesAPI/*	Adds a forwards attribute to inbound messages and converts response entries into InboundForwardOutcome objects.
Thread search and message outcomes lib/mailtrap/inbound_thread_message*.rb, lib/mailtrap/inbound_threads_api.rb, examples/inbound_threads_api.rb, spec/mailtrap/inbound_thread_message*_spec.rb, spec/mailtrap/inbound_threads_api_spec.rb, spec/fixtures/vcr_cassettes/Mailtrap_InboundThreadsAPI/*	Adds an optional search query to thread listing. Thread messages expose delivery data through a delivery object and forwarding data through outcome objects.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Merge Risk: ⚪ Minimal · up to 78ff1

The forwarding destination in the test recording is masked, and no issue remains that needs resolution before merging.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 36.84% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 19 functions across 25 files. (12 skipped…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main changes: inbound forward rules, forward outcomes, thread delivery, and search.
Description check	✅ Passed	The description explains the main changes and identifies the breaking change. It omits the template’s Motivation, How to test, and Images and GIFs sections, but it provides a detailed summary of the c…

Full details: Docstring Coverage

Explanation

Docstring coverage is 36.84% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 19 functions across 25 files. (12 skipped: 12 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}