Add Inbound Email API support

[mklocek]

Summary

Adds Inbound Email API support to the PHP SDK, matching the other Mailtrap SDKs. Exposed as a new token-scoped inbound() layer (no account id required):

$inbound = (new MailtrapClient($config))->inbound();

$inbound->folders()->getList();
$inbound->inboxes($folderId)->create(new CreateInboundInbox('Tickets'));
$inbound->messages($inboxId)->reply($messageId, $email);   // $email is a Symfony Mime Email
$inbound->threads($inboxId)->getList();

• Folders — folders(): getList / getById / create / update / delete
• Inboxes — inboxes($folderId): folder-scoped CRUD (create takes an optional domain id)
• Messages — messages($inboxId): getList (cursor via last_id) / getById / delete + reply / replyAll / forward (send real email)
• Threads — threads($inboxId): getList / getById / delete

Notes

• Endpoints are token-scoped under /api/inbound/...; the inbound() layer and its endpoint classes take only path ids, mirroring the General\Account precedent.
• Request bodies are sent flat (the v2 inbound API does not wrap params under a resource key).
• reply/replyAll/forward accept a Symfony\Component\Mime\Email — exactly like the send API. To reuse the existing Email → payload mapping, getPayload() and its helpers were extracted from AbstractEmails into a new EmailPayloadTrait (pure refactor, no behavior change). forward requires at least one recipient.
• Also adds inbound_inbox_id to the webhook DTOs (CreateWebhook/UpdateWebhook) and a TYPE_INBOUND_RECEIVING constant, for inbound_receiving webhooks. inbound_inbox_id is optional (omit to apply to all inboxes).
• The email-log threading fields and sending-domain inbound flags need no code — responses are passthrough (ResponseHelper::toArray), so those keys already flow through.

Summary by CodeRabbit

• New Features

  • Added Inbound Email API support for managing folders, inboxes, messages, and threads.
  • Added message replies, reply-all, forwarding, and deletion capabilities.
  • Added support for inbound-receiving webhooks with optional inbox targeting.
  • Added PHP examples demonstrating inbound email operations.

• Refactor

  • Centralized email payload formatting for more consistent message handling.

• Documentation

  • Updated supported functionality and examples indexes with Inbound Email API guidance.

[coderabbitai]

Warning

Review limit reached

@mklocek, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 34 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: abec5312-24f8-42b2-b8c6-3cf19a4f1a00

📥 Commits

Reviewing files that changed from the base of the PR and between 86df621 and dc2182e.

📒 Files selected for processing (22)

• README.md
• examples/README.md
• examples/inbound/folders.php
• examples/inbound/inboxes.php
• examples/inbound/messages.php
• examples/inbound/threads.php
• src/Api/Inbound/Folder.php
• src/Api/Inbound/InboundInterface.php
• src/Api/Inbound/Inbox.php
• src/Api/Inbound/Message.php
• src/Api/Inbound/Thread.php
• src/DTO/Request/Webhook/CreateWebhook.php
• src/DTO/Request/Webhook/UpdateWebhook.php
• src/DTO/Request/Webhook/Webhook.php
• src/MailtrapClient.php
• src/MailtrapInboundClient.php
• tests/Api/Inbound/FolderTest.php
• tests/Api/Inbound/InboxTest.php
• tests/Api/Inbound/MessageTest.php
• tests/Api/Inbound/ThreadTest.php
• tests/Api/Sending/WebhookTest.php
• tests/MailtrapInboundClientTest.php

📝 Walkthrough

Walkthrough

The PR adds inbound folder, inbox, message, and thread APIs. It adds shared email payload serialization, inbound-receiving webhook support, client wiring, tests, documentation, and PHP examples.

Changes

Inbound Email API

Layer / File(s)	Summary
Shared email payload serialization src/Api/EmailPayloadTrait.php, src/Api/AbstractEmails.php	Email payload construction moves into EmailPayloadTrait, including addresses, attachments, headers, templates, categories, and validation.
Inbound resource contracts and operations src/Api/Inbound/*, src/DTO/Request/Inbound/*	Adds folder, inbox, message, and thread resources with CRUD, pagination, email actions, and request DTOs.
Client wiring and inbound webhooks src/MailtrapClient.php, src/MailtrapInboundClient.php, src/DTO/Request/Webhook/*	Exposes the inbound client layer and supports inbound-receiving webhook types and inbox targeting.
Inbound API and webhook validation tests/Api/Inbound/*, tests/Api/Sending/WebhookTest.php, tests/MailtrapInboundClientTest.php	Tests request paths, payloads, responses, message actions, forwarding validation, resource mapping, and webhook serialization.
Inbound documentation and examples README.md, examples/README.md, examples/inbound/*	Documents inbound functionality and adds PHP examples for folders, inboxes, messages, and threads.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Application
  participant MailtrapClient
  participant MailtrapInboundClient
  participant InboundResource
  participant MailtrapAPI
  Application->>MailtrapClient: Select inbound()
  MailtrapClient->>MailtrapInboundClient: Create inbound client
  Application->>InboundResource: Call folder, inbox, message, or thread operation
  InboundResource->>MailtrapAPI: Send token-scoped request
  MailtrapAPI-->>InboundResource: Return response
  InboundResource-->>Application: Return handled response

Loading

Possibly related PRs

• mailtrap/mailtrap-php#42: Both PRs modify shared email payload serialization.
• mailtrap/mailtrap-php#56: Both PRs update README and examples documentation.
• mailtrap/mailtrap-php#65: Both PRs update webhook DTO behavior.

Suggested reviewers: vladimirtaytor

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.23% which is insufficient. The required threshold is 80.00%.	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 and concisely summarizes the primary change: adding Inbound Email API support.
Description check	✅ Passed	The description clearly explains the motivation and changes, but it omits the template's explicit testing checklist and Images and GIFs section.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

---

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.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/README.md`:
- Around line 41-76: Insert one blank line between each affected section heading
and its following table in the README: Inbound Email, Contact Management,
Templates & Domains, General API, and Framework Bridges. Preserve the table
contents and existing formatting.

In `@src/Api/Inbound/Message.php`:
- Around line 53-88: The forward method must require at least one recipient in
the email’s “to” field, rejecting cc-only or bcc-only payloads. Add validation
in reply and replyAll to reject emails missing both text and html before
invoking httpPost, while preserving their existing request flow for valid
bodies.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e2297fb9-984f-44b4-86d6-eeccc9fda7e3

📥 Commits

Reviewing files that changed from the base of the PR and between aa1e5fc and 86df621.

📒 Files selected for processing (28)

• README.md
• examples/README.md
• examples/inbound/folders.php
• examples/inbound/inboxes.php
• examples/inbound/messages.php
• examples/inbound/threads.php
• src/Api/AbstractEmails.php
• src/Api/EmailPayloadTrait.php
• src/Api/Inbound/Folder.php
• src/Api/Inbound/InboundInterface.php
• src/Api/Inbound/Inbox.php
• src/Api/Inbound/Message.php
• src/Api/Inbound/Thread.php
• src/DTO/Request/Inbound/CreateInboundFolder.php
• src/DTO/Request/Inbound/CreateInboundInbox.php
• src/DTO/Request/Inbound/UpdateInboundFolder.php
• src/DTO/Request/Inbound/UpdateInboundInbox.php
• src/DTO/Request/Webhook/CreateWebhook.php
• src/DTO/Request/Webhook/UpdateWebhook.php
• src/DTO/Request/Webhook/Webhook.php
• src/MailtrapClient.php
• src/MailtrapInboundClient.php
• tests/Api/Inbound/FolderTest.php
• tests/Api/Inbound/InboxTest.php
• tests/Api/Inbound/MessageTest.php
• tests/Api/Inbound/ThreadTest.php
• tests/Api/Sending/WebhookTest.php
• tests/MailtrapInboundClientTest.php