Inbound documentation#38
Merged
Merged
Conversation
📝 WalkthroughWalkthroughThis PR introduces the Inbound API v2.0.0 specification, extends the email-sending webhook contract to support inbound webhook notifications with an inbox reference field, updates the README to list the new Inbound API, and disables a Spectral linting rule due to an upstream regression. ChangesInbound API and Webhook Integration
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
piobeny
force-pushed
the
MT-22010-docs-update-documentation
branch
2 times, most recently
from
f86c347 to
084714f
Compare
piobeny
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
specs/email-sending.openapi.yml (1)
1665-1742:⚠️ Potential issue | 🟠 Major | ⚡ Quick winEnforce
inbound_inbox_idconditional validation in the create webhook schema.The schema describes
inbound_inbox_idas required forwebhook_type: inbound_receivingand forbidden otherwise, but the currentrequiredlist does not enforce that rule.Proposed schema constraint
webhook: type: object required: - url - webhook_type properties: ... inbound_inbox_id: type: integer description: | ID of the inbound inbox the webhook is linked to. Required for `inbound_receiving` webhooks; must not be set for any other webhook type. example: 1 + allOf: + - if: + properties: + webhook_type: + const: inbound_receiving + required: + - webhook_type + then: + required: + - inbound_inbox_id + else: + not: + required: + - inbound_inbox_id🤖 Prompt for 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. In `@specs/email-sending.openapi.yml` around lines 1665 - 1742, The create webhook schema's "webhook" object must enforce conditional validation for "inbound_inbox_id": add an if/then/else (or oneOf) constraint on the "webhook" schema that checks "webhook_type" == "inbound_receiving" and in the then-clause requires "inbound_inbox_id", and in the else-clause uses "not" or "required": [] / "properties": {"inbound_inbox_id": {"not": {}}} to forbid "inbound_inbox_id" for other webhook_type values; update the same "webhook" object that contains "webhook_type", "sending_stream" and "event_types" so "sending_stream" & "event_types" conditional requirements remain intact while enforcing the inbound_inbox_id rule.
🤖 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 `@specs/inbound.openapi.yml`:
- Around line 70-76: The x-codeSamples block only contains a cURL example with a
literal token; expand that block to include code samples in the required
priority order (cURL/shell, Node.js/JavaScript, PHP, Python, Ruby, .NET/C#,
Java) and replace any literal API keys with environment-variable usage (e.g.,
process.env.MAILTRAP_API_KEY or equivalent for each language); update the
x-codeSamples array (the existing x-codeSamples entry) so each sample has lang,
label and source fields, and ensure the auth header examples consistently use
env vars instead of "YOUR_API_KEY".
---
Outside diff comments:
In `@specs/email-sending.openapi.yml`:
- Around line 1665-1742: The create webhook schema's "webhook" object must
enforce conditional validation for "inbound_inbox_id": add an if/then/else (or
oneOf) constraint on the "webhook" schema that checks "webhook_type" ==
"inbound_receiving" and in the then-clause requires "inbound_inbox_id", and in
the else-clause uses "not" or "required": [] / "properties":
{"inbound_inbox_id": {"not": {}}} to forbid "inbound_inbox_id" for other
webhook_type values; update the same "webhook" object that contains
"webhook_type", "sending_stream" and "event_types" so "sending_stream" &
"event_types" conditional requirements remain intact while enforcing the
inbound_inbox_id rule.
🪄 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: defaults
Review profile: CHILL
Plan: Pro
Run ID: 7c325698-f9ca-499b-94ae-ff16122d1372
📒 Files selected for processing (4)
.spectral.yamlREADME.mdspecs/email-sending.openapi.ymlspecs/inbound.openapi.yml
mklocek
approved these changes
May 26, 2026
| x-page-description: Receive inbound email | ||
| description: | | ||
| An inbox is the destination for inbound email. Each inbox is created | ||
| inside a folder and gets a unique generated address that can receive |
Contributor
There was a problem hiding this comment.
This will need adjustment once we ship custom domains.
Contributor
Author
There was a problem hiding this comment.
Do you thing we should be more vague about address at this point?
Contributor
There was a problem hiding this comment.
That's what I thought but I guess we will come back here and update this spec soon anyway. So it's fine as is now
piobeny
force-pushed
the
MT-22010-docs-update-documentation
branch
from
084714f to
3cff831
Compare
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
specs/email-sending.openapi.yml (1)
1670-1742:⚠️ Potential issue | 🟠 Major | ⚡ Quick winEnforce conditional validation for
inbound_inbox_idin create webhook schema.The description says
inbound_inbox_idis required forinbound_receivingand forbidden otherwise, but the schema does not encode that rule. This weakens contract validation for generated clients and docs consumers.💡 Suggested schema patch
webhook: type: object required: - url - webhook_type properties: @@ inbound_inbox_id: type: integer description: | ID of the inbound inbox the webhook is linked to. Required for `inbound_receiving` webhooks; must not be set for any other webhook type. example: 1 + allOf: + - if: + properties: + webhook_type: + const: inbound_receiving + then: + required: + - inbound_inbox_id + - if: + properties: + webhook_type: + not: + const: inbound_receiving + then: + not: + required: + - inbound_inbox_id🤖 Prompt for 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. In `@specs/email-sending.openapi.yml` around lines 1670 - 1742, Add conditional JSON Schema validation so inbound_inbox_id is required when webhook_type == "inbound_receiving" and forbidden for other webhook_type values: modify the create webhook schema that defines properties webhook_type and inbound_inbox_id to include a oneOf with two subschemas — one that matches webhook_type: {const: "inbound_receiving"} and declares required: ["inbound_inbox_id"] (with inbound_inbox_id typed as integer), and another that matches webhook_type values excluding "inbound_receiving" and uses not: { required: ["inbound_inbox_id"] } to forbid that property; reference the existing webhook_type and inbound_inbox_id property names when adding these subschemas.
🤖 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.
Outside diff comments:
In `@specs/email-sending.openapi.yml`:
- Around line 1670-1742: Add conditional JSON Schema validation so
inbound_inbox_id is required when webhook_type == "inbound_receiving" and
forbidden for other webhook_type values: modify the create webhook schema that
defines properties webhook_type and inbound_inbox_id to include a oneOf with two
subschemas — one that matches webhook_type: {const: "inbound_receiving"} and
declares required: ["inbound_inbox_id"] (with inbound_inbox_id typed as
integer), and another that matches webhook_type values excluding
"inbound_receiving" and uses not: { required: ["inbound_inbox_id"] } to forbid
that property; reference the existing webhook_type and inbound_inbox_id property
names when adding these subschemas.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: f370baf7-f61b-4843-83d2-d7eb5472ceb5
📒 Files selected for processing (4)
.spectral.yamlREADME.mdspecs/email-sending.openapi.ymlspecs/inbound.openapi.yml
solovey23
approved these changes
May 27, 2026
leonid-shevtsov
approved these changes
May 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
Document the Inbound email API (folders, inboxes, messages) and the companion
inbound_receivingwebhook type so external integrators can build against it from the public docs.Changes
specs/inbound.openapi.ymlcovering 13 operations across three tags: Folders, Inboxes, Messages (list/create/update/delete folders and inboxes, list/get/delete messages, fetch raw bodies and attachments).specs/email-sending.openapi.ymlWebhook schema with the newinbound_receivingevent type andinbound_inbox_idfield — required when creating an inbound webhook, ignored for other webhook types.duplicated-entry-in-enumrule in.spectral.yaml. Upstream regression in@stoplight/spectral-rulesets@1.22.3(2026-05-21) crashes nimma when traversing pastnullvalues in examples; this halted lint CI on this branch and would have done the same on the next push to main.README.mdspec table with the Inbound row and align column widths.How to test
inbound_receivingappears as a webhook type withinbound_inbox_iddocumented as the link to the receiving inbox.Summary by CodeRabbit
New Features
Documentation
Chores