Inbound documentation

.spectral.yaml

@@ -5,3 +5,8 @@ rules:
   # because Spectral tries to parse them as JSON and fails on multi-line/concatenated JSON
   oas3-valid-media-example: off
 
+  # Disable due to upstream regression in @stoplight/spectral-rulesets >= 1.22.3
+  # (released 2026-05-21): the rule's JSONPath crashes nimma when traversing
+  # past `null` values in examples ("Cannot read properties of null").
+  duplicated-entry-in-enum: off
+

README.md

@@ -8,19 +8,18 @@ This repository contains the OpenAPI specification files for various Mailtrap se
 
 The specifications are located in the `specs/` directory:
 
-| Spec | File | Base URL |
-|------|------|----------|
-| Account Management | `specs/account-management.openapi.yml` | `https://mailtrap.io` |
-| Contacts | `specs/contacts.openapi.yml` | `https://mailtrap.io` |
-| Email Sending | `specs/email-sending.openapi.yml` | `https://mailtrap.io` |
-| Email Sending (Bulk) | `specs/email-sending-bulk.openapi.yml` | `https://bulk.api.mailtrap.io` |
-| Email Sending (Transactional) | `specs/email-sending-transactional.openapi.yml` | `https://send.api.mailtrap.io` |
-| Sandbox (send & batch) | `specs/sandbox-sending.openapi.yml` | `https://sandbox.api.mailtrap.io` |
-| Sandbox | `specs/sandbox.openapi.yml` | `https://mailtrap.io` |
-| Templates | `specs/templates.openapi.yml` | `https://mailtrap.io` |
+| Spec                          | File                                            | Base URL                          |
+| ----------------------------- | ----------------------------------------------- | --------------------------------- |
+| Account Management            | `specs/account-management.openapi.yml`          | `https://mailtrap.io`             |
+| Contacts                      | `specs/contacts.openapi.yml`                    | `https://mailtrap.io`             |
+| Email Sending                 | `specs/email-sending.openapi.yml`               | `https://mailtrap.io`             |
+| Email Sending (Bulk)          | `specs/email-sending-bulk.openapi.yml`          | `https://bulk.api.mailtrap.io`    |
+| Email Sending (Transactional) | `specs/email-sending-transactional.openapi.yml` | `https://send.api.mailtrap.io`    |
+| Sandbox (send & batch)        | `specs/sandbox-sending.openapi.yml`             | `https://sandbox.api.mailtrap.io` |
+| Sandbox                       | `specs/sandbox.openapi.yml`                     | `https://mailtrap.io`             |
+| Templates                     | `specs/templates.openapi.yml`                   | `https://mailtrap.io`             |
+| Inbound                       | `specs/inbound.openapi.yml`                     | `https://mailtrap.io`             |
 
 ## Usage
 
 You can import these files into tools like Postman, Swagger UI, or use them with OpenAPI generators to build SDKs for your preferred language.
-
-

specs/email-sending.openapi.yml

@@ -52,7 +52,7 @@ tags:
     x-page-description: Manage webhook endpoints
     description: |
       Configure webhooks to receive real-time notifications about events in
-      your Mailtrap account. For a complete guide, see 
+      your Mailtrap account. For a complete guide, see
       [Webhooks](https://docs.mailtrap.io/email-api-smtp/advanced/webhooks).
 paths:
   /api/domains:
@@ -1684,6 +1684,7 @@ paths:
                         - email_sending
                         - campaigns
                         - audit_log
+                        - inbound_receiving
                       example: email_sending
                     active:
                       type: boolean
@@ -1732,6 +1733,13 @@ paths:
                         domains if omitted. Applicable only for `email_sending`
                         and `campaigns` webhooks.
                       example: 435
+                    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
       responses:
         '200':
           description: Webhook created successfully
@@ -1917,6 +1925,12 @@ paths:
                         - delivery
                         - bounce
                         - unsubscribe
+                    inbound_inbox_id:
+                      type: integer
+                      description: |
+                        ID of the inbound inbox the webhook is linked to.
+                        Applicable only for `inbound_receiving` webhooks.
+                      example: 1
       responses:
         '200':
           description: Webhook updated successfully
@@ -2542,6 +2556,7 @@ components:
             - email_sending
             - campaigns
             - audit_log
+            - inbound_receiving
           example: email_sending
         payload_format:
           type: string
@@ -2570,6 +2585,14 @@ components:
             omitted. Applicable only for `email_sending` and `campaigns`
             webhooks.
           example: 435
+        inbound_inbox_id:
+          type:
+            - integer
+            - 'null'
+          description: |
+            ID of the inbound inbox the webhook is linked to. Applicable only
+            for `inbound_receiving` webhooks.
+          example: 1
         event_types:
           type: array
           description: |