From 1c539b1d8dc7273445fffa7b3ec2fc0be903456b Mon Sep 17 00:00:00 2001
From: Marcin Klocek <marcin.klocek@railsware.com>
Date: Wed, 3 Jun 2026 18:22:49 +0200
Subject: [PATCH] Fix inbound spec: message IDs are strings, correct 403 shape

- Type message `id` and the messages `last_id` cursor (param and
  response) as string instead of integer, matching the actual API
- Add a dedicated schema for 403 responses, which return an `errors`
  field rather than the `error` field used by 401/404
---
 specs/inbound.openapi.yml | 26 ++++++++++++++++----------
 1 file changed, 16 insertions(+), 10 deletions(-)

diff --git a/specs/inbound.openapi.yml b/specs/inbound.openapi.yml
index 36bfbe0..9385d7e 100644
--- a/specs/inbound.openapi.yml
+++ b/specs/inbound.openapi.yml
@@ -416,8 +416,8 @@ paths:
             value returned by the previous response to fetch the next page.
             Omit on the first request.
           schema:
-            type: integer
-            example: 1700000000000123
+            type: string
+            example: "1700000000000123"
       x-codeSamples:
         - lang: shell
           label: "cURL"
@@ -433,7 +433,7 @@ paths:
                 $ref: "#/components/schemas/MessagesListResponse"
               example:
                 data:
-                  - id: 1700000000000123
+                  - id: "1700000000000123"
                     inbox_id: 1
                     from: "sender@example.com"
                     to:
@@ -565,8 +565,8 @@ components:
       required: true
       description: Inbound message ID
       schema:
-        type: integer
-        example: 1700000000000123
+        type: string
+        example: "1700000000000123"
 
   schemas:
     Folder:
@@ -678,9 +678,9 @@ components:
       type: object
       properties:
         id:
-          type: integer
+          type: string
           description: Mailtrap object ID for the message (not the `Message-ID` header value).
-          example: 1700000000000123
+          example: "1700000000000123"
         inbox_id:
           type: integer
           example: 1
@@ -823,7 +823,7 @@ components:
           example: 1
         last_id:
           type:
-            - integer
+            - string
             - "null"
           description: |
             Cursor for the next page. `null` when there are no more results.
@@ -845,6 +845,12 @@ components:
         error:
           type: string
 
+    ForbiddenError:
+      type: object
+      properties:
+        errors:
+          type: string
+
   responses:
     Unauthorized:
       description: Unauthorized
@@ -860,9 +866,9 @@ components:
       content:
         application/json:
           schema:
-            $ref: "#/components/schemas/ErrorResponse"
+            $ref: "#/components/schemas/ForbiddenError"
           example:
-            error: Access forbidden
+            errors: Access forbidden
 
     NotFound:
       description: Not found