SPB Git

Repository Public

OPENAPI.yaml 259.9 KB 8,073 lines yaml

1openapi: "3.1.0"2info:3  title: "SP Mail API"4  version: "1.0.0"5  description: "Universal REST API of SP Mail. Human contract: docs/API.md. Generated from the route registry that validates requests."6servers:7  -8    url: "https://mail.spboucher.ai/api/v1"9tags:10  -11    name: "Introspection"12  -13    name: "Messages"14  -15    name: "Attachments"16  -17    name: "Folders"18  -19    name: "Templates"20  -21    name: "Sending"22  -23    name: "Drafts"24  -25    name: "Addresses"26  -27    name: "Aliases"28  -29    name: "Webhooks"30paths:31  "/addresses":32    get:33      operationId: "getAddresses"34      tags:35        - "Addresses"36      summary: "Addresses visible to the caller"37      parameters:38        -39          name: "kind"40          in: "query"41          required: false42          schema:43            type: "string"44            enum:45              - "mailbox"46              - "alias"47              - "shared"48              - "notification"49              - "send_only"50              - "receive_only"51              - "temporary"52        -53          name: "mailbox"54          in: "query"55          required: false56          schema:57            type: "string"58            maxLength: 25459        -60          name: "status"61          in: "query"62          required: false63          schema:64            type: "string"65            enum:66              - "active"67              - "suspended"68      responses:69        "200":70          description: "Success"71          content:72            "application/json":73              schema:74                type: "object"75                properties:76                  data:77                    type: "array"78                    items:79                      type: "object"80                      properties:81                        id:82                          type: "string"83                        address:84                          type: "string"85                        kind:86                          type: "string"87                          enum:88                            - "mailbox"89                            - "alias"90                            - "shared"91                            - "notification"92                            - "send_only"93                            - "receive_only"94                            - "temporary"95                        mailbox:96                          description: "Primary address of the physical mailbox that stores and sends for this address"97                          type:98                            - "string"99                            - "null"100                        mailbox_id:101                          type: "string"102                        display_name:103                          type: "string"104                        signature_text:105                          type: "string"106                        signature_html:107                          type: "string"108                        avatar:109                          type:110                            - "string"111                            - "null"112                        can_send:113                          type: "boolean"114                        can_receive:115                          type: "boolean"116                        status:117                          type: "string"118                          enum:119                            - "active"120                            - "suspended"121                        suspended_reason:122                          type:123                            - "string"124                            - "null"125                        expired:126                          type: "boolean"127                        expires_at:128                          type:129                            - "string"130                            - "null"131                        retention_days:132                          type:133                            - "number"134                            - "null"135                        retention_trash_days:136                          type:137                            - "number"138                            - "null"139                        retention_junk_days:140                          type:141                            - "number"142                            - "null"143                        quota_bytes:144                          type:145                            - "number"146                            - "null"147                        reply_policy:148                          type: "string"149                          enum:150                            - "reject"151                            - "accept"152                            - "discard"153                        protected:154                          type: "boolean"155                        extra_destinations:156                          type: "array"157                          items:158                            type: "string"159                        inbound:160                          type: "string"161                          enum:162                            - "accept"163                            - "reject"164                            - "discard"165                          description: "What the mail server currently does with mail for this address"166                        created_at:167                          type: "string"168                        updated_at:169                          type: "string"170                      required:171                        - "id"172                        - "address"173                        - "kind"174                        - "mailbox"175                        - "mailbox_id"176                        - "display_name"177                        - "signature_text"178                        - "signature_html"179                        - "avatar"180                        - "can_send"181                        - "can_receive"182                        - "status"183                        - "suspended_reason"184                        - "expired"185                        - "expires_at"186                        - "retention_days"187                        - "retention_trash_days"188                        - "retention_junk_days"189                        - "quota_bytes"190                        - "reply_policy"191                        - "protected"192                        - "extra_destinations"193                        - "inbound"194                        - "created_at"195                        - "updated_at"196                      additionalProperties: false197                required:198                  - "data"199                additionalProperties: false200        default:201          description: "Error"202          content:203            "application/json":204              schema:205                "$ref": "#/components/schemas/Error"206      security:207        -208          apiKey: []209        -210          session: []211      x-required-scopes:212        - "mail.addresses.read"213    post:214      operationId: "postAddresses"215      tags:216        - "Addresses"217      summary: "Create an address (alias kinds, or a new physical mailbox)"218      description: "Alias kinds (alias, notification, send_only, receive_only, temporary) attach to an existing mailbox. `mailbox` / `shared` create a mail account and require `mail.admin`. A new address is never added implicitly to any key's allowlist."219      parameters:220        -221          name: "Idempotency-Key"222          in: "header"223          required: false224          description: "Replays the stored response for 24 h; a different payload with the same key answers 409."225          schema:226            type: "string"227            maxLength: 200228      requestBody:229        required: true230        content:231          "application/json":232            schema:233              type: "object"234              properties:235                display_name:236                  type: "string"237                  maxLength: 80238                signature_text:239                  type: "string"240                  maxLength: 4000241                signature_html:242                  type: "string"243                  maxLength: 20000244                avatar:245                  anyOf:246                    -247                      type: "string"248                      maxLength: 90000249                      pattern: "^data:image\\/(png|jpeg|webp);base64,[A-Za-z0-9+/=]+$"250                    -251                      type: "null"252                can_send:253                  type: "boolean"254                can_receive:255                  type: "boolean"256                status:257                  type: "string"258                  enum:259                    - "active"260                    - "suspended"261                expires_at:262                  type:263                    - "string"264                    - "null"265                retention_days:266                  anyOf:267                    -268                      type: "integer"269                      minimum: 1270                      maximum: 36500271                    -272                      type: "null"273                retention_trash_days:274                  anyOf:275                    -276                      type: "integer"277                      minimum: 1278                      maximum: 36500279                    -280                      type: "null"281                retention_junk_days:282                  anyOf:283                    -284                      type: "integer"285                      minimum: 1286                      maximum: 36500287                    -288                      type: "null"289                quota_bytes:290                  anyOf:291                    -292                      type: "integer"293                      minimum: 1000000294                      maximum: 1000000000000295                    -296                      type: "null"297                reply_policy:298                  type: "string"299                  enum:300                    - "reject"301                    - "accept"302                    - "discard"303                extra_destinations:304                  maxItems: 20305                  type: "array"306                  items:307                    type: "string"308                    maxLength: 254309                kind:310                  default: "alias"311                  type: "string"312                  enum:313                    - "mailbox"314                    - "alias"315                    - "shared"316                    - "notification"317                    - "send_only"318                    - "receive_only"319                    - "temporary"320                protected:321                  type: "boolean"322                address:323                  type: "string"324                  maxLength: 254325                mailbox:326                  description: "Alias kinds: primary address (or address id) of the mailbox that will store/send for it"327                  type: "string"328                  maxLength: 254329                user_id:330                  description: "Mailbox kinds: owner user (defaults to the admin who owns the key or session)"331                  type: "string"332                  format: "uuid"333                  pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"334              required:335                - "address"336              additionalProperties: false337      responses:338        "201":339          description: "Success"340          content:341            "application/json":342              schema:343                type: "object"344                properties:345                  id:346                    type: "string"347                  address:348                    type: "string"349                  kind:350                    type: "string"351                    enum:352                      - "mailbox"353                      - "alias"354                      - "shared"355                      - "notification"356                      - "send_only"357                      - "receive_only"358                      - "temporary"359                  mailbox:360                    description: "Primary address of the physical mailbox that stores and sends for this address"361                    type:362                      - "string"363                      - "null"364                  mailbox_id:365                    type: "string"366                  display_name:367                    type: "string"368                  signature_text:369                    type: "string"370                  signature_html:371                    type: "string"372                  avatar:373                    type:374                      - "string"375                      - "null"376                  can_send:377                    type: "boolean"378                  can_receive:379                    type: "boolean"380                  status:381                    type: "string"382                    enum:383                      - "active"384                      - "suspended"385                  suspended_reason:386                    type:387                      - "string"388                      - "null"389                  expired:390                    type: "boolean"391                  expires_at:392                    type:393                      - "string"394                      - "null"395                  retention_days:396                    type:397                      - "number"398                      - "null"399                  retention_trash_days:400                    type:401                      - "number"402                      - "null"403                  retention_junk_days:404                    type:405                      - "number"406                      - "null"407                  quota_bytes:408                    type:409                      - "number"410                      - "null"411                  reply_policy:412                    type: "string"413                    enum:414                      - "reject"415                      - "accept"416                      - "discard"417                  protected:418                    type: "boolean"419                  extra_destinations:420                    type: "array"421                    items:422                      type: "string"423                  inbound:424                    type: "string"425                    enum:426                      - "accept"427                      - "reject"428                      - "discard"429                    description: "What the mail server currently does with mail for this address"430                  created_at:431                    type: "string"432                  updated_at:433                    type: "string"434                required:435                  - "id"436                  - "address"437                  - "kind"438                  - "mailbox"439                  - "mailbox_id"440                  - "display_name"441                  - "signature_text"442                  - "signature_html"443                  - "avatar"444                  - "can_send"445                  - "can_receive"446                  - "status"447                  - "suspended_reason"448                  - "expired"449                  - "expires_at"450                  - "retention_days"451                  - "retention_trash_days"452                  - "retention_junk_days"453                  - "quota_bytes"454                  - "reply_policy"455                  - "protected"456                  - "extra_destinations"457                  - "inbound"458                  - "created_at"459                  - "updated_at"460                additionalProperties: false461        default:462          description: "Error"463          content:464            "application/json":465              schema:466                "$ref": "#/components/schemas/Error"467      security:468        -469          apiKey: []470        -471          session: []472      x-required-scopes:473        - "mail.addresses.manage"474        - "mail.aliases.manage"475  "/addresses/{id}":476    delete:477      operationId: "deleteAddressesId"478      tags:479        - "Addresses"480      summary: "Delete an alias, or detach / purge a mailbox"481      description: "Alias kinds: removed from the mail server. Mailbox kinds (`mail.admin`): detached by default (the mail account and its mail are kept); `?purge=delete-all-mail` with body `{\"confirm\":\"delete-all-mail\"}` destroys the account and all its mail. Sessions need a recent re-authentication."482      parameters:483        -484          name: "id"485          in: "path"486          required: true487          description: "Address id (uuid) or the address itself"488          schema:489            type: "string"490            maxLength: 254491        -492          name: "purge"493          in: "query"494          required: false495          schema:496            type: "string"497            const: "delete-all-mail"498      requestBody:499        required: true500        content:501          "application/json":502            schema:503              type: "object"504              properties:505                confirm:506                  type: "string"507                  maxLength: 40508      responses:509        "200":510          description: "Success"511          content:512            "application/json":513              schema:514                type: "object"515                properties:516                  ok:517                    type: "boolean"518                    const: true519                  purged:520                    type: "boolean"521                required:522                  - "ok"523                  - "purged"524                additionalProperties: false525        default:526          description: "Error"527          content:528            "application/json":529              schema:530                "$ref": "#/components/schemas/Error"531      security:532        -533          apiKey: []534        -535          session: []536      x-required-scopes:537        - "mail.addresses.manage"538        - "mail.aliases.manage"539    get:540      operationId: "getAddressesId"541      tags:542        - "Addresses"543      summary: "Read one address"544      parameters:545        -546          name: "id"547          in: "path"548          required: true549          description: "Address id (uuid) or the address itself"550          schema:551            type: "string"552            maxLength: 254553      responses:554        "200":555          description: "Success"556          content:557            "application/json":558              schema:559                type: "object"560                properties:561                  id:562                    type: "string"563                  address:564                    type: "string"565                  kind:566                    type: "string"567                    enum:568                      - "mailbox"569                      - "alias"570                      - "shared"571                      - "notification"572                      - "send_only"573                      - "receive_only"574                      - "temporary"575                  mailbox:576                    description: "Primary address of the physical mailbox that stores and sends for this address"577                    type:578                      - "string"579                      - "null"580                  mailbox_id:581                    type: "string"582                  display_name:583                    type: "string"584                  signature_text:585                    type: "string"586                  signature_html:587                    type: "string"588                  avatar:589                    type:590                      - "string"591                      - "null"592                  can_send:593                    type: "boolean"594                  can_receive:595                    type: "boolean"596                  status:597                    type: "string"598                    enum:599                      - "active"600                      - "suspended"601                  suspended_reason:602                    type:603                      - "string"604                      - "null"605                  expired:606                    type: "boolean"607                  expires_at:608                    type:609                      - "string"610                      - "null"611                  retention_days:612                    type:613                      - "number"614                      - "null"615                  retention_trash_days:616                    type:617                      - "number"618                      - "null"619                  retention_junk_days:620                    type:621                      - "number"622                      - "null"623                  quota_bytes:624                    type:625                      - "number"626                      - "null"627                  reply_policy:628                    type: "string"629                    enum:630                      - "reject"631                      - "accept"632                      - "discard"633                  protected:634                    type: "boolean"635                  extra_destinations:636                    type: "array"637                    items:638                      type: "string"639                  inbound:640                    type: "string"641                    enum:642                      - "accept"643                      - "reject"644                      - "discard"645                    description: "What the mail server currently does with mail for this address"646                  created_at:647                    type: "string"648                  updated_at:649                    type: "string"650                required:651                  - "id"652                  - "address"653                  - "kind"654                  - "mailbox"655                  - "mailbox_id"656                  - "display_name"657                  - "signature_text"658                  - "signature_html"659                  - "avatar"660                  - "can_send"661                  - "can_receive"662                  - "status"663                  - "suspended_reason"664                  - "expired"665                  - "expires_at"666                  - "retention_days"667                  - "retention_trash_days"668                  - "retention_junk_days"669                  - "quota_bytes"670                  - "reply_policy"671                  - "protected"672                  - "extra_destinations"673                  - "inbound"674                  - "created_at"675                  - "updated_at"676                additionalProperties: false677        default:678          description: "Error"679          content:680            "application/json":681              schema:682                "$ref": "#/components/schemas/Error"683      security:684        -685          apiKey: []686        -687          session: []688      x-required-scopes:689        - "mail.addresses.read"690    patch:691      operationId: "patchAddressesId"692      tags:693        - "Addresses"694      summary: "Update an address (display, signatures, send/receive, suspension, expiry, quota, retention…)"695      description: "State changes are applied on the mail server before the call returns. Protected addresses refuse destructive changes with 403 `protected_address`."696      parameters:697        -698          name: "id"699          in: "path"700          required: true701          description: "Address id (uuid) or the address itself"702          schema:703            type: "string"704            maxLength: 254705      requestBody:706        required: true707        content:708          "application/json":709            schema:710              type: "object"711              properties:712                display_name:713                  type: "string"714                  maxLength: 80715                signature_text:716                  type: "string"717                  maxLength: 4000718                signature_html:719                  type: "string"720                  maxLength: 20000721                avatar:722                  anyOf:723                    -724                      type: "string"725                      maxLength: 90000726                      pattern: "^data:image\\/(png|jpeg|webp);base64,[A-Za-z0-9+/=]+$"727                    -728                      type: "null"729                can_send:730                  type: "boolean"731                can_receive:732                  type: "boolean"733                status:734                  type: "string"735                  enum:736                    - "active"737                    - "suspended"738                expires_at:739                  type:740                    - "string"741                    - "null"742                retention_days:743                  anyOf:744                    -745                      type: "integer"746                      minimum: 1747                      maximum: 36500748                    -749                      type: "null"750                retention_trash_days:751                  anyOf:752                    -753                      type: "integer"754                      minimum: 1755                      maximum: 36500756                    -757                      type: "null"758                retention_junk_days:759                  anyOf:760                    -761                      type: "integer"762                      minimum: 1763                      maximum: 36500764                    -765                      type: "null"766                quota_bytes:767                  anyOf:768                    -769                      type: "integer"770                      minimum: 1000000771                      maximum: 1000000000000772                    -773                      type: "null"774                reply_policy:775                  type: "string"776                  enum:777                    - "reject"778                    - "accept"779                    - "discard"780                extra_destinations:781                  maxItems: 20782                  type: "array"783                  items:784                    type: "string"785                    maxLength: 254786                kind:787                  type: "string"788                  enum:789                    - "mailbox"790                    - "alias"791                    - "shared"792                    - "notification"793                    - "send_only"794                    - "receive_only"795                    - "temporary"796                protected:797                  type: "boolean"798              additionalProperties: false799      responses:800        "200":801          description: "Success"802          content:803            "application/json":804              schema:805                type: "object"806                properties:807                  id:808                    type: "string"809                  address:810                    type: "string"811                  kind:812                    type: "string"813                    enum:814                      - "mailbox"815                      - "alias"816                      - "shared"817                      - "notification"818                      - "send_only"819                      - "receive_only"820                      - "temporary"821                  mailbox:822                    description: "Primary address of the physical mailbox that stores and sends for this address"823                    type:824                      - "string"825                      - "null"826                  mailbox_id:827                    type: "string"828                  display_name:829                    type: "string"830                  signature_text:831                    type: "string"832                  signature_html:833                    type: "string"834                  avatar:835                    type:836                      - "string"837                      - "null"838                  can_send:839                    type: "boolean"840                  can_receive:841                    type: "boolean"842                  status:843                    type: "string"844                    enum:845                      - "active"846                      - "suspended"847                  suspended_reason:848                    type:849                      - "string"850                      - "null"851                  expired:852                    type: "boolean"853                  expires_at:854                    type:855                      - "string"856                      - "null"857                  retention_days:858                    type:859                      - "number"860                      - "null"861                  retention_trash_days:862                    type:863                      - "number"864                      - "null"865                  retention_junk_days:866                    type:867                      - "number"868                      - "null"869                  quota_bytes:870                    type:871                      - "number"872                      - "null"873                  reply_policy:874                    type: "string"875                    enum:876                      - "reject"877                      - "accept"878                      - "discard"879                  protected:880                    type: "boolean"881                  extra_destinations:882                    type: "array"883                    items:884                      type: "string"885                  inbound:886                    type: "string"887                    enum:888                      - "accept"889                      - "reject"890                      - "discard"891                    description: "What the mail server currently does with mail for this address"892                  created_at:893                    type: "string"894                  updated_at:895                    type: "string"896                required:897                  - "id"898                  - "address"899                  - "kind"900                  - "mailbox"901                  - "mailbox_id"902                  - "display_name"903                  - "signature_text"904                  - "signature_html"905                  - "avatar"906                  - "can_send"907                  - "can_receive"908                  - "status"909                  - "suspended_reason"910                  - "expired"911                  - "expires_at"912                  - "retention_days"913                  - "retention_trash_days"914                  - "retention_junk_days"915                  - "quota_bytes"916                  - "reply_policy"917                  - "protected"918                  - "extra_destinations"919                  - "inbound"920                  - "created_at"921                  - "updated_at"922                additionalProperties: false923        default:924          description: "Error"925          content:926            "application/json":927              schema:928                "$ref": "#/components/schemas/Error"929      security:930        -931          apiKey: []932        -933          session: []934      x-required-scopes:935        - "mail.addresses.manage"936        - "mail.aliases.manage"937  "/addresses/{id}/automation":938    get:939      operationId: "getAddressesIdAutomation"940      tags:941        - "Addresses"942      summary: "Filters, auto-reply and forwarding of a mailbox"943      description: "`raw_sieve` (the stored script) is returned to administrators only."944      parameters:945        -946          name: "id"947          in: "path"948          required: true949          description: "Address id (uuid) or the address itself"950          schema:951            type: "string"952            maxLength: 254953      responses:954        "200":955          description: "Success"956          content:957            "application/json":958              schema:959                type: "object"960                properties:961                  managed:962                    type: "boolean"963                  active:964                    type: "boolean"965                  rules:966                    type: "array"967                    items: {}968                  vacation: {}969                  forward:970                    anyOf:971                      -972                        type: "object"973                        properties:974                          to: {}975                          keep_copy:976                            default: true977                            type: "boolean"978                        required:979                          - "to"980                          - "keep_copy"981                        additionalProperties: false982                      -983                        type: "null"984                  raw_sieve:985                    type: "string"986                required:987                  - "managed"988                  - "active"989                  - "rules"990                  - "vacation"991                  - "forward"992                additionalProperties: false993        default:994          description: "Error"995          content:996            "application/json":997              schema:998                "$ref": "#/components/schemas/Error"999      security:1000        -1001          apiKey: []1002        -1003          session: []1004      x-required-scopes:1005        - "mail.addresses.read"1006    put:1007      operationId: "putAddressesIdAutomation"1008      tags:1009        - "Addresses"1010      summary: "Replace filters / auto-reply / forwarding of a mailbox"1011      description: "`rules` and `vacation` generate ONE managed Sieve script named `spmail` (same format as the webmail). `forward` is limited to addresses on hosted domains (one destination). `raw_sieve` replaces the script with a hand-written one and requires `mail.admin`."1012      parameters:1013        -1014          name: "id"1015          in: "path"1016          required: true1017          description: "Address id (uuid) or the address itself"1018          schema:1019            type: "string"1020            maxLength: 2541021      requestBody:1022        required: true1023        content:1024          "application/json":1025            schema:1026              type: "object"1027              properties:1028                rules:1029                  maxItems: 1001030                  type: "array"1031                  items:1032                    type: "object"1033                    properties:1034                      id:1035                        type: "string"1036                        maxLength: 641037                      name:1038                        default: ""1039                        type: "string"1040                        maxLength: 1201041                      enabled:1042                        default: true1043                        type: "boolean"1044                      match:1045                        default: "all"1046                        type: "string"1047                        enum:1048                          - "all"1049                          - "any"1050                      conditions:1051                        maxItems: 201052                        type: "array"1053                        items:1054                          type: "object"1055                          properties:1056                            field:1057                              type: "string"1058                              enum:1059                                - "from"1060                                - "to"1061                                - "subject"1062                            op:1063                              type: "string"1064                              enum:1065                                - "contains"1066                                - "is"1067                            value:1068                              type: "string"1069                              maxLength: 3001070                          required:1071                            - "field"1072                            - "op"1073                            - "value"1074                      actions:1075                        maxItems: 61076                        type: "array"1077                        items:1078                          anyOf:1079                            -1080                              type: "object"1081                              properties:1082                                type:1083                                  type: "string"1084                                  const: "move"1085                                folder:1086                                  type: "string"1087                                  maxLength: 1201088                              required:1089                                - "type"1090                                - "folder"1091                            -1092                              type: "object"1093                              properties:1094                                type:1095                                  type: "string"1096                                  const: "markRead"1097                              required:1098                                - "type"1099                            -1100                              type: "object"1101                              properties:1102                                type:1103                                  type: "string"1104                                  const: "flag"1105                              required:1106                                - "type"1107                            -1108                              type: "object"1109                              properties:1110                                type:1111                                  type: "string"1112                                  const: "trash"1113                              required:1114                                - "type"1115                    required:1116                      - "id"1117                      - "conditions"1118                      - "actions"1119                vacation:1120                  type: "object"1121                  properties:1122                    enabled:1123                      default: false1124                      type: "boolean"1125                    subject:1126                      default: ""1127                      type: "string"1128                      maxLength: 2001129                    text:1130                      default: ""1131                      type: "string"1132                      maxLength: 50001133                    from:1134                      anyOf:1135                        -1136                          type: "string"1137                          pattern: "^\\d{4}-\\d{2}-\\d{2}$"1138                        -1139                          type: "null"1140                    to:1141                      anyOf:1142                        -1143                          type: "string"1144                          pattern: "^\\d{4}-\\d{2}-\\d{2}$"1145                        -1146                          type: "null"1147                    days:1148                      type: "integer"1149                      minimum: 11150                      maximum: 301151                forward:1152                  anyOf:1153                    -1154                      type: "object"1155                      properties:1156                        to:1157                          type: "string"1158                          maxLength: 2541159                        keep_copy:1160                          default: true1161                          type: "boolean"1162                      required:1163                        - "to"1164                    -1165                      type: "null"1166                raw_sieve:1167                  type: "string"1168                  maxLength: 1000001169              additionalProperties: false1170      responses:1171        "200":1172          description: "Success"1173          content:1174            "application/json":1175              schema:1176                type: "object"1177                properties:1178                  managed:1179                    type: "boolean"1180                  active:1181                    type: "boolean"1182                  rules:1183                    type: "array"1184                    items: {}1185                  vacation: {}1186                  forward:1187                    anyOf:1188                      -1189                        type: "object"1190                        properties:1191                          to: {}1192                          keep_copy:1193                            default: true1194                            type: "boolean"1195                        required:1196                          - "to"1197                          - "keep_copy"1198                        additionalProperties: false1199                      -1200                        type: "null"1201                  raw_sieve:1202                    type: "string"1203                required:1204                  - "managed"1205                  - "active"1206                  - "rules"1207                  - "vacation"1208                  - "forward"1209                additionalProperties: false1210        default:1211          description: "Error"1212          content:1213            "application/json":1214              schema:1215                "$ref": "#/components/schemas/Error"1216      security:1217        -1218          apiKey: []1219        -1220          session: []1221      x-required-scopes:1222        - "mail.addresses.manage"1223  "/aliases":1224    get:1225      operationId: "getAliases"1226      tags:1227        - "Aliases"1228      summary: "Alias-type addresses visible to the caller"1229      parameters:1230        -1231          name: "kind"1232          in: "query"1233          required: false1234          schema:1235            type: "string"1236            enum:1237              - "mailbox"1238              - "alias"1239              - "shared"1240              - "notification"1241              - "send_only"1242              - "receive_only"1243              - "temporary"1244        -1245          name: "mailbox"1246          in: "query"1247          required: false1248          schema:1249            type: "string"1250            maxLength: 2541251        -1252          name: "status"1253          in: "query"1254          required: false1255          schema:1256            type: "string"1257            enum:1258              - "active"1259              - "suspended"1260      responses:1261        "200":1262          description: "Success"1263          content:1264            "application/json":1265              schema:1266                type: "object"1267                properties:1268                  data:1269                    type: "array"1270                    items:1271                      type: "object"1272                      properties:1273                        id:1274                          type: "string"1275                        address:1276                          type: "string"1277                        kind:1278                          type: "string"1279                          enum:1280                            - "mailbox"1281                            - "alias"1282                            - "shared"1283                            - "notification"1284                            - "send_only"1285                            - "receive_only"1286                            - "temporary"1287                        mailbox:1288                          description: "Primary address of the physical mailbox that stores and sends for this address"1289                          type:1290                            - "string"1291                            - "null"1292                        mailbox_id:1293                          type: "string"1294                        display_name:1295                          type: "string"1296                        signature_text:1297                          type: "string"1298                        signature_html:1299                          type: "string"1300                        avatar:1301                          type:1302                            - "string"1303                            - "null"1304                        can_send:1305                          type: "boolean"1306                        can_receive:1307                          type: "boolean"1308                        status:1309                          type: "string"1310                          enum:1311                            - "active"1312                            - "suspended"1313                        suspended_reason:1314                          type:1315                            - "string"1316                            - "null"1317                        expired:1318                          type: "boolean"1319                        expires_at:1320                          type:1321                            - "string"1322                            - "null"1323                        retention_days:1324                          type:1325                            - "number"1326                            - "null"1327                        retention_trash_days:1328                          type:1329                            - "number"1330                            - "null"1331                        retention_junk_days:1332                          type:1333                            - "number"1334                            - "null"1335                        quota_bytes:1336                          type:1337                            - "number"1338                            - "null"1339                        reply_policy:1340                          type: "string"1341                          enum:1342                            - "reject"1343                            - "accept"1344                            - "discard"1345                        protected:1346                          type: "boolean"1347                        extra_destinations:1348                          type: "array"1349                          items:1350                            type: "string"1351                        inbound:1352                          type: "string"1353                          enum:1354                            - "accept"1355                            - "reject"1356                            - "discard"1357                          description: "What the mail server currently does with mail for this address"1358                        created_at:1359                          type: "string"1360                        updated_at:1361                          type: "string"1362                      required:1363                        - "id"1364                        - "address"1365                        - "kind"1366                        - "mailbox"1367                        - "mailbox_id"1368                        - "display_name"1369                        - "signature_text"1370                        - "signature_html"1371                        - "avatar"1372                        - "can_send"1373                        - "can_receive"1374                        - "status"1375                        - "suspended_reason"1376                        - "expired"1377                        - "expires_at"1378                        - "retention_days"1379                        - "retention_trash_days"1380                        - "retention_junk_days"1381                        - "quota_bytes"1382                        - "reply_policy"1383                        - "protected"1384                        - "extra_destinations"1385                        - "inbound"1386                        - "created_at"1387                        - "updated_at"1388                      additionalProperties: false1389                required:1390                  - "data"1391                additionalProperties: false1392        default:1393          description: "Error"1394          content:1395            "application/json":1396              schema:1397                "$ref": "#/components/schemas/Error"1398      security:1399        -1400          apiKey: []1401        -1402          session: []1403      x-required-scopes:1404        - "mail.addresses.read"1405    post:1406      operationId: "postAliases"1407      tags:1408        - "Aliases"1409      summary: "Create an alias on a mailbox"1410      parameters:1411        -1412          name: "Idempotency-Key"1413          in: "header"1414          required: false1415          description: "Replays the stored response for 24 h; a different payload with the same key answers 409."1416          schema:1417            type: "string"1418            maxLength: 2001419      requestBody:1420        required: true1421        content:1422          "application/json":1423            schema:1424              type: "object"1425              properties:1426                display_name:1427                  type: "string"1428                  maxLength: 801429                signature_text:1430                  type: "string"1431                  maxLength: 40001432                signature_html:1433                  type: "string"1434                  maxLength: 200001435                avatar:1436                  anyOf:1437                    -1438                      type: "string"1439                      maxLength: 900001440                      pattern: "^data:image\\/(png|jpeg|webp);base64,[A-Za-z0-9+/=]+$"1441                    -1442                      type: "null"1443                can_send:1444                  type: "boolean"1445                can_receive:1446                  type: "boolean"1447                status:1448                  type: "string"1449                  enum:1450                    - "active"1451                    - "suspended"1452                expires_at:1453                  type:1454                    - "string"1455                    - "null"1456                retention_days:1457                  anyOf:1458                    -1459                      type: "integer"1460                      minimum: 11461                      maximum: 365001462                    -1463                      type: "null"1464                retention_trash_days:1465                  anyOf:1466                    -1467                      type: "integer"1468                      minimum: 11469                      maximum: 365001470                    -1471                      type: "null"1472                retention_junk_days:1473                  anyOf:1474                    -1475                      type: "integer"1476                      minimum: 11477                      maximum: 365001478                    -1479                      type: "null"1480                quota_bytes:1481                  anyOf:1482                    -1483                      type: "integer"1484                      minimum: 10000001485                      maximum: 10000000000001486                    -1487                      type: "null"1488                reply_policy:1489                  type: "string"1490                  enum:1491                    - "reject"1492                    - "accept"1493                    - "discard"1494                extra_destinations:1495                  maxItems: 201496                  type: "array"1497                  items:1498                    type: "string"1499                    maxLength: 2541500                kind:1501                  default: "alias"1502                  type: "string"1503                  enum:1504                    - "alias"1505                    - "notification"1506                    - "send_only"1507                    - "receive_only"1508                    - "temporary"1509                protected:1510                  type: "boolean"1511                address:1512                  type: "string"1513                  maxLength: 2541514                mailbox:1515                  description: "Alias kinds: primary address (or address id) of the mailbox that will store/send for it"1516                  type: "string"1517                  maxLength: 2541518                user_id:1519                  description: "Mailbox kinds: owner user (defaults to the admin who owns the key or session)"1520                  type: "string"1521                  format: "uuid"1522                  pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"1523              required:1524                - "address"1525              additionalProperties: false1526      responses:1527        "201":1528          description: "Success"1529          content:1530            "application/json":1531              schema:1532                type: "object"1533                properties:1534                  id:1535                    type: "string"1536                  address:1537                    type: "string"1538                  kind:1539                    type: "string"1540                    enum:1541                      - "mailbox"1542                      - "alias"1543                      - "shared"1544                      - "notification"1545                      - "send_only"1546                      - "receive_only"1547                      - "temporary"1548                  mailbox:1549                    description: "Primary address of the physical mailbox that stores and sends for this address"1550                    type:1551                      - "string"1552                      - "null"1553                  mailbox_id:1554                    type: "string"1555                  display_name:1556                    type: "string"1557                  signature_text:1558                    type: "string"1559                  signature_html:1560                    type: "string"1561                  avatar:1562                    type:1563                      - "string"1564                      - "null"1565                  can_send:1566                    type: "boolean"1567                  can_receive:1568                    type: "boolean"1569                  status:1570                    type: "string"1571                    enum:1572                      - "active"1573                      - "suspended"1574                  suspended_reason:1575                    type:1576                      - "string"1577                      - "null"1578                  expired:1579                    type: "boolean"1580                  expires_at:1581                    type:1582                      - "string"1583                      - "null"1584                  retention_days:1585                    type:1586                      - "number"1587                      - "null"1588                  retention_trash_days:1589                    type:1590                      - "number"1591                      - "null"1592                  retention_junk_days:1593                    type:1594                      - "number"1595                      - "null"1596                  quota_bytes:1597                    type:1598                      - "number"1599                      - "null"1600                  reply_policy:1601                    type: "string"1602                    enum:1603                      - "reject"1604                      - "accept"1605                      - "discard"1606                  protected:1607                    type: "boolean"1608                  extra_destinations:1609                    type: "array"1610                    items:1611                      type: "string"1612                  inbound:1613                    type: "string"1614                    enum:1615                      - "accept"1616                      - "reject"1617                      - "discard"1618                    description: "What the mail server currently does with mail for this address"1619                  created_at:1620                    type: "string"1621                  updated_at:1622                    type: "string"1623                required:1624                  - "id"1625                  - "address"1626                  - "kind"1627                  - "mailbox"1628                  - "mailbox_id"1629                  - "display_name"1630                  - "signature_text"1631                  - "signature_html"1632                  - "avatar"1633                  - "can_send"1634                  - "can_receive"1635                  - "status"1636                  - "suspended_reason"1637                  - "expired"1638                  - "expires_at"1639                  - "retention_days"1640                  - "retention_trash_days"1641                  - "retention_junk_days"1642                  - "quota_bytes"1643                  - "reply_policy"1644                  - "protected"1645                  - "extra_destinations"1646                  - "inbound"1647                  - "created_at"1648                  - "updated_at"1649                additionalProperties: false1650        default:1651          description: "Error"1652          content:1653            "application/json":1654              schema:1655                "$ref": "#/components/schemas/Error"1656      security:1657        -1658          apiKey: []1659        -1660          session: []1661      x-required-scopes:1662        - "mail.aliases.manage"1663        - "mail.addresses.manage"1664  "/aliases/{id}":1665    delete:1666      operationId: "deleteAliasesId"1667      tags:1668        - "Aliases"1669      summary: "Delete an alias"1670      parameters:1671        -1672          name: "id"1673          in: "path"1674          required: true1675          description: "Address id (uuid) or the address itself"1676          schema:1677            type: "string"1678            maxLength: 2541679      responses:1680        "200":1681          description: "Success"1682          content:1683            "application/json":1684              schema:1685                type: "object"1686                properties:1687                  ok:1688                    type: "boolean"1689                    const: true1690                  purged:1691                    type: "boolean"1692                required:1693                  - "ok"1694                  - "purged"1695                additionalProperties: false1696        default:1697          description: "Error"1698          content:1699            "application/json":1700              schema:1701                "$ref": "#/components/schemas/Error"1702      security:1703        -1704          apiKey: []1705        -1706          session: []1707      x-required-scopes:1708        - "mail.aliases.manage"1709        - "mail.addresses.manage"1710    patch:1711      operationId: "patchAliasesId"1712      tags:1713        - "Aliases"1714      summary: "Update an alias (destinations, signature, sendable, disable, expiry)"1715      parameters:1716        -1717          name: "id"1718          in: "path"1719          required: true1720          description: "Address id (uuid) or the address itself"1721          schema:1722            type: "string"1723            maxLength: 2541724      requestBody:1725        required: true1726        content:1727          "application/json":1728            schema:1729              type: "object"1730              properties:1731                display_name:1732                  type: "string"1733                  maxLength: 801734                signature_text:1735                  type: "string"1736                  maxLength: 40001737                signature_html:1738                  type: "string"1739                  maxLength: 200001740                avatar:1741                  anyOf:1742                    -1743                      type: "string"1744                      maxLength: 900001745                      pattern: "^data:image\\/(png|jpeg|webp);base64,[A-Za-z0-9+/=]+$"1746                    -1747                      type: "null"1748                can_send:1749                  type: "boolean"1750                can_receive:1751                  type: "boolean"1752                status:1753                  type: "string"1754                  enum:1755                    - "active"1756                    - "suspended"1757                expires_at:1758                  type:1759                    - "string"1760                    - "null"1761                retention_days:1762                  anyOf:1763                    -1764                      type: "integer"1765                      minimum: 11766                      maximum: 365001767                    -1768                      type: "null"1769                retention_trash_days:1770                  anyOf:1771                    -1772                      type: "integer"1773                      minimum: 11774                      maximum: 365001775                    -1776                      type: "null"1777                retention_junk_days:1778                  anyOf:1779                    -1780                      type: "integer"1781                      minimum: 11782                      maximum: 365001783                    -1784                      type: "null"1785                quota_bytes:1786                  anyOf:1787                    -1788                      type: "integer"1789                      minimum: 10000001790                      maximum: 10000000000001791                    -1792                      type: "null"1793                reply_policy:1794                  type: "string"1795                  enum:1796                    - "reject"1797                    - "accept"1798                    - "discard"1799                extra_destinations:1800                  maxItems: 201801                  type: "array"1802                  items:1803                    type: "string"1804                    maxLength: 2541805                kind:1806                  type: "string"1807                  enum:1808                    - "mailbox"1809                    - "alias"1810                    - "shared"1811                    - "notification"1812                    - "send_only"1813                    - "receive_only"1814                    - "temporary"1815                protected:1816                  type: "boolean"1817              additionalProperties: false1818      responses:1819        "200":1820          description: "Success"1821          content:1822            "application/json":1823              schema:1824                type: "object"1825                properties:1826                  id:1827                    type: "string"1828                  address:1829                    type: "string"1830                  kind:1831                    type: "string"1832                    enum:1833                      - "mailbox"1834                      - "alias"1835                      - "shared"1836                      - "notification"1837                      - "send_only"1838                      - "receive_only"1839                      - "temporary"1840                  mailbox:1841                    description: "Primary address of the physical mailbox that stores and sends for this address"1842                    type:1843                      - "string"1844                      - "null"1845                  mailbox_id:1846                    type: "string"1847                  display_name:1848                    type: "string"1849                  signature_text:1850                    type: "string"1851                  signature_html:1852                    type: "string"1853                  avatar:1854                    type:1855                      - "string"1856                      - "null"1857                  can_send:1858                    type: "boolean"1859                  can_receive:1860                    type: "boolean"1861                  status:1862                    type: "string"1863                    enum:1864                      - "active"1865                      - "suspended"1866                  suspended_reason:1867                    type:1868                      - "string"1869                      - "null"1870                  expired:1871                    type: "boolean"1872                  expires_at:1873                    type:1874                      - "string"1875                      - "null"1876                  retention_days:1877                    type:1878                      - "number"1879                      - "null"1880                  retention_trash_days:1881                    type:1882                      - "number"1883                      - "null"1884                  retention_junk_days:1885                    type:1886                      - "number"1887                      - "null"1888                  quota_bytes:1889                    type:1890                      - "number"1891                      - "null"1892                  reply_policy:1893                    type: "string"1894                    enum:1895                      - "reject"1896                      - "accept"1897                      - "discard"1898                  protected:1899                    type: "boolean"1900                  extra_destinations:1901                    type: "array"1902                    items:1903                      type: "string"1904                  inbound:1905                    type: "string"1906                    enum:1907                      - "accept"1908                      - "reject"1909                      - "discard"1910                    description: "What the mail server currently does with mail for this address"1911                  created_at:1912                    type: "string"1913                  updated_at:1914                    type: "string"1915                required:1916                  - "id"1917                  - "address"1918                  - "kind"1919                  - "mailbox"1920                  - "mailbox_id"1921                  - "display_name"1922                  - "signature_text"1923                  - "signature_html"1924                  - "avatar"1925                  - "can_send"1926                  - "can_receive"1927                  - "status"1928                  - "suspended_reason"1929                  - "expired"1930                  - "expires_at"1931                  - "retention_days"1932                  - "retention_trash_days"1933                  - "retention_junk_days"1934                  - "quota_bytes"1935                  - "reply_policy"1936                  - "protected"1937                  - "extra_destinations"1938                  - "inbound"1939                  - "created_at"1940                  - "updated_at"1941                additionalProperties: false1942        default:1943          description: "Error"1944          content:1945            "application/json":1946              schema:1947                "$ref": "#/components/schemas/Error"1948      security:1949        -1950          apiKey: []1951        -1952          session: []1953      x-required-scopes:1954        - "mail.aliases.manage"1955        - "mail.addresses.manage"1956  "/drafts":1957    get:1958      operationId: "getDrafts"1959      tags:1960        - "Drafts"1961      summary: "List drafts"1962      parameters:1963        -1964          name: "address"1965          in: "query"1966          required: false1967          description: "Comma-separated addresses to read (each must be allowed). A mailbox's primary address means the whole mailbox; an alias means only mail delivered to / sent from it. Omitted = every address the caller may read."1968          schema:1969            type: "string"1970            maxLength: 20001971        -1972          name: "limit"1973          in: "query"1974          required: false1975          schema:1976            default: 251977            type: "integer"1978            minimum: 11979            maximum: 1001980        -1981          name: "cursor"1982          in: "query"1983          required: false1984          schema:1985            type: "string"1986            maxLength: 20001987      responses:1988        "200":1989          description: "Success"1990          content:1991            "application/json":1992              schema:1993                type: "object"1994                properties:1995                  data:1996                    type: "array"1997                    items:1998                      type: "object"1999                      properties:2000                        id:2001                          type: "string"2002                        thread_id:2003                          type: "string"2004                        mailbox:2005                          type: "string"2006                          description: "Primary address of the physical mailbox holding the message"2007                        delivered_to:2008                          type: "array"2009                          items:2010                            type: "string"2011                          description: "Envelope recipients recorded by the mail server (Delivered-To)"2012                        folders:2013                          type: "array"2014                          items:2015                            type: "object"2016                            properties:2017                              id:2018                                type: "string"2019                              role:2020                                type:2021                                  - "string"2022                                  - "null"2023                              name:2024                                type: "string"2025                            required:2026                              - "id"2027                              - "role"2028                              - "name"2029                            additionalProperties: false2030                        from:2031                          type: "array"2032                          items:2033                            type: "object"2034                            properties:2035                              email:2036                                type: "string"2037                              name:2038                                type:2039                                  - "string"2040                                  - "null"2041                            required:2042                              - "email"2043                              - "name"2044                            additionalProperties: false2045                        to:2046                          type: "array"2047                          items:2048                            type: "object"2049                            properties:2050                              email:2051                                type: "string"2052                              name:2053                                type:2054                                  - "string"2055                                  - "null"2056                            required:2057                              - "email"2058                              - "name"2059                            additionalProperties: false2060                        cc:2061                          type: "array"2062                          items:2063                            type: "object"2064                            properties:2065                              email:2066                                type: "string"2067                              name:2068                                type:2069                                  - "string"2070                                  - "null"2071                            required:2072                              - "email"2073                              - "name"2074                            additionalProperties: false2075                        subject:2076                          type: "string"2077                        preview:2078                          type: "string"2079                        received_at:2080                          type: "string"2081                        sent_at:2082                          type:2083                            - "string"2084                            - "null"2085                        size:2086                          type: "number"2087                        unread:2088                          type: "boolean"2089                        starred:2090                          type: "boolean"2091                        draft:2092                          type: "boolean"2093                        answered:2094                          type: "boolean"2095                        forwarded:2096                          type: "boolean"2097                        has_attachment:2098                          type: "boolean"2099                        labels:2100                          type: "array"2101                          items:2102                            type: "string"2103                        pinned:2104                          type: "boolean"2105                          description: "Pinned to the top of its lists (`$pinned` keyword)"2106                        snoozed:2107                          type: "boolean"2108                          description: "Currently snoozed (`$snoozed` keyword); it returns to the inbox when the snooze ends"2109                        followup:2110                          type: "boolean"2111                          description: "A follow-up reminder is set on the message (`$followup` keyword)"2112                      required:2113                        - "id"2114                        - "thread_id"2115                        - "mailbox"2116                        - "delivered_to"2117                        - "folders"2118                        - "from"2119                        - "to"2120                        - "cc"2121                        - "subject"2122                        - "preview"2123                        - "received_at"2124                        - "sent_at"2125                        - "size"2126                        - "unread"2127                        - "starred"2128                        - "draft"2129                        - "answered"2130                        - "forwarded"2131                        - "has_attachment"2132                        - "labels"2133                        - "pinned"2134                        - "snoozed"2135                        - "followup"2136                      additionalProperties: false2137                  next_cursor:2138                    type:2139                      - "string"2140                      - "null"2141                  has_more:2142                    type: "boolean"2143                required:2144                  - "data"2145                  - "next_cursor"2146                  - "has_more"2147                additionalProperties: false2148        default:2149          description: "Error"2150          content:2151            "application/json":2152              schema:2153                "$ref": "#/components/schemas/Error"2154      security:2155        -2156          apiKey: []2157        -2158          session: []2159      x-required-scopes:2160        - "mail.drafts"2161    post:2162      operationId: "postDrafts"2163      tags:2164        - "Drafts"2165      summary: "Create a draft"2166      parameters:2167        -2168          name: "Idempotency-Key"2169          in: "header"2170          required: false2171          description: "Replays the stored response for 24 h; a different payload with the same key answers 409."2172          schema:2173            type: "string"2174            maxLength: 2002175      requestBody:2176        required: true2177        content:2178          "application/json":2179            schema:2180              type: "object"2181              properties:2182                from:2183                  type: "string"2184                  maxLength: 2542185                to:2186                  maxItems: 1002187                  type: "array"2188                  items:2189                    anyOf:2190                      -2191                        type: "string"2192                        maxLength: 2542193                      -2194                        type: "object"2195                        properties:2196                          email:2197                            type: "string"2198                            maxLength: 2542199                          name:2200                            type: "string"2201                            maxLength: 1202202                        required:2203                          - "email"2204                cc:2205                  maxItems: 1002206                  type: "array"2207                  items:2208                    anyOf:2209                      -2210                        type: "string"2211                        maxLength: 2542212                      -2213                        type: "object"2214                        properties:2215                          email:2216                            type: "string"2217                            maxLength: 2542218                          name:2219                            type: "string"2220                            maxLength: 1202221                        required:2222                          - "email"2223                bcc:2224                  maxItems: 1002225                  type: "array"2226                  items:2227                    anyOf:2228                      -2229                        type: "string"2230                        maxLength: 2542231                      -2232                        type: "object"2233                        properties:2234                          email:2235                            type: "string"2236                            maxLength: 2542237                          name:2238                            type: "string"2239                            maxLength: 1202240                        required:2241                          - "email"2242                subject:2243                  default: ""2244                  type: "string"2245                  maxLength: 9982246                text:2247                  type: "string"2248                  maxLength: 20000002249                html:2250                  description: "Sanitised server-side with a strict allowlist before being stored or sent"2251                  type: "string"2252                  maxLength: 20000002253                attachments:2254                  default: []2255                  maxItems: 302256                  type: "array"2257                  items:2258                    type: "object"2259                    properties:2260                      file_id:2261                        type: "string"2262                        pattern: "^file_[A-Za-z0-9_-]{10,60}$"2263                      filename:2264                        type: "string"2265                        maxLength: 2002266                      inline:2267                        description: "Inline image referenced from the HTML as cid:<cid>"2268                        type: "boolean"2269                      cid:2270                        type: "string"2271                        pattern: "^[A-Za-z0-9._@-]{1,100}$"2272                    required:2273                      - "file_id"2274                    additionalProperties: false2275                reply_to_message_id:2276                  description: "Message (msg_…) being answered: sets In-Reply-To / References from it"2277                  type: "string"2278                  maxLength: 4002279                in_reply_to:2280                  type: "string"2281                  maxLength: 5002282                references:2283                  maxItems: 502284                  type: "array"2285                  items:2286                    type: "string"2287                    maxLength: 5002288                headers:2289                  description: "Only X-*, Reply-To, List-Unsubscribe, List-Unsubscribe-Post"2290                  type: "object"2291                  propertyNames:2292                    type: "string"2293                    maxLength: 642294                  additionalProperties:2295                    type: "string"2296                    maxLength: 9002297                priority:2298                  type: "string"2299                  enum:2300                    - "high"2301                    - "normal"2302                    - "low"2303              required:2304                - "from"2305              additionalProperties: false2306      responses:2307        "201":2308          description: "Success"2309          content:2310            "application/json":2311              schema:2312                type: "object"2313                properties:2314                  id:2315                    type: "string"2316                    description: "msg_out_… (or the draft's msg_… id when status is draft)"2317                  status:2318                    type: "string"2319                    enum:2320                      - "queued"2321                      - "scheduled"2322                      - "pending_approval"2323                      - "sent"2324                      - "delivered"2325                      - "deferred"2326                      - "bounced"2327                      - "failed"2328                      - "cancelled"2329                      - "draft"2330                  from:2331                    type: "string"2332                  message_id:2333                    type:2334                      - "string"2335                      - "null"2336                  recipients:2337                    type: "array"2338                    items:2339                      type: "object"2340                      properties:2341                        address:2342                          type: "string"2343                        status:2344                          type: "string"2345                        smtp_reply:2346                          type:2347                            - "string"2348                            - "null"2349                      required:2350                        - "address"2351                        - "status"2352                        - "smtp_reply"2353                      additionalProperties: false2354                  external:2355                    type: "boolean"2356                  send_at:2357                    type:2358                      - "string"2359                      - "null"2360                  attempts:2361                    type: "number"2362                  last_error:2363                    type:2364                      - "string"2365                      - "null"2366                  submitted_at:2367                    type:2368                      - "string"2369                      - "null"2370                  final_at:2371                    type:2372                      - "string"2373                      - "null"2374                  created_at:2375                    type: "string"2376                  updated_at:2377                    type: "string"2378                  approval_id:2379                    type: "string"2380                  thread_id:2381                    type:2382                      - "string"2383                      - "null"2384                  undo_until:2385                    description: "Undo send: the message is held until this instant and can still be cancelled"2386                    type:2387                      - "string"2388                      - "null"2389                required:2390                  - "id"2391                  - "status"2392                  - "from"2393                  - "message_id"2394                  - "recipients"2395                  - "external"2396                  - "send_at"2397                  - "attempts"2398                  - "last_error"2399                  - "submitted_at"2400                  - "final_at"2401                  - "created_at"2402                  - "updated_at"2403                additionalProperties: false2404        default:2405          description: "Error"2406          content:2407            "application/json":2408              schema:2409                "$ref": "#/components/schemas/Error"2410      security:2411        -2412          apiKey: []2413        -2414          session: []2415      x-required-scopes:2416        - "mail.drafts"2417  "/drafts/{id}":2418    delete:2419      operationId: "deleteDraftsId"2420      tags:2421        - "Drafts"2422      summary: "Discard a draft (destroyed, not moved to trash)"2423      parameters:2424        -2425          name: "id"2426          in: "path"2427          required: true2428          schema:2429            type: "string"2430            maxLength: 4002431      responses:2432        "200":2433          description: "Success"2434          content:2435            "application/json":2436              schema:2437                type: "object"2438                properties:2439                  ok:2440                    type: "boolean"2441                    const: true2442                required:2443                  - "ok"2444                additionalProperties: false2445        default:2446          description: "Error"2447          content:2448            "application/json":2449              schema:2450                "$ref": "#/components/schemas/Error"2451      security:2452        -2453          apiKey: []2454        -2455          session: []2456      x-required-scopes:2457        - "mail.drafts"2458    get:2459      operationId: "getDraftsId"2460      tags:2461        - "Drafts"2462      summary: "Read a draft"2463      parameters:2464        -2465          name: "id"2466          in: "path"2467          required: true2468          schema:2469            type: "string"2470            maxLength: 4002471      responses:2472        "200":2473          description: "Success"2474          content:2475            "application/json":2476              schema:2477                type: "object"2478                properties:2479                  id:2480                    type: "string"2481                  thread_id:2482                    type: "string"2483                  mailbox:2484                    type: "string"2485                    description: "Primary address of the physical mailbox holding the message"2486                  delivered_to:2487                    type: "array"2488                    items:2489                      type: "string"2490                    description: "Envelope recipients recorded by the mail server (Delivered-To)"2491                  folders:2492                    type: "array"2493                    items:2494                      type: "object"2495                      properties:2496                        id:2497                          type: "string"2498                        role:2499                          type:2500                            - "string"2501                            - "null"2502                        name:2503                          type: "string"2504                      required:2505                        - "id"2506                        - "role"2507                        - "name"2508                      additionalProperties: false2509                  from:2510                    type: "array"2511                    items:2512                      type: "object"2513                      properties:2514                        email:2515                          type: "string"2516                        name:2517                          type:2518                            - "string"2519                            - "null"2520                      required:2521                        - "email"2522                        - "name"2523                      additionalProperties: false2524                  to:2525                    type: "array"2526                    items:2527                      type: "object"2528                      properties:2529                        email:2530                          type: "string"2531                        name:2532                          type:2533                            - "string"2534                            - "null"2535                      required:2536                        - "email"2537                        - "name"2538                      additionalProperties: false2539                  cc:2540                    type: "array"2541                    items:2542                      type: "object"2543                      properties:2544                        email:2545                          type: "string"2546                        name:2547                          type:2548                            - "string"2549                            - "null"2550                      required:2551                        - "email"2552                        - "name"2553                      additionalProperties: false2554                  subject:2555                    type: "string"2556                  preview:2557                    type: "string"2558                  received_at:2559                    type: "string"2560                  sent_at:2561                    type:2562                      - "string"2563                      - "null"2564                  size:2565                    type: "number"2566                  unread:2567                    type: "boolean"2568                  starred:2569                    type: "boolean"2570                  draft:2571                    type: "boolean"2572                  answered:2573                    type: "boolean"2574                  forwarded:2575                    type: "boolean"2576                  has_attachment:2577                    type: "boolean"2578                  labels:2579                    type: "array"2580                    items:2581                      type: "string"2582                  pinned:2583                    type: "boolean"2584                    description: "Pinned to the top of its lists (`$pinned` keyword)"2585                  snoozed:2586                    type: "boolean"2587                    description: "Currently snoozed (`$snoozed` keyword); it returns to the inbox when the snooze ends"2588                  followup:2589                    type: "boolean"2590                    description: "A follow-up reminder is set on the message (`$followup` keyword)"2591                  bcc:2592                    type: "array"2593                    items:2594                      type: "object"2595                      properties:2596                        email:2597                          type: "string"2598                        name:2599                          type:2600                            - "string"2601                            - "null"2602                      required:2603                        - "email"2604                        - "name"2605                      additionalProperties: false2606                  reply_to:2607                    type: "array"2608                    items:2609                      type: "object"2610                      properties:2611                        email:2612                          type: "string"2613                        name:2614                          type:2615                            - "string"2616                            - "null"2617                      required:2618                        - "email"2619                        - "name"2620                      additionalProperties: false2621                  message_id:2622                    type:2623                      - "string"2624                      - "null"2625                  in_reply_to:2626                    type: "array"2627                    items:2628                      type: "string"2629                  references:2630                    type: "array"2631                    items:2632                      type: "string"2633                  headers:2634                    type: "array"2635                    items:2636                      type: "object"2637                      properties:2638                        name:2639                          type: "string"2640                        value:2641                          type: "string"2642                      required:2643                        - "name"2644                        - "value"2645                      additionalProperties: false2646                  text:2647                    type:2648                      - "string"2649                      - "null"2650                  html:2651                    description: "Sanitised server-side (strict allowlist); remote images are NOT fetched or rewritten"2652                    type:2653                      - "string"2654                      - "null"2655                  truncated:2656                    type: "boolean"2657                  attachments:2658                    type: "array"2659                    items:2660                      type: "object"2661                      properties:2662                        id:2663                          type: "string"2664                        name:2665                          type:2666                            - "string"2667                            - "null"2668                        type:2669                          type: "string"2670                        size:2671                          type: "number"2672                        cid:2673                          type:2674                            - "string"2675                            - "null"2676                        disposition:2677                          type:2678                            - "string"2679                            - "null"2680                        inline:2681                          type: "boolean"2682                      required:2683                        - "id"2684                        - "name"2685                        - "type"2686                        - "size"2687                        - "cid"2688                        - "disposition"2689                        - "inline"2690                      additionalProperties: false2691                  auth:2692                    type: "object"2693                    properties:2694                      spf:2695                        type:2696                          - "string"2697                          - "null"2698                      dkim:2699                        type:2700                          - "string"2701                          - "null"2702                      dmarc:2703                        type:2704                          - "string"2705                          - "null"2706                      raw:2707                        type:2708                          - "string"2709                          - "null"2710                    required:2711                      - "spf"2712                      - "dkim"2713                      - "dmarc"2714                      - "raw"2715                    additionalProperties: false2716                required:2717                  - "id"2718                  - "thread_id"2719                  - "mailbox"2720                  - "delivered_to"2721                  - "folders"2722                  - "from"2723                  - "to"2724                  - "cc"2725                  - "subject"2726                  - "preview"2727                  - "received_at"2728                  - "sent_at"2729                  - "size"2730                  - "unread"2731                  - "starred"2732                  - "draft"2733                  - "answered"2734                  - "forwarded"2735                  - "has_attachment"2736                  - "labels"2737                  - "pinned"2738                  - "snoozed"2739                  - "followup"2740                  - "bcc"2741                  - "reply_to"2742                  - "message_id"2743                  - "in_reply_to"2744                  - "references"2745                  - "headers"2746                  - "text"2747                  - "html"2748                  - "truncated"2749                  - "attachments"2750                  - "auth"2751                additionalProperties: false2752        default:2753          description: "Error"2754          content:2755            "application/json":2756              schema:2757                "$ref": "#/components/schemas/Error"2758      security:2759        -2760          apiKey: []2761        -2762          session: []2763      x-required-scopes:2764        - "mail.drafts"2765    patch:2766      operationId: "patchDraftsId"2767      tags:2768        - "Drafts"2769      summary: "Replace fields of a draft"2770      description: "Messages are immutable on the mail server: the draft is recreated with the merged fields and the response carries its NEW id. Attachments are kept unless `attachments` is given."2771      parameters:2772        -2773          name: "id"2774          in: "path"2775          required: true2776          schema:2777            type: "string"2778            maxLength: 4002779      requestBody:2780        required: true2781        content:2782          "application/json":2783            schema:2784              type: "object"2785              properties:2786                from:2787                  description: "Sender address; must be in the caller's allowlist, active and allowed to send"2788                  type: "string"2789                  maxLength: 2542790                to:2791                  maxItems: 1002792                  type: "array"2793                  items:2794                    anyOf:2795                      -2796                        type: "string"2797                        maxLength: 2542798                      -2799                        type: "object"2800                        properties:2801                          email:2802                            type: "string"2803                            maxLength: 2542804                          name:2805                            type: "string"2806                            maxLength: 1202807                        required:2808                          - "email"2809                cc:2810                  maxItems: 1002811                  type: "array"2812                  items:2813                    anyOf:2814                      -2815                        type: "string"2816                        maxLength: 2542817                      -2818                        type: "object"2819                        properties:2820                          email:2821                            type: "string"2822                            maxLength: 2542823                          name:2824                            type: "string"2825                            maxLength: 1202826                        required:2827                          - "email"2828                bcc:2829                  maxItems: 1002830                  type: "array"2831                  items:2832                    anyOf:2833                      -2834                        type: "string"2835                        maxLength: 2542836                      -2837                        type: "object"2838                        properties:2839                          email:2840                            type: "string"2841                            maxLength: 2542842                          name:2843                            type: "string"2844                            maxLength: 1202845                        required:2846                          - "email"2847                subject:2848                  type: "string"2849                  maxLength: 9982850                text:2851                  type: "string"2852                  maxLength: 20000002853                html:2854                  description: "Sanitised server-side with a strict allowlist before being stored or sent"2855                  type: "string"2856                  maxLength: 20000002857                attachments:2858                  maxItems: 302859                  type: "array"2860                  items:2861                    type: "object"2862                    properties:2863                      file_id:2864                        type: "string"2865                        pattern: "^file_[A-Za-z0-9_-]{10,60}$"2866                      filename:2867                        type: "string"2868                        maxLength: 2002869                      inline:2870                        description: "Inline image referenced from the HTML as cid:<cid>"2871                        type: "boolean"2872                      cid:2873                        type: "string"2874                        pattern: "^[A-Za-z0-9._@-]{1,100}$"2875                    required:2876                      - "file_id"2877                    additionalProperties: false2878                reply_to_message_id:2879                  description: "Message (msg_…) being answered: sets In-Reply-To / References from it"2880                  type: "string"2881                  maxLength: 4002882                in_reply_to:2883                  type: "string"2884                  maxLength: 5002885                references:2886                  maxItems: 502887                  type: "array"2888                  items:2889                    type: "string"2890                    maxLength: 5002891                headers:2892                  description: "Only X-*, Reply-To, List-Unsubscribe, List-Unsubscribe-Post"2893                  type: "object"2894                  propertyNames:2895                    type: "string"2896                    maxLength: 642897                  additionalProperties:2898                    type: "string"2899                    maxLength: 9002900                priority:2901                  type: "string"2902                  enum:2903                    - "high"2904                    - "normal"2905                    - "low"2906              additionalProperties: false2907      responses:2908        "200":2909          description: "Success"2910          content:2911            "application/json":2912              schema:2913                type: "object"2914                properties:2915                  id:2916                    type: "string"2917                    description: "msg_out_… (or the draft's msg_… id when status is draft)"2918                  status:2919                    type: "string"2920                    enum:2921                      - "queued"2922                      - "scheduled"2923                      - "pending_approval"2924                      - "sent"2925                      - "delivered"2926                      - "deferred"2927                      - "bounced"2928                      - "failed"2929                      - "cancelled"2930                      - "draft"2931                  from:2932                    type: "string"2933                  message_id:2934                    type:2935                      - "string"2936                      - "null"2937                  recipients:2938                    type: "array"2939                    items:2940                      type: "object"2941                      properties:2942                        address:2943                          type: "string"2944                        status:2945                          type: "string"2946                        smtp_reply:2947                          type:2948                            - "string"2949                            - "null"2950                      required:2951                        - "address"2952                        - "status"2953                        - "smtp_reply"2954                      additionalProperties: false2955                  external:2956                    type: "boolean"2957                  send_at:2958                    type:2959                      - "string"2960                      - "null"2961                  attempts:2962                    type: "number"2963                  last_error:2964                    type:2965                      - "string"2966                      - "null"2967                  submitted_at:2968                    type:2969                      - "string"2970                      - "null"2971                  final_at:2972                    type:2973                      - "string"2974                      - "null"2975                  created_at:2976                    type: "string"2977                  updated_at:2978                    type: "string"2979                  approval_id:2980                    type: "string"2981                  thread_id:2982                    type:2983                      - "string"2984                      - "null"2985                  undo_until:2986                    description: "Undo send: the message is held until this instant and can still be cancelled"2987                    type:2988                      - "string"2989                      - "null"2990                required:2991                  - "id"2992                  - "status"2993                  - "from"2994                  - "message_id"2995                  - "recipients"2996                  - "external"2997                  - "send_at"2998                  - "attempts"2999                  - "last_error"3000                  - "submitted_at"3001                  - "final_at"3002                  - "created_at"3003                  - "updated_at"3004                additionalProperties: false3005        default:3006          description: "Error"3007          content:3008            "application/json":3009              schema:3010                "$ref": "#/components/schemas/Error"3011      security:3012        -3013          apiKey: []3014        -3015          session: []3016      x-required-scopes:3017        - "mail.drafts"3018  "/drafts/{id}/send":3019    post:3020      operationId: "postDraftsIdSend"3021      tags:3022        - "Drafts"3023      summary: "Send an existing draft"3024      description: "The draft's From must be an address the caller may send from; the same policy checks as POST /messages/send apply."3025      parameters:3026        -3027          name: "id"3028          in: "path"3029          required: true3030          schema:3031            type: "string"3032            maxLength: 4003033        -3034          name: "Idempotency-Key"3035          in: "header"3036          required: false3037          description: "Replays the stored response for 24 h; a different payload with the same key answers 409."3038          schema:3039            type: "string"3040            maxLength: 2003041      requestBody:3042        required: true3043        content:3044          "application/json":3045            schema:3046              type: "object"3047              properties:3048                send_at:3049                  type: "string"3050              additionalProperties: false3051      responses:3052        "200":3053          description: "Success"3054          content:3055            "application/json":3056              schema:3057                type: "object"3058                properties:3059                  id:3060                    type: "string"3061                    description: "msg_out_… (or the draft's msg_… id when status is draft)"3062                  status:3063                    type: "string"3064                    enum:3065                      - "queued"3066                      - "scheduled"3067                      - "pending_approval"3068                      - "sent"3069                      - "delivered"3070                      - "deferred"3071                      - "bounced"3072                      - "failed"3073                      - "cancelled"3074                      - "draft"3075                  from:3076                    type: "string"3077                  message_id:3078                    type:3079                      - "string"3080                      - "null"3081                  recipients:3082                    type: "array"3083                    items:3084                      type: "object"3085                      properties:3086                        address:3087                          type: "string"3088                        status:3089                          type: "string"3090                        smtp_reply:3091                          type:3092                            - "string"3093                            - "null"3094                      required:3095                        - "address"3096                        - "status"3097                        - "smtp_reply"3098                      additionalProperties: false3099                  external:3100                    type: "boolean"3101                  send_at:3102                    type:3103                      - "string"3104                      - "null"3105                  attempts:3106                    type: "number"3107                  last_error:3108                    type:3109                      - "string"3110                      - "null"3111                  submitted_at:3112                    type:3113                      - "string"3114                      - "null"3115                  final_at:3116                    type:3117                      - "string"3118                      - "null"3119                  created_at:3120                    type: "string"3121                  updated_at:3122                    type: "string"3123                  approval_id:3124                    type: "string"3125                  thread_id:3126                    type:3127                      - "string"3128                      - "null"3129                  undo_until:3130                    description: "Undo send: the message is held until this instant and can still be cancelled"3131                    type:3132                      - "string"3133                      - "null"3134                required:3135                  - "id"3136                  - "status"3137                  - "from"3138                  - "message_id"3139                  - "recipients"3140                  - "external"3141                  - "send_at"3142                  - "attempts"3143                  - "last_error"3144                  - "submitted_at"3145                  - "final_at"3146                  - "created_at"3147                  - "updated_at"3148                additionalProperties: false3149        "202":3150          description: "Accepted"3151        default:3152          description: "Error"3153          content:3154            "application/json":3155              schema:3156                "$ref": "#/components/schemas/Error"3157      security:3158        -3159          apiKey: []3160        -3161          session: []3162      x-required-scopes:3163        - "mail.send"3164  "/events":3165    get:3166      operationId: "getEvents"3167      tags:3168        - "Webhooks"3169      summary: "Recent events visible to the caller (metadata only, newest first)"3170      description: "Events are kept 30 days. Content fields (subject, preview) are never returned here."3171      parameters:3172        -3173          name: "type"3174          in: "query"3175          required: false3176          schema:3177            type: "string"3178            enum:3179              - "message.received"3180              - "message.sent"3181              - "message.delivered"3182              - "message.deferred"3183              - "message.bounced"3184              - "message.failed"3185              - "message.read"3186              - "message.deleted"3187              - "draft.created"3188              - "address.created"3189              - "address.suspended"3190              - "rule.matched"3191        -3192          name: "limit"3193          in: "query"3194          required: false3195          schema:3196            default: 253197            type: "integer"3198            minimum: 13199            maximum: 1003200        -3201          name: "cursor"3202          in: "query"3203          required: false3204          schema:3205            type: "string"3206            maxLength: 20003207      responses:3208        "200":3209          description: "Success"3210          content:3211            "application/json":3212              schema:3213                type: "object"3214                properties:3215                  data:3216                    type: "array"3217                    items:3218                      type: "object"3219                      properties:3220                        id:3221                          type: "string"3222                        type:3223                          type: "string"3224                        occurred_at:3225                          type: "string"3226                        address:3227                          type:3228                            - "string"3229                            - "null"3230                        mailbox:3231                          type:3232                            - "string"3233                            - "null"3234                        data:3235                          type: "object"3236                          propertyNames:3237                            type: "string"3238                          additionalProperties: {}3239                      required:3240                        - "id"3241                        - "type"3242                        - "occurred_at"3243                        - "address"3244                        - "mailbox"3245                        - "data"3246                      additionalProperties: false3247                  next_cursor:3248                    type:3249                      - "string"3250                      - "null"3251                  has_more:3252                    type: "boolean"3253                required:3254                  - "data"3255                  - "next_cursor"3256                  - "has_more"3257                additionalProperties: false3258        default:3259          description: "Error"3260          content:3261            "application/json":3262              schema:3263                "$ref": "#/components/schemas/Error"3264      security:3265        -3266          apiKey: []3267        -3268          session: []3269      x-required-scopes:3270        - "mail.read"3271        - "mail.webhooks.manage"3272        - "mail.send"3273  "/files":3274    post:3275      operationId: "postFiles"3276      tags:3277        - "Attachments"3278      summary: "Upload a file to attach later (raw body)"3279      description: "Send the bytes as the raw request body with the file's Content-Type (multipart/form-data is NOT parsed). `address` selects the mailbox the file is bound to: it can only be attached to messages sent from that mailbox, by the caller that uploaded it. Max 50 MB. Not idempotent."3280      parameters:3281        -3282          name: "filename"3283          in: "query"3284          required: false3285          schema:3286            default: "file"3287            type: "string"3288            maxLength: 2003289        -3290          name: "address"3291          in: "query"3292          required: false3293          description: "An address the caller may send from (required when several mailboxes are allowed)"3294          schema:3295            type: "string"3296            maxLength: 2543297      requestBody:3298        required: true3299        content:3300          "application/octet-stream":3301            schema:3302              type: "string"3303              format: "binary"3304      responses:3305        "201":3306          description: "Success"3307          content:3308            "application/json":3309              schema:3310                type: "object"3311                properties:3312                  id:3313                    type: "string"3314                  name:3315                    type: "string"3316                  type:3317                    type: "string"3318                  size:3319                    type: "number"3320                  mailbox:3321                    type: "string"3322                  expires_at:3323                    type: "string"3324                required:3325                  - "id"3326                  - "name"3327                  - "type"3328                  - "size"3329                  - "mailbox"3330                  - "expires_at"3331                additionalProperties: false3332        "413":3333          description: "file_too_large"3334        default:3335          description: "Error"3336          content:3337            "application/json":3338              schema:3339                "$ref": "#/components/schemas/Error"3340      security:3341        -3342          apiKey: []3343        -3344          session: []3345      x-required-scopes:3346        - "mail.attachments.write"3347  "/folders":3348    get:3349      operationId: "getFolders"3350      tags:3351        - "Folders"3352      summary: "Folders of the readable mailboxes"3353      description: "Counts are null for address-restricted views (they would reveal the volume of the whole mailbox)."3354      parameters:3355        -3356          name: "address"3357          in: "query"3358          required: false3359          schema:3360            type: "string"3361            maxLength: 20003362      responses:3363        "200":3364          description: "Success"3365          content:3366            "application/json":3367              schema:3368                type: "object"3369                properties:3370                  data:3371                    type: "array"3372                    items:3373                      type: "object"3374                      properties:3375                        id:3376                          type: "string"3377                        mailbox:3378                          type: "string"3379                        name:3380                          type: "string"3381                        role:3382                          type:3383                            - "string"3384                            - "null"3385                        parent_id:3386                          type:3387                            - "string"3388                            - "null"3389                        total:3390                          type:3391                            - "number"3392                            - "null"3393                        unread:3394                          type:3395                            - "number"3396                            - "null"3397                      required:3398                        - "id"3399                        - "mailbox"3400                        - "name"3401                        - "role"3402                        - "parent_id"3403                        - "total"3404                        - "unread"3405                      additionalProperties: false3406                required:3407                  - "data"3408                additionalProperties: false3409        default:3410          description: "Error"3411          content:3412            "application/json":3413              schema:3414                "$ref": "#/components/schemas/Error"3415      security:3416        -3417          apiKey: []3418        -3419          session: []3420      x-required-scopes:3421        - "mail.read"3422    post:3423      operationId: "postFolders"3424      tags:3425        - "Folders"3426      summary: "Create a folder in a mailbox"3427      parameters:3428        -3429          name: "Idempotency-Key"3430          in: "header"3431          required: false3432          description: "Replays the stored response for 24 h; a different payload with the same key answers 409."3433          schema:3434            type: "string"3435            maxLength: 2003436      requestBody:3437        required: true3438        content:3439          "application/json":3440            schema:3441              type: "object"3442              properties:3443                address:3444                  type: "string"3445                  maxLength: 2543446                  description: "Primary address of the mailbox"3447                name:3448                  type: "string"3449                  minLength: 13450                  maxLength: 1003451                parent_id:3452                  type: "string"3453                  maxLength: 3003454              required:3455                - "address"3456                - "name"3457              additionalProperties: false3458      responses:3459        "201":3460          description: "Success"3461          content:3462            "application/json":3463              schema:3464                type: "object"3465                properties:3466                  id:3467                    type: "string"3468                  mailbox:3469                    type: "string"3470                  name:3471                    type: "string"3472                  role:3473                    type:3474                      - "string"3475                      - "null"3476                  parent_id:3477                    type:3478                      - "string"3479                      - "null"3480                  total:3481                    type:3482                      - "number"3483                      - "null"3484                  unread:3485                    type:3486                      - "number"3487                      - "null"3488                required:3489                  - "id"3490                  - "mailbox"3491                  - "name"3492                  - "role"3493                  - "parent_id"3494                  - "total"3495                  - "unread"3496                additionalProperties: false3497        default:3498          description: "Error"3499          content:3500            "application/json":3501              schema:3502                "$ref": "#/components/schemas/Error"3503      security:3504        -3505          apiKey: []3506        -3507          session: []3508      x-required-scopes:3509        - "mail.modify"3510  "/health":3511    get:3512      operationId: "getHealth"3513      tags:3514        - "Introspection"3515      summary: "Liveness of the API, database and mail server"3516      responses:3517        "200":3518          description: "Success"3519          content:3520            "application/json":3521              schema:3522                type: "object"3523                properties:3524                  ok:3525                    type: "boolean"3526                  version:3527                    type: "string"3528                  database:3529                    type: "string"3530                    enum:3531                      - "ok"3532                      - "down"3533                  mail_server:3534                    type: "string"3535                    enum:3536                      - "reachable"3537                      - "unreachable"3538                  workers:3539                    type: "string"3540                    enum:3541                      - "on"3542                      - "off"3543                required:3544                  - "ok"3545                  - "version"3546                  - "database"3547                  - "mail_server"3548                  - "workers"3549                additionalProperties: false3550        "503":3551          description: "Database or mail server unreachable (same body)"3552        default:3553          description: "Error"3554          content:3555            "application/json":3556              schema:3557                "$ref": "#/components/schemas/Error"3558      security: []3559      x-required-scopes: []3560  "/me":3561    get:3562      operationId: "getMe"3563      tags:3564        - "Introspection"3565      summary: "Who am I: scopes, allowed addresses, limits, usage today"3566      responses:3567        "200":3568          description: "Success"3569          content:3570            "application/json":3571              schema:3572                type: "object"3573                properties:3574                  type:3575                    type: "string"3576                    enum:3577                      - "key"3578                      - "user"3579                  id:3580                    type: "string"3581                  name:3582                    type: "string"3583                  explorer:3584                    type: "boolean"3585                  scopes:3586                    type: "array"3587                    items:3588                      type: "string"3589                  all_addresses:3590                    type: "boolean"3591                  addresses:3592                    type: "array"3593                    items:3594                      type: "object"3595                      properties:3596                        id:3597                          type: "string"3598                        address:3599                          type: "string"3600                        kind:3601                          type: "string"3602                        mailbox:3603                          type: "string"3604                        status:3605                          type: "string"3606                        can_send:3607                          type: "boolean"3608                        can_receive:3609                          type: "boolean"3610                        read:3611                          type: "string"3612                          enum:3613                            - "full"3614                            - "restricted"3615                            - "none"3616                      required:3617                        - "id"3618                        - "address"3619                        - "kind"3620                        - "mailbox"3621                        - "status"3622                        - "can_send"3623                        - "can_receive"3624                        - "read"3625                      additionalProperties: false3626                  limits:3627                    type: "object"3628                    properties:3629                      rate_per_minute:3630                        type:3631                          - "number"3632                          - "null"3633                      daily_send_limit:3634                        type:3635                          - "number"3636                          - "null"3637                      external_send_policy:3638                        type: "string"3639                      allowed_recipient_domains:3640                        type: "array"3641                        items:3642                          type: "string"3643                    required:3644                      - "rate_per_minute"3645                      - "daily_send_limit"3646                      - "external_send_policy"3647                      - "allowed_recipient_domains"3648                    additionalProperties: false3649                  usage_today:3650                    type: "object"3651                    properties:3652                      sent:3653                        type: "number"3654                      requests:3655                        type: "number"3656                    required:3657                      - "sent"3658                      - "requests"3659                    additionalProperties: false3660                  version:3661                    type: "string"3662                required:3663                  - "type"3664                  - "id"3665                  - "name"3666                  - "explorer"3667                  - "scopes"3668                  - "all_addresses"3669                  - "addresses"3670                  - "limits"3671                  - "usage_today"3672                  - "version"3673                additionalProperties: false3674        default:3675          description: "Error"3676          content:3677            "application/json":3678              schema:3679                "$ref": "#/components/schemas/Error"3680      security:3681        -3682          apiKey: []3683        -3684          session: []3685      x-required-scopes: []3686  "/messages":3687    get:3688      operationId: "getMessages"3689      tags:3690        - "Messages"3691      summary: "List / search messages (unified across mailboxes)"3692      description: "Newest first. With several addresses (or none = all allowed) results are merged across mailboxes by date with a composite cursor: no duplicates, no gaps. Any search filter (from, to, subject, text, label) requires `mail.search`."3693      parameters:3694        -3695          name: "address"3696          in: "query"3697          required: false3698          description: "Comma-separated addresses to read (each must be allowed). A mailbox's primary address means the whole mailbox; an alias means only mail delivered to / sent from it. Omitted = every address the caller may read."3699          schema:3700            type: "string"3701            maxLength: 20003702        -3703          name: "mailbox"3704          in: "query"3705          required: false3706          description: "Synonym of `address` for primary mailbox addresses"3707          schema:3708            type: "string"3709            maxLength: 20003710        -3711          name: "folder"3712          in: "query"3713          required: false3714          description: "Folder role (inbox, drafts, sent, trash, junk, archive) resolved in each mailbox, or a folder id (fld_…)"3715          schema:3716            type: "string"3717            maxLength: 3003718        -3719          name: "unread"3720          in: "query"3721          required: false3722          schema:3723            type: "string"3724            enum:3725              - "true"3726              - "false"3727        -3728          name: "flagged"3729          in: "query"3730          required: false3731          description: "Starred / important"3732          schema:3733            type: "string"3734            enum:3735              - "true"3736              - "false"3737        -3738          name: "has_attachment"3739          in: "query"3740          required: false3741          schema:3742            type: "string"3743            enum:3744              - "true"3745              - "false"3746        -3747          name: "from"3748          in: "query"3749          required: false3750          schema:3751            type: "string"3752            maxLength: 2003753        -3754          name: "to"3755          in: "query"3756          required: false3757          schema:3758            type: "string"3759            maxLength: 2003760        -3761          name: "subject"3762          in: "query"3763          required: false3764          schema:3765            type: "string"3766            maxLength: 2003767        -3768          name: "text"3769          in: "query"3770          required: false3771          description: "Full-text search (headers, bodies and, as far as the server indexes them, attachments)"3772          schema:3773            type: "string"3774            maxLength: 3003775        -3776          name: "before"3777          in: "query"3778          required: false3779          description: "Received strictly before (ISO 8601)"3780          schema:3781            type: "string"3782        -3783          name: "after"3784          in: "query"3785          required: false3786          description: "Received at or after (ISO 8601)"3787          schema:3788            type: "string"3789        -3790          name: "label"3791          in: "query"3792          required: false3793          schema:3794            type: "string"3795        -3796          name: "limit"3797          in: "query"3798          required: false3799          schema:3800            default: 253801            type: "integer"3802            minimum: 13803            maximum: 1003804        -3805          name: "cursor"3806          in: "query"3807          required: false3808          schema:3809            type: "string"3810            maxLength: 20003811      responses:3812        "200":3813          description: "Success"3814          content:3815            "application/json":3816              schema:3817                type: "object"3818                properties:3819                  data:3820                    type: "array"3821                    items:3822                      type: "object"3823                      properties:3824                        id:3825                          type: "string"3826                        thread_id:3827                          type: "string"3828                        mailbox:3829                          type: "string"3830                          description: "Primary address of the physical mailbox holding the message"3831                        delivered_to:3832                          type: "array"3833                          items:3834                            type: "string"3835                          description: "Envelope recipients recorded by the mail server (Delivered-To)"3836                        folders:3837                          type: "array"3838                          items:3839                            type: "object"3840                            properties:3841                              id:3842                                type: "string"3843                              role:3844                                type:3845                                  - "string"3846                                  - "null"3847                              name:3848                                type: "string"3849                            required:3850                              - "id"3851                              - "role"3852                              - "name"3853                            additionalProperties: false3854                        from:3855                          type: "array"3856                          items:3857                            type: "object"3858                            properties:3859                              email:3860                                type: "string"3861                              name:3862                                type:3863                                  - "string"3864                                  - "null"3865                            required:3866                              - "email"3867                              - "name"3868                            additionalProperties: false3869                        to:3870                          type: "array"3871                          items:3872                            type: "object"3873                            properties:3874                              email:3875                                type: "string"3876                              name:3877                                type:3878                                  - "string"3879                                  - "null"3880                            required:3881                              - "email"3882                              - "name"3883                            additionalProperties: false3884                        cc:3885                          type: "array"3886                          items:3887                            type: "object"3888                            properties:3889                              email:3890                                type: "string"3891                              name:3892                                type:3893                                  - "string"3894                                  - "null"3895                            required:3896                              - "email"3897                              - "name"3898                            additionalProperties: false3899                        subject:3900                          type: "string"3901                        preview:3902                          type: "string"3903                        received_at:3904                          type: "string"3905                        sent_at:3906                          type:3907                            - "string"3908                            - "null"3909                        size:3910                          type: "number"3911                        unread:3912                          type: "boolean"3913                        starred:3914                          type: "boolean"3915                        draft:3916                          type: "boolean"3917                        answered:3918                          type: "boolean"3919                        forwarded:3920                          type: "boolean"3921                        has_attachment:3922                          type: "boolean"3923                        labels:3924                          type: "array"3925                          items:3926                            type: "string"3927                        pinned:3928                          type: "boolean"3929                          description: "Pinned to the top of its lists (`$pinned` keyword)"3930                        snoozed:3931                          type: "boolean"3932                          description: "Currently snoozed (`$snoozed` keyword); it returns to the inbox when the snooze ends"3933                        followup:3934                          type: "boolean"3935                          description: "A follow-up reminder is set on the message (`$followup` keyword)"3936                      required:3937                        - "id"3938                        - "thread_id"3939                        - "mailbox"3940                        - "delivered_to"3941                        - "folders"3942                        - "from"3943                        - "to"3944                        - "cc"3945                        - "subject"3946                        - "preview"3947                        - "received_at"3948                        - "sent_at"3949                        - "size"3950                        - "unread"3951                        - "starred"3952                        - "draft"3953                        - "answered"3954                        - "forwarded"3955                        - "has_attachment"3956                        - "labels"3957                        - "pinned"3958                        - "snoozed"3959                        - "followup"3960                      additionalProperties: false3961                  next_cursor:3962                    type:3963                      - "string"3964                      - "null"3965                  has_more:3966                    type: "boolean"3967                required:3968                  - "data"3969                  - "next_cursor"3970                  - "has_more"3971                additionalProperties: false3972        default:3973          description: "Error"3974          content:3975            "application/json":3976              schema:3977                "$ref": "#/components/schemas/Error"3978      security:3979        -3980          apiKey: []3981        -3982          session: []3983      x-required-scopes:3984        - "mail.read"3985        - "mail.search"3986  "/messages/{id}":3987    delete:3988      operationId: "deleteMessagesId"3989      tags:3990        - "Messages"3991      summary: "Move to trash, or delete permanently with explicit confirmation"3992      description: "Default: the message goes to Trash (restorable with POST /messages/{id}/move {folder:\"inbox\"}). `?permanent=true` destroys it and requires the scope `mail.delete` AND the body `{\"confirm\":\"permanently-delete\"}`."3993      parameters:3994        -3995          name: "id"3996          in: "path"3997          required: true3998          schema:3999            type: "string"4000            maxLength: 4004001        -4002          name: "permanent"4003          in: "query"4004          required: false4005          schema:4006            type: "string"4007            enum:4008              - "true"4009              - "false"4010      requestBody:4011        required: true4012        content:4013          "application/json":4014            schema:4015              type: "object"4016              properties:4017                confirm:4018                  type: "string"4019                  maxLength: 404020      responses:4021        "200":4022          description: "Success"4023          content:4024            "application/json":4025              schema:4026                type: "object"4027                properties:4028                  ok:4029                    type: "boolean"4030                    const: true4031                  permanent:4032                    type: "boolean"4033                required:4034                  - "ok"4035                  - "permanent"4036                additionalProperties: false4037        default:4038          description: "Error"4039          content:4040            "application/json":4041              schema:4042                "$ref": "#/components/schemas/Error"4043      security:4044        -4045          apiKey: []4046        -4047          session: []4048      x-required-scopes:4049        - "mail.modify"4050        - "mail.delete"4051    get:4052      operationId: "getMessagesId"4053      tags:4054        - "Messages"4055      summary: "Read one message (headers, text, sanitised HTML, attachment metadata)"4056      parameters:4057        -4058          name: "id"4059          in: "path"4060          required: true4061          schema:4062            type: "string"4063            maxLength: 4004064      responses:4065        "200":4066          description: "Success"4067          content:4068            "application/json":4069              schema:4070                type: "object"4071                properties:4072                  id:4073                    type: "string"4074                  thread_id:4075                    type: "string"4076                  mailbox:4077                    type: "string"4078                    description: "Primary address of the physical mailbox holding the message"4079                  delivered_to:4080                    type: "array"4081                    items:4082                      type: "string"4083                    description: "Envelope recipients recorded by the mail server (Delivered-To)"4084                  folders:4085                    type: "array"4086                    items:4087                      type: "object"4088                      properties:4089                        id:4090                          type: "string"4091                        role:4092                          type:4093                            - "string"4094                            - "null"4095                        name:4096                          type: "string"4097                      required:4098                        - "id"4099                        - "role"4100                        - "name"4101                      additionalProperties: false4102                  from:4103                    type: "array"4104                    items:4105                      type: "object"4106                      properties:4107                        email:4108                          type: "string"4109                        name:4110                          type:4111                            - "string"4112                            - "null"4113                      required:4114                        - "email"4115                        - "name"4116                      additionalProperties: false4117                  to:4118                    type: "array"4119                    items:4120                      type: "object"4121                      properties:4122                        email:4123                          type: "string"4124                        name:4125                          type:4126                            - "string"4127                            - "null"4128                      required:4129                        - "email"4130                        - "name"4131                      additionalProperties: false4132                  cc:4133                    type: "array"4134                    items:4135                      type: "object"4136                      properties:4137                        email:4138                          type: "string"4139                        name:4140                          type:4141                            - "string"4142                            - "null"4143                      required:4144                        - "email"4145                        - "name"4146                      additionalProperties: false4147                  subject:4148                    type: "string"4149                  preview:4150                    type: "string"4151                  received_at:4152                    type: "string"4153                  sent_at:4154                    type:4155                      - "string"4156                      - "null"4157                  size:4158                    type: "number"4159                  unread:4160                    type: "boolean"4161                  starred:4162                    type: "boolean"4163                  draft:4164                    type: "boolean"4165                  answered:4166                    type: "boolean"4167                  forwarded:4168                    type: "boolean"4169                  has_attachment:4170                    type: "boolean"4171                  labels:4172                    type: "array"4173                    items:4174                      type: "string"4175                  pinned:4176                    type: "boolean"4177                    description: "Pinned to the top of its lists (`$pinned` keyword)"4178                  snoozed:4179                    type: "boolean"4180                    description: "Currently snoozed (`$snoozed` keyword); it returns to the inbox when the snooze ends"4181                  followup:4182                    type: "boolean"4183                    description: "A follow-up reminder is set on the message (`$followup` keyword)"4184                  bcc:4185                    type: "array"4186                    items:4187                      type: "object"4188                      properties:4189                        email:4190                          type: "string"4191                        name:4192                          type:4193                            - "string"4194                            - "null"4195                      required:4196                        - "email"4197                        - "name"4198                      additionalProperties: false4199                  reply_to:4200                    type: "array"4201                    items:4202                      type: "object"4203                      properties:4204                        email:4205                          type: "string"4206                        name:4207                          type:4208                            - "string"4209                            - "null"4210                      required:4211                        - "email"4212                        - "name"4213                      additionalProperties: false4214                  message_id:4215                    type:4216                      - "string"4217                      - "null"4218                  in_reply_to:4219                    type: "array"4220                    items:4221                      type: "string"4222                  references:4223                    type: "array"4224                    items:4225                      type: "string"4226                  headers:4227                    type: "array"4228                    items:4229                      type: "object"4230                      properties:4231                        name:4232                          type: "string"4233                        value:4234                          type: "string"4235                      required:4236                        - "name"4237                        - "value"4238                      additionalProperties: false4239                  text:4240                    type:4241                      - "string"4242                      - "null"4243                  html:4244                    description: "Sanitised server-side (strict allowlist); remote images are NOT fetched or rewritten"4245                    type:4246                      - "string"4247                      - "null"4248                  truncated:4249                    type: "boolean"4250                  attachments:4251                    type: "array"4252                    items:4253                      type: "object"4254                      properties:4255                        id:4256                          type: "string"4257                        name:4258                          type:4259                            - "string"4260                            - "null"4261                        type:4262                          type: "string"4263                        size:4264                          type: "number"4265                        cid:4266                          type:4267                            - "string"4268                            - "null"4269                        disposition:4270                          type:4271                            - "string"4272                            - "null"4273                        inline:4274                          type: "boolean"4275                      required:4276                        - "id"4277                        - "name"4278                        - "type"4279                        - "size"4280                        - "cid"4281                        - "disposition"4282                        - "inline"4283                      additionalProperties: false4284                  auth:4285                    type: "object"4286                    properties:4287                      spf:4288                        type:4289                          - "string"4290                          - "null"4291                      dkim:4292                        type:4293                          - "string"4294                          - "null"4295                      dmarc:4296                        type:4297                          - "string"4298                          - "null"4299                      raw:4300                        type:4301                          - "string"4302                          - "null"4303                    required:4304                      - "spf"4305                      - "dkim"4306                      - "dmarc"4307                      - "raw"4308                    additionalProperties: false4309                required:4310                  - "id"4311                  - "thread_id"4312                  - "mailbox"4313                  - "delivered_to"4314                  - "folders"4315                  - "from"4316                  - "to"4317                  - "cc"4318                  - "subject"4319                  - "preview"4320                  - "received_at"4321                  - "sent_at"4322                  - "size"4323                  - "unread"4324                  - "starred"4325                  - "draft"4326                  - "answered"4327                  - "forwarded"4328                  - "has_attachment"4329                  - "labels"4330                  - "pinned"4331                  - "snoozed"4332                  - "followup"4333                  - "bcc"4334                  - "reply_to"4335                  - "message_id"4336                  - "in_reply_to"4337                  - "references"4338                  - "headers"4339                  - "text"4340                  - "html"4341                  - "truncated"4342                  - "attachments"4343                  - "auth"4344                additionalProperties: false4345        default:4346          description: "Error"4347          content:4348            "application/json":4349              schema:4350                "$ref": "#/components/schemas/Error"4351      security:4352        -4353          apiKey: []4354        -4355          session: []4356      x-required-scopes:4357        - "mail.read"4358    patch:4359      operationId: "patchMessagesId"4360      tags:4361        - "Messages"4362      summary: "Mark read/unread, star, add or remove labels"4363      parameters:4364        -4365          name: "id"4366          in: "path"4367          required: true4368          schema:4369            type: "string"4370            maxLength: 4004371      requestBody:4372        required: true4373        content:4374          "application/json":4375            schema:4376              type: "object"4377              properties:4378                unread:4379                  type: "boolean"4380                starred:4381                  type: "boolean"4382                add_labels:4383                  maxItems: 204384                  type: "array"4385                  items:4386                    type: "string"4387                remove_labels:4388                  maxItems: 204389                  type: "array"4390                  items:4391                    type: "string"4392              additionalProperties: false4393      responses:4394        "200":4395          description: "Success"4396          content:4397            "application/json":4398              schema:4399                type: "object"4400                properties:4401                  id:4402                    type: "string"4403                  thread_id:4404                    type: "string"4405                  mailbox:4406                    type: "string"4407                    description: "Primary address of the physical mailbox holding the message"4408                  delivered_to:4409                    type: "array"4410                    items:4411                      type: "string"4412                    description: "Envelope recipients recorded by the mail server (Delivered-To)"4413                  folders:4414                    type: "array"4415                    items:4416                      type: "object"4417                      properties:4418                        id:4419                          type: "string"4420                        role:4421                          type:4422                            - "string"4423                            - "null"4424                        name:4425                          type: "string"4426                      required:4427                        - "id"4428                        - "role"4429                        - "name"4430                      additionalProperties: false4431                  from:4432                    type: "array"4433                    items:4434                      type: "object"4435                      properties:4436                        email:4437                          type: "string"4438                        name:4439                          type:4440                            - "string"4441                            - "null"4442                      required:4443                        - "email"4444                        - "name"4445                      additionalProperties: false4446                  to:4447                    type: "array"4448                    items:4449                      type: "object"4450                      properties:4451                        email:4452                          type: "string"4453                        name:4454                          type:4455                            - "string"4456                            - "null"4457                      required:4458                        - "email"4459                        - "name"4460                      additionalProperties: false4461                  cc:4462                    type: "array"4463                    items:4464                      type: "object"4465                      properties:4466                        email:4467                          type: "string"4468                        name:4469                          type:4470                            - "string"4471                            - "null"4472                      required:4473                        - "email"4474                        - "name"4475                      additionalProperties: false4476                  subject:4477                    type: "string"4478                  preview:4479                    type: "string"4480                  received_at:4481                    type: "string"4482                  sent_at:4483                    type:4484                      - "string"4485                      - "null"4486                  size:4487                    type: "number"4488                  unread:4489                    type: "boolean"4490                  starred:4491                    type: "boolean"4492                  draft:4493                    type: "boolean"4494                  answered:4495                    type: "boolean"4496                  forwarded:4497                    type: "boolean"4498                  has_attachment:4499                    type: "boolean"4500                  labels:4501                    type: "array"4502                    items:4503                      type: "string"4504                  pinned:4505                    type: "boolean"4506                    description: "Pinned to the top of its lists (`$pinned` keyword)"4507                  snoozed:4508                    type: "boolean"4509                    description: "Currently snoozed (`$snoozed` keyword); it returns to the inbox when the snooze ends"4510                  followup:4511                    type: "boolean"4512                    description: "A follow-up reminder is set on the message (`$followup` keyword)"4513                required:4514                  - "id"4515                  - "thread_id"4516                  - "mailbox"4517                  - "delivered_to"4518                  - "folders"4519                  - "from"4520                  - "to"4521                  - "cc"4522                  - "subject"4523                  - "preview"4524                  - "received_at"4525                  - "sent_at"4526                  - "size"4527                  - "unread"4528                  - "starred"4529                  - "draft"4530                  - "answered"4531                  - "forwarded"4532                  - "has_attachment"4533                  - "labels"4534                  - "pinned"4535                  - "snoozed"4536                  - "followup"4537                additionalProperties: false4538        default:4539          description: "Error"4540          content:4541            "application/json":4542              schema:4543                "$ref": "#/components/schemas/Error"4544      security:4545        -4546          apiKey: []4547        -4548          session: []4549      x-required-scopes:4550        - "mail.modify"4551  "/messages/{id}/attachments":4552    get:4553      operationId: "getMessagesIdAttachments"4554      tags:4555        - "Attachments"4556      summary: "Attachment metadata of a message"4557      parameters:4558        -4559          name: "id"4560          in: "path"4561          required: true4562          schema:4563            type: "string"4564            maxLength: 4004565      responses:4566        "200":4567          description: "Success"4568          content:4569            "application/json":4570              schema:4571                type: "object"4572                properties:4573                  data:4574                    type: "array"4575                    items:4576                      type: "object"4577                      properties:4578                        id:4579                          type: "string"4580                        name:4581                          type:4582                            - "string"4583                            - "null"4584                        type:4585                          type: "string"4586                        size:4587                          type: "number"4588                        cid:4589                          type:4590                            - "string"4591                            - "null"4592                        disposition:4593                          type:4594                            - "string"4595                            - "null"4596                        inline:4597                          type: "boolean"4598                      required:4599                        - "id"4600                        - "name"4601                        - "type"4602                        - "size"4603                        - "cid"4604                        - "disposition"4605                        - "inline"4606                      additionalProperties: false4607                required:4608                  - "data"4609                additionalProperties: false4610        default:4611          description: "Error"4612          content:4613            "application/json":4614              schema:4615                "$ref": "#/components/schemas/Error"4616      security:4617        -4618          apiKey: []4619        -4620          session: []4621      x-required-scopes:4622        - "mail.attachments.read"4623  "/messages/{id}/attachments/{attachment_id}":4624    get:4625      operationId: "getMessagesIdAttachmentsAttachment_id"4626      tags:4627        - "Attachments"4628      summary: "Download one attachment"4629      description: "Always served as `Content-Disposition: attachment` with `Content-Security-Policy: sandbox`. The attachment id is verified against the message."4630      parameters:4631        -4632          name: "id"4633          in: "path"4634          required: true4635          schema:4636            type: "string"4637            maxLength: 4004638        -4639          name: "attachment_id"4640          in: "path"4641          required: true4642          schema:4643            type: "string"4644            maxLength: 7004645      responses:4646        "200":4647          description: "Binary content"4648          content:4649            "application/octet-stream":4650              schema:4651                type: "string"4652                format: "binary"4653        default:4654          description: "Error"4655          content:4656            "application/json":4657              schema:4658                "$ref": "#/components/schemas/Error"4659      security:4660        -4661          apiKey: []4662        -4663          session: []4664      x-required-scopes:4665        - "mail.attachments.read"4666  "/messages/{id}/forward":4667    post:4668      operationId: "postMessagesIdForward"4669      tags:4670        - "Sending"4671      summary: "Forward a message, keeping its attachments"4672      description: "Requires `mail.send` AND `mail.read` (forwarding re-reads the content). The original's attachments are re-attached; its text is quoted below yours. The sender must belong to the same mailbox as the original."4673      parameters:4674        -4675          name: "id"4676          in: "path"4677          required: true4678          schema:4679            type: "string"4680            maxLength: 4004681        -4682          name: "Idempotency-Key"4683          in: "header"4684          required: false4685          description: "Replays the stored response for 24 h; a different payload with the same key answers 409."4686          schema:4687            type: "string"4688            maxLength: 2004689      requestBody:4690        required: true4691        content:4692          "application/json":4693            schema:4694              type: "object"4695              properties:4696                from:4697                  type: "string"4698                  maxLength: 2544699                to:4700                  minItems: 14701                  maxItems: 1004702                  type: "array"4703                  items:4704                    anyOf:4705                      -4706                        type: "string"4707                        maxLength: 2544708                      -4709                        type: "object"4710                        properties:4711                          email:4712                            type: "string"4713                            maxLength: 2544714                          name:4715                            type: "string"4716                            maxLength: 1204717                        required:4718                          - "email"4719                cc:4720                  maxItems: 1004721                  type: "array"4722                  items:4723                    anyOf:4724                      -4725                        type: "string"4726                        maxLength: 2544727                      -4728                        type: "object"4729                        properties:4730                          email:4731                            type: "string"4732                            maxLength: 2544733                          name:4734                            type: "string"4735                            maxLength: 1204736                        required:4737                          - "email"4738                bcc:4739                  maxItems: 1004740                  type: "array"4741                  items:4742                    anyOf:4743                      -4744                        type: "string"4745                        maxLength: 2544746                      -4747                        type: "object"4748                        properties:4749                          email:4750                            type: "string"4751                            maxLength: 2544752                          name:4753                            type: "string"4754                            maxLength: 1204755                        required:4756                          - "email"4757                text:4758                  default: ""4759                  type: "string"4760                  maxLength: 20000004761                include_attachments:4762                  default: true4763                  type: "boolean"4764                send_at:4765                  type: "string"4766                draft:4767                  type: "boolean"4768                undo_seconds:4769                  description: "Undo send: hold the message this many seconds before it is submitted (status `scheduled`, response carries `undo_until`); cancel with DELETE /messages/scheduled/{id}. Ignored with a future `send_at`, `draft`, or when the message awaits approval"4770                  type: "integer"4771                  minimum: 04772                  maximum: 1204773                remind_at:4774                  description: "ISO 8601; creates a follow-up reminder on the sent message once it has been submitted (session callers only)"4775                  type: "string"4776                remind_if_no_reply:4777                  description: "With `remind_at`: the reminder resolves silently if somebody replied in the meantime"4778                  type: "boolean"4779                confirm_sensitive:4780                  description: "Session callers: confirms sending to recipients listed as sensitive in the compose preferences (otherwise `409 confirmation_required`)"4781                  type: "boolean"4782              required:4783                - "to"4784              additionalProperties: false4785      responses:4786        "200":4787          description: "Success"4788          content:4789            "application/json":4790              schema:4791                type: "object"4792                properties:4793                  id:4794                    type: "string"4795                    description: "msg_out_… (or the draft's msg_… id when status is draft)"4796                  status:4797                    type: "string"4798                    enum:4799                      - "queued"4800                      - "scheduled"4801                      - "pending_approval"4802                      - "sent"4803                      - "delivered"4804                      - "deferred"4805                      - "bounced"4806                      - "failed"4807                      - "cancelled"4808                      - "draft"4809                  from:4810                    type: "string"4811                  message_id:4812                    type:4813                      - "string"4814                      - "null"4815                  recipients:4816                    type: "array"4817                    items:4818                      type: "object"4819                      properties:4820                        address:4821                          type: "string"4822                        status:4823                          type: "string"4824                        smtp_reply:4825                          type:4826                            - "string"4827                            - "null"4828                      required:4829                        - "address"4830                        - "status"4831                        - "smtp_reply"4832                      additionalProperties: false4833                  external:4834                    type: "boolean"4835                  send_at:4836                    type:4837                      - "string"4838                      - "null"4839                  attempts:4840                    type: "number"4841                  last_error:4842                    type:4843                      - "string"4844                      - "null"4845                  submitted_at:4846                    type:4847                      - "string"4848                      - "null"4849                  final_at:4850                    type:4851                      - "string"4852                      - "null"4853                  created_at:4854                    type: "string"4855                  updated_at:4856                    type: "string"4857                  approval_id:4858                    type: "string"4859                  thread_id:4860                    type:4861                      - "string"4862                      - "null"4863                  undo_until:4864                    description: "Undo send: the message is held until this instant and can still be cancelled"4865                    type:4866                      - "string"4867                      - "null"4868                required:4869                  - "id"4870                  - "status"4871                  - "from"4872                  - "message_id"4873                  - "recipients"4874                  - "external"4875                  - "send_at"4876                  - "attempts"4877                  - "last_error"4878                  - "submitted_at"4879                  - "final_at"4880                  - "created_at"4881                  - "updated_at"4882                additionalProperties: false4883        "201":4884          description: "Draft saved"4885        "202":4886          description: "Accepted"4887        default:4888          description: "Error"4889          content:4890            "application/json":4891              schema:4892                "$ref": "#/components/schemas/Error"4893      security:4894        -4895          apiKey: []4896        -4897          session: []4898      x-required-scopes:4899        - "mail.send"4900  "/messages/{id}/move":4901    post:4902      operationId: "postMessagesIdMove"4903      tags:4904        - "Messages"4905      summary: "Move to a folder (archive, trash, inbox = restore, or a folder id)"4906      description: "`folder` is a role (inbox, archive, trash, junk, sent, drafts) or a folder id of the same mailbox. The Archive folder is created (role archive) when missing."4907      parameters:4908        -4909          name: "id"4910          in: "path"4911          required: true4912          schema:4913            type: "string"4914            maxLength: 4004915      requestBody:4916        required: true4917        content:4918          "application/json":4919            schema:4920              type: "object"4921              properties:4922                folder:4923                  type: "string"4924                  maxLength: 3004925              required:4926                - "folder"4927              additionalProperties: false4928      responses:4929        "200":4930          description: "Success"4931          content:4932            "application/json":4933              schema:4934                type: "object"4935                properties:4936                  id:4937                    type: "string"4938                  thread_id:4939                    type: "string"4940                  mailbox:4941                    type: "string"4942                    description: "Primary address of the physical mailbox holding the message"4943                  delivered_to:4944                    type: "array"4945                    items:4946                      type: "string"4947                    description: "Envelope recipients recorded by the mail server (Delivered-To)"4948                  folders:4949                    type: "array"4950                    items:4951                      type: "object"4952                      properties:4953                        id:4954                          type: "string"4955                        role:4956                          type:4957                            - "string"4958                            - "null"4959                        name:4960                          type: "string"4961                      required:4962                        - "id"4963                        - "role"4964                        - "name"4965                      additionalProperties: false4966                  from:4967                    type: "array"4968                    items:4969                      type: "object"4970                      properties:4971                        email:4972                          type: "string"4973                        name:4974                          type:4975                            - "string"4976                            - "null"4977                      required:4978                        - "email"4979                        - "name"4980                      additionalProperties: false4981                  to:4982                    type: "array"4983                    items:4984                      type: "object"4985                      properties:4986                        email:4987                          type: "string"4988                        name:4989                          type:4990                            - "string"4991                            - "null"4992                      required:4993                        - "email"4994                        - "name"4995                      additionalProperties: false4996                  cc:4997                    type: "array"4998                    items:4999                      type: "object"5000                      properties:5001                        email:5002                          type: "string"5003                        name:5004                          type:5005                            - "string"5006                            - "null"5007                      required:5008                        - "email"5009                        - "name"5010                      additionalProperties: false5011                  subject:5012                    type: "string"5013                  preview:5014                    type: "string"5015                  received_at:5016                    type: "string"5017                  sent_at:5018                    type:5019                      - "string"5020                      - "null"5021                  size:5022                    type: "number"5023                  unread:5024                    type: "boolean"5025                  starred:5026                    type: "boolean"5027                  draft:5028                    type: "boolean"5029                  answered:5030                    type: "boolean"5031                  forwarded:5032                    type: "boolean"5033                  has_attachment:5034                    type: "boolean"5035                  labels:5036                    type: "array"5037                    items:5038                      type: "string"5039                  pinned:5040                    type: "boolean"5041                    description: "Pinned to the top of its lists (`$pinned` keyword)"5042                  snoozed:5043                    type: "boolean"5044                    description: "Currently snoozed (`$snoozed` keyword); it returns to the inbox when the snooze ends"5045                  followup:5046                    type: "boolean"5047                    description: "A follow-up reminder is set on the message (`$followup` keyword)"5048                required:5049                  - "id"5050                  - "thread_id"5051                  - "mailbox"5052                  - "delivered_to"5053                  - "folders"5054                  - "from"5055                  - "to"5056                  - "cc"5057                  - "subject"5058                  - "preview"5059                  - "received_at"5060                  - "sent_at"5061                  - "size"5062                  - "unread"5063                  - "starred"5064                  - "draft"5065                  - "answered"5066                  - "forwarded"5067                  - "has_attachment"5068                  - "labels"5069                  - "pinned"5070                  - "snoozed"5071                  - "followup"5072                additionalProperties: false5073        default:5074          description: "Error"5075          content:5076            "application/json":5077              schema:5078                "$ref": "#/components/schemas/Error"5079      security:5080        -5081          apiKey: []5082        -5083          session: []5084      x-required-scopes:5085        - "mail.modify"5086  "/messages/{id}/reply":5087    post:5088      operationId: "postMessagesIdReply"5089      tags:5090        - "Sending"5091      summary: "Reply (or reply-all) to a message, keeping the thread"5092      description: "Recipients, subject (`Re:`), In-Reply-To and References come from the original. Same outcomes and status codes as POST /messages/send."5093      parameters:5094        -5095          name: "id"5096          in: "path"5097          required: true5098          schema:5099            type: "string"5100            maxLength: 4005101        -5102          name: "Idempotency-Key"5103          in: "header"5104          required: false5105          description: "Replays the stored response for 24 h; a different payload with the same key answers 409."5106          schema:5107            type: "string"5108            maxLength: 2005109      requestBody:5110        required: true5111        content:5112          "application/json":5113            schema:5114              type: "object"5115              properties:5116                from:5117                  description: "Defaults to the allowed address the message was delivered to, else the mailbox's primary address"5118                  type: "string"5119                  maxLength: 2545120                reply_all:5121                  default: false5122                  type: "boolean"5123                text:5124                  type: "string"5125                  maxLength: 20000005126                html:5127                  type: "string"5128                  maxLength: 20000005129                cc:5130                  maxItems: 1005131                  type: "array"5132                  items:5133                    anyOf:5134                      -5135                        type: "string"5136                        maxLength: 2545137                      -5138                        type: "object"5139                        properties:5140                          email:5141                            type: "string"5142                            maxLength: 2545143                          name:5144                            type: "string"5145                            maxLength: 1205146                        required:5147                          - "email"5148                bcc:5149                  maxItems: 1005150                  type: "array"5151                  items:5152                    anyOf:5153                      -5154                        type: "string"5155                        maxLength: 2545156                      -5157                        type: "object"5158                        properties:5159                          email:5160                            type: "string"5161                            maxLength: 2545162                          name:5163                            type: "string"5164                            maxLength: 1205165                        required:5166                          - "email"5167                attachments:5168                  default: []5169                  maxItems: 305170                  type: "array"5171                  items:5172                    type: "object"5173                    properties:5174                      file_id:5175                        type: "string"5176                        pattern: "^file_[A-Za-z0-9_-]{10,60}$"5177                      filename:5178                        type: "string"5179                        maxLength: 2005180                      inline:5181                        description: "Inline image referenced from the HTML as cid:<cid>"5182                        type: "boolean"5183                      cid:5184                        type: "string"5185                        pattern: "^[A-Za-z0-9._@-]{1,100}$"5186                    required:5187                      - "file_id"5188                    additionalProperties: false5189                headers:5190                  type: "object"5191                  propertyNames:5192                    type: "string"5193                    maxLength: 645194                  additionalProperties:5195                    type: "string"5196                    maxLength: 9005197                send_at:5198                  type: "string"5199                draft:5200                  type: "boolean"5201                undo_seconds:5202                  description: "Undo send: hold the message this many seconds before it is submitted (status `scheduled`, response carries `undo_until`); cancel with DELETE /messages/scheduled/{id}. Ignored with a future `send_at`, `draft`, or when the message awaits approval"5203                  type: "integer"5204                  minimum: 05205                  maximum: 1205206                remind_at:5207                  description: "ISO 8601; creates a follow-up reminder on the sent message once it has been submitted (session callers only)"5208                  type: "string"5209                remind_if_no_reply:5210                  description: "With `remind_at`: the reminder resolves silently if somebody replied in the meantime"5211                  type: "boolean"5212                confirm_sensitive:5213                  description: "Session callers: confirms sending to recipients listed as sensitive in the compose preferences (otherwise `409 confirmation_required`)"5214                  type: "boolean"5215              additionalProperties: false5216      responses:5217        "200":5218          description: "Success"5219          content:5220            "application/json":5221              schema:5222                type: "object"5223                properties:5224                  id:5225                    type: "string"5226                    description: "msg_out_… (or the draft's msg_… id when status is draft)"5227                  status:5228                    type: "string"5229                    enum:5230                      - "queued"5231                      - "scheduled"5232                      - "pending_approval"5233                      - "sent"5234                      - "delivered"5235                      - "deferred"5236                      - "bounced"5237                      - "failed"5238                      - "cancelled"5239                      - "draft"5240                  from:5241                    type: "string"5242                  message_id:5243                    type:5244                      - "string"5245                      - "null"5246                  recipients:5247                    type: "array"5248                    items:5249                      type: "object"5250                      properties:5251                        address:5252                          type: "string"5253                        status:5254                          type: "string"5255                        smtp_reply:5256                          type:5257                            - "string"5258                            - "null"5259                      required:5260                        - "address"5261                        - "status"5262                        - "smtp_reply"5263                      additionalProperties: false5264                  external:5265                    type: "boolean"5266                  send_at:5267                    type:5268                      - "string"5269                      - "null"5270                  attempts:5271                    type: "number"5272                  last_error:5273                    type:5274                      - "string"5275                      - "null"5276                  submitted_at:5277                    type:5278                      - "string"5279                      - "null"5280                  final_at:5281                    type:5282                      - "string"5283                      - "null"5284                  created_at:5285                    type: "string"5286                  updated_at:5287                    type: "string"5288                  approval_id:5289                    type: "string"5290                  thread_id:5291                    type:5292                      - "string"5293                      - "null"5294                  undo_until:5295                    description: "Undo send: the message is held until this instant and can still be cancelled"5296                    type:5297                      - "string"5298                      - "null"5299                required:5300                  - "id"5301                  - "status"5302                  - "from"5303                  - "message_id"5304                  - "recipients"5305                  - "external"5306                  - "send_at"5307                  - "attempts"5308                  - "last_error"5309                  - "submitted_at"5310                  - "final_at"5311                  - "created_at"5312                  - "updated_at"5313                additionalProperties: false5314        "201":5315          description: "Draft saved"5316        "202":5317          description: "Accepted"5318        default:5319          description: "Error"5320          content:5321            "application/json":5322              schema:5323                "$ref": "#/components/schemas/Error"5324      security:5325        -5326          apiKey: []5327        -5328          session: []5329      x-required-scopes:5330        - "mail.send"5331  "/messages/changes":5332    get:5333      operationId: "getMessagesChanges"5334      tags:5335        - "Messages"5336      summary: "Incremental sync of one mailbox (JMAP Email/changes)"5337      description: "Without `since`: returns the current `state` and empty lists (bootstrap after a full listing). With `since`: ids created / updated / destroyed since that state. An unknown or too old state answers 409 `resync_required`. In an address-restricted view, created/updated are filtered to visible messages; destroyed ids are returned unfiltered (ids only)."5338      parameters:5339        -5340          name: "address"5341          in: "query"5342          required: false5343          description: "Address whose mailbox is synchronised (required when the caller can read several mailboxes)"5344          schema:5345            type: "string"5346            maxLength: 2545347        -5348          name: "since"5349          in: "query"5350          required: false5351          schema:5352            type: "string"5353            maxLength: 6005354        -5355          name: "limit"5356          in: "query"5357          required: false5358          schema:5359            default: 2005360            type: "integer"5361            minimum: 15362            maximum: 5005363      responses:5364        "200":5365          description: "Success"5366          content:5367            "application/json":5368              schema:5369                type: "object"5370                properties:5371                  mailbox:5372                    type: "string"5373                  state:5374                    type: "string"5375                  created:5376                    type: "array"5377                    items:5378                      type: "string"5379                  updated:5380                    type: "array"5381                    items:5382                      type: "string"5383                  destroyed:5384                    type: "array"5385                    items:5386                      type: "string"5387                  has_more:5388                    type: "boolean"5389                required:5390                  - "mailbox"5391                  - "state"5392                  - "created"5393                  - "updated"5394                  - "destroyed"5395                  - "has_more"5396                additionalProperties: false5397        "409":5398          description: "resync_required"5399        default:5400          description: "Error"5401          content:5402            "application/json":5403              schema:5404                "$ref": "#/components/schemas/Error"5405      security:5406        -5407          apiKey: []5408        -5409          session: []5410      x-required-scopes:5411        - "mail.read"5412  "/messages/outbound":5413    get:5414      operationId: "getMessagesOutbound"5415      tags:5416        - "Sending"5417      summary: "Messages sent through the API by this caller, with delivery status"5418      parameters:5419        -5420          name: "status"5421          in: "query"5422          required: false5423          schema:5424            type: "string"5425            enum:5426              - "queued"5427              - "scheduled"5428              - "pending_approval"5429              - "sent"5430              - "delivered"5431              - "deferred"5432              - "bounced"5433              - "failed"5434              - "cancelled"5435        -5436          name: "limit"5437          in: "query"5438          required: false5439          schema:5440            default: 255441            type: "integer"5442            minimum: 15443            maximum: 1005444        -5445          name: "cursor"5446          in: "query"5447          required: false5448          schema:5449            type: "string"5450            maxLength: 20005451      responses:5452        "200":5453          description: "Success"5454          content:5455            "application/json":5456              schema:5457                type: "object"5458                properties:5459                  data:5460                    type: "array"5461                    items:5462                      type: "object"5463                      properties:5464                        id:5465                          type: "string"5466                          description: "msg_out_… (or the draft's msg_… id when status is draft)"5467                        status:5468                          type: "string"5469                          enum:5470                            - "queued"5471                            - "scheduled"5472                            - "pending_approval"5473                            - "sent"5474                            - "delivered"5475                            - "deferred"5476                            - "bounced"5477                            - "failed"5478                            - "cancelled"5479                            - "draft"5480                        from:5481                          type: "string"5482                        message_id:5483                          type:5484                            - "string"5485                            - "null"5486                        recipients:5487                          type: "array"5488                          items:5489                            type: "object"5490                            properties:5491                              address:5492                                type: "string"5493                              status:5494                                type: "string"5495                              smtp_reply:5496                                type:5497                                  - "string"5498                                  - "null"5499                            required:5500                              - "address"5501                              - "status"5502                              - "smtp_reply"5503                            additionalProperties: false5504                        external:5505                          type: "boolean"5506                        send_at:5507                          type:5508                            - "string"5509                            - "null"5510                        attempts:5511                          type: "number"5512                        last_error:5513                          type:5514                            - "string"5515                            - "null"5516                        submitted_at:5517                          type:5518                            - "string"5519                            - "null"5520                        final_at:5521                          type:5522                            - "string"5523                            - "null"5524                        created_at:5525                          type: "string"5526                        updated_at:5527                          type: "string"5528                        approval_id:5529                          type: "string"5530                        thread_id:5531                          type:5532                            - "string"5533                            - "null"5534                        undo_until:5535                          description: "Undo send: the message is held until this instant and can still be cancelled"5536                          type:5537                            - "string"5538                            - "null"5539                      required:5540                        - "id"5541                        - "status"5542                        - "from"5543                        - "message_id"5544                        - "recipients"5545                        - "external"5546                        - "send_at"5547                        - "attempts"5548                        - "last_error"5549                        - "submitted_at"5550                        - "final_at"5551                        - "created_at"5552                        - "updated_at"5553                      additionalProperties: false5554                  next_cursor:5555                    type:5556                      - "string"5557                      - "null"5558                  has_more:5559                    type: "boolean"5560                required:5561                  - "data"5562                  - "next_cursor"5563                  - "has_more"5564                additionalProperties: false5565        default:5566          description: "Error"5567          content:5568            "application/json":5569              schema:5570                "$ref": "#/components/schemas/Error"5571      security:5572        -5573          apiKey: []5574        -5575          session: []5576      x-required-scopes:5577        - "mail.send"5578        - "mail.read"5579  "/messages/outbound/{id}":5580    get:5581      operationId: "getMessagesOutboundId"5582      tags:5583        - "Sending"5584      summary: "Delivery status of one sent message (per recipient, with SMTP replies)"5585      parameters:5586        -5587          name: "id"5588          in: "path"5589          required: true5590          schema:5591            type: "string"5592            maxLength: 605593      responses:5594        "200":5595          description: "Success"5596          content:5597            "application/json":5598              schema:5599                type: "object"5600                properties:5601                  id:5602                    type: "string"5603                    description: "msg_out_… (or the draft's msg_… id when status is draft)"5604                  status:5605                    type: "string"5606                    enum:5607                      - "queued"5608                      - "scheduled"5609                      - "pending_approval"5610                      - "sent"5611                      - "delivered"5612                      - "deferred"5613                      - "bounced"5614                      - "failed"5615                      - "cancelled"5616                      - "draft"5617                  from:5618                    type: "string"5619                  message_id:5620                    type:5621                      - "string"5622                      - "null"5623                  recipients:5624                    type: "array"5625                    items:5626                      type: "object"5627                      properties:5628                        address:5629                          type: "string"5630                        status:5631                          type: "string"5632                        smtp_reply:5633                          type:5634                            - "string"5635                            - "null"5636                      required:5637                        - "address"5638                        - "status"5639                        - "smtp_reply"5640                      additionalProperties: false5641                  external:5642                    type: "boolean"5643                  send_at:5644                    type:5645                      - "string"5646                      - "null"5647                  attempts:5648                    type: "number"5649                  last_error:5650                    type:5651                      - "string"5652                      - "null"5653                  submitted_at:5654                    type:5655                      - "string"5656                      - "null"5657                  final_at:5658                    type:5659                      - "string"5660                      - "null"5661                  created_at:5662                    type: "string"5663                  updated_at:5664                    type: "string"5665                  approval_id:5666                    type: "string"5667                  thread_id:5668                    type:5669                      - "string"5670                      - "null"5671                  undo_until:5672                    description: "Undo send: the message is held until this instant and can still be cancelled"5673                    type:5674                      - "string"5675                      - "null"5676                required:5677                  - "id"5678                  - "status"5679                  - "from"5680                  - "message_id"5681                  - "recipients"5682                  - "external"5683                  - "send_at"5684                  - "attempts"5685                  - "last_error"5686                  - "submitted_at"5687                  - "final_at"5688                  - "created_at"5689                  - "updated_at"5690                additionalProperties: false5691        default:5692          description: "Error"5693          content:5694            "application/json":5695              schema:5696                "$ref": "#/components/schemas/Error"5697      security:5698        -5699          apiKey: []5700        -5701          session: []5702      x-required-scopes:5703        - "mail.send"5704        - "mail.read"5705  "/messages/scheduled":5706    get:5707      operationId: "getMessagesScheduled"5708      tags:5709        - "Sending"5710      summary: "Scheduled messages not yet sent"5711      parameters:5712        -5713          name: "limit"5714          in: "query"5715          required: false5716          schema:5717            default: 255718            type: "integer"5719            minimum: 15720            maximum: 1005721        -5722          name: "cursor"5723          in: "query"5724          required: false5725          schema:5726            type: "string"5727            maxLength: 20005728      responses:5729        "200":5730          description: "Success"5731          content:5732            "application/json":5733              schema:5734                type: "object"5735                properties:5736                  data:5737                    type: "array"5738                    items:5739                      type: "object"5740                      properties:5741                        id:5742                          type: "string"5743                          description: "msg_out_… (or the draft's msg_… id when status is draft)"5744                        status:5745                          type: "string"5746                          enum:5747                            - "queued"5748                            - "scheduled"5749                            - "pending_approval"5750                            - "sent"5751                            - "delivered"5752                            - "deferred"5753                            - "bounced"5754                            - "failed"5755                            - "cancelled"5756                            - "draft"5757                        from:5758                          type: "string"5759                        message_id:5760                          type:5761                            - "string"5762                            - "null"5763                        recipients:5764                          type: "array"5765                          items:5766                            type: "object"5767                            properties:5768                              address:5769                                type: "string"5770                              status:5771                                type: "string"5772                              smtp_reply:5773                                type:5774                                  - "string"5775                                  - "null"5776                            required:5777                              - "address"5778                              - "status"5779                              - "smtp_reply"5780                            additionalProperties: false5781                        external:5782                          type: "boolean"5783                        send_at:5784                          type:5785                            - "string"5786                            - "null"5787                        attempts:5788                          type: "number"5789                        last_error:5790                          type:5791                            - "string"5792                            - "null"5793                        submitted_at:5794                          type:5795                            - "string"5796                            - "null"5797                        final_at:5798                          type:5799                            - "string"5800                            - "null"5801                        created_at:5802                          type: "string"5803                        updated_at:5804                          type: "string"5805                        approval_id:5806                          type: "string"5807                        thread_id:5808                          type:5809                            - "string"5810                            - "null"5811                        undo_until:5812                          description: "Undo send: the message is held until this instant and can still be cancelled"5813                          type:5814                            - "string"5815                            - "null"5816                      required:5817                        - "id"5818                        - "status"5819                        - "from"5820                        - "message_id"5821                        - "recipients"5822                        - "external"5823                        - "send_at"5824                        - "attempts"5825                        - "last_error"5826                        - "submitted_at"5827                        - "final_at"5828                        - "created_at"5829                        - "updated_at"5830                      additionalProperties: false5831                  next_cursor:5832                    type:5833                      - "string"5834                      - "null"5835                  has_more:5836                    type: "boolean"5837                required:5838                  - "data"5839                  - "next_cursor"5840                  - "has_more"5841                additionalProperties: false5842        default:5843          description: "Error"5844          content:5845            "application/json":5846              schema:5847                "$ref": "#/components/schemas/Error"5848      security:5849        -5850          apiKey: []5851        -5852          session: []5853      x-required-scopes:5854        - "mail.send"5855  "/messages/scheduled/{id}":5856    delete:5857      operationId: "deleteMessagesScheduledId"5858      tags:5859        - "Sending"5860      summary: "Cancel a scheduled message (nothing is sent, the stored draft is destroyed)"5861      parameters:5862        -5863          name: "id"5864          in: "path"5865          required: true5866          schema:5867            type: "string"5868            maxLength: 605869      responses:5870        "200":5871          description: "Success"5872          content:5873            "application/json":5874              schema:5875                type: "object"5876                properties:5877                  id:5878                    type: "string"5879                    description: "msg_out_… (or the draft's msg_… id when status is draft)"5880                  status:5881                    type: "string"5882                    enum:5883                      - "queued"5884                      - "scheduled"5885                      - "pending_approval"5886                      - "sent"5887                      - "delivered"5888                      - "deferred"5889                      - "bounced"5890                      - "failed"5891                      - "cancelled"5892                      - "draft"5893                  from:5894                    type: "string"5895                  message_id:5896                    type:5897                      - "string"5898                      - "null"5899                  recipients:5900                    type: "array"5901                    items:5902                      type: "object"5903                      properties:5904                        address:5905                          type: "string"5906                        status:5907                          type: "string"5908                        smtp_reply:5909                          type:5910                            - "string"5911                            - "null"5912                      required:5913                        - "address"5914                        - "status"5915                        - "smtp_reply"5916                      additionalProperties: false5917                  external:5918                    type: "boolean"5919                  send_at:5920                    type:5921                      - "string"5922                      - "null"5923                  attempts:5924                    type: "number"5925                  last_error:5926                    type:5927                      - "string"5928                      - "null"5929                  submitted_at:5930                    type:5931                      - "string"5932                      - "null"5933                  final_at:5934                    type:5935                      - "string"5936                      - "null"5937                  created_at:5938                    type: "string"5939                  updated_at:5940                    type: "string"5941                  approval_id:5942                    type: "string"5943                  thread_id:5944                    type:5945                      - "string"5946                      - "null"5947                  undo_until:5948                    description: "Undo send: the message is held until this instant and can still be cancelled"5949                    type:5950                      - "string"5951                      - "null"5952                required:5953                  - "id"5954                  - "status"5955                  - "from"5956                  - "message_id"5957                  - "recipients"5958                  - "external"5959                  - "send_at"5960                  - "attempts"5961                  - "last_error"5962                  - "submitted_at"5963                  - "final_at"5964                  - "created_at"5965                  - "updated_at"5966                additionalProperties: false5967        "409":5968          description: "not_cancellable"5969        default:5970          description: "Error"5971          content:5972            "application/json":5973              schema:5974                "$ref": "#/components/schemas/Error"5975      security:5976        -5977          apiKey: []5978        -5979          session: []5980      x-required-scopes:5981        - "mail.send"5982  "/messages/send":5983    post:5984      operationId: "postMessagesSend"5985      tags:5986        - "Sending"5987      summary: "Send a message (or schedule it, or save it as a draft)"5988      description: "200 = handed to the mail server (`sent`) or refused by it (`failed`). 202 = accepted but not yet handed over: `scheduled`, `pending_approval` (external recipients with key policy `approval`) or `queued` (mail server unreachable, will retry). 201 = `draft: true`."5989      parameters:5990        -5991          name: "Idempotency-Key"5992          in: "header"5993          required: false5994          description: "Replays the stored response for 24 h; a different payload with the same key answers 409."5995          schema:5996            type: "string"5997            maxLength: 2005998      requestBody:5999        required: true6000        content:6001          "application/json":6002            schema:6003              type: "object"6004              properties:6005                from:6006                  description: "Sender address; must be in the caller's allowlist, active and allowed to send"6007                  type: "string"6008                  maxLength: 2546009                to:6010                  maxItems: 1006011                  type: "array"6012                  items:6013                    anyOf:6014                      -6015                        type: "string"6016                        maxLength: 2546017                      -6018                        type: "object"6019                        properties:6020                          email:6021                            type: "string"6022                            maxLength: 2546023                          name:6024                            type: "string"6025                            maxLength: 1206026                        required:6027                          - "email"6028                cc:6029                  maxItems: 1006030                  type: "array"6031                  items:6032                    anyOf:6033                      -6034                        type: "string"6035                        maxLength: 2546036                      -6037                        type: "object"6038                        properties:6039                          email:6040                            type: "string"6041                            maxLength: 2546042                          name:6043                            type: "string"6044                            maxLength: 1206045                        required:6046                          - "email"6047                bcc:6048                  maxItems: 1006049                  type: "array"6050                  items:6051                    anyOf:6052                      -6053                        type: "string"6054                        maxLength: 2546055                      -6056                        type: "object"6057                        properties:6058                          email:6059                            type: "string"6060                            maxLength: 2546061                          name:6062                            type: "string"6063                            maxLength: 1206064                        required:6065                          - "email"6066                subject:6067                  default: ""6068                  type: "string"6069                  maxLength: 9986070                text:6071                  type: "string"6072                  maxLength: 20000006073                html:6074                  description: "Sanitised server-side with a strict allowlist before being stored or sent"6075                  type: "string"6076                  maxLength: 20000006077                attachments:6078                  default: []6079                  maxItems: 306080                  type: "array"6081                  items:6082                    type: "object"6083                    properties:6084                      file_id:6085                        type: "string"6086                        pattern: "^file_[A-Za-z0-9_-]{10,60}$"6087                      filename:6088                        type: "string"6089                        maxLength: 2006090                      inline:6091                        description: "Inline image referenced from the HTML as cid:<cid>"6092                        type: "boolean"6093                      cid:6094                        type: "string"6095                        pattern: "^[A-Za-z0-9._@-]{1,100}$"6096                    required:6097                      - "file_id"6098                    additionalProperties: false6099                reply_to_message_id:6100                  description: "Message (msg_…) being answered: sets In-Reply-To / References from it"6101                  type: "string"6102                  maxLength: 4006103                in_reply_to:6104                  type: "string"6105                  maxLength: 5006106                references:6107                  maxItems: 506108                  type: "array"6109                  items:6110                    type: "string"6111                    maxLength: 5006112                headers:6113                  description: "Only X-*, Reply-To, List-Unsubscribe, List-Unsubscribe-Post"6114                  type: "object"6115                  propertyNames:6116                    type: "string"6117                    maxLength: 646118                  additionalProperties:6119                    type: "string"6120                    maxLength: 9006121                priority:6122                  type: "string"6123                  enum:6124                    - "high"6125                    - "normal"6126                    - "low"6127                send_at:6128                  description: "ISO 8601; future = scheduled (max 30 days ahead)"6129                  type: "string"6130                draft:6131                  description: "Save as a draft only; nothing is sent"6132                  type: "boolean"6133                template_id:6134                  description: "Send a stored template (see /templates): its rendered subject, HTML and text are used; `html` and `text` must then be omitted, `subject` is optional and overrides the template's"6135                  type: "string"6136                  format: "uuid"6137                  pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"6138                variables:6139                  description: "Values for the template's {{variables}}; every required variable must be present"6140                  type: "object"6141                  propertyNames:6142                    type: "string"6143                    pattern: "^[a-z][a-z0-9_]{0,39}$"6144                  additionalProperties:6145                    type: "string"6146                    maxLength: 200006147                undo_seconds:6148                  description: "Undo send: hold the message this many seconds before it is submitted (status `scheduled`, response carries `undo_until`); cancel with DELETE /messages/scheduled/{id}. Ignored with a future `send_at`, `draft`, or when the message awaits approval"6149                  type: "integer"6150                  minimum: 06151                  maximum: 1206152                remind_at:6153                  description: "ISO 8601; creates a follow-up reminder on the sent message once it has been submitted (session callers only)"6154                  type: "string"6155                remind_if_no_reply:6156                  description: "With `remind_at`: the reminder resolves silently if somebody replied in the meantime"6157                  type: "boolean"6158                confirm_sensitive:6159                  description: "Session callers: confirms sending to recipients listed as sensitive in the compose preferences (otherwise `409 confirmation_required`)"6160                  type: "boolean"6161              required:6162                - "from"6163              additionalProperties: false6164      responses:6165        "200":6166          description: "Success"6167          content:6168            "application/json":6169              schema:6170                type: "object"6171                properties:6172                  id:6173                    type: "string"6174                    description: "msg_out_… (or the draft's msg_… id when status is draft)"6175                  status:6176                    type: "string"6177                    enum:6178                      - "queued"6179                      - "scheduled"6180                      - "pending_approval"6181                      - "sent"6182                      - "delivered"6183                      - "deferred"6184                      - "bounced"6185                      - "failed"6186                      - "cancelled"6187                      - "draft"6188                  from:6189                    type: "string"6190                  message_id:6191                    type:6192                      - "string"6193                      - "null"6194                  recipients:6195                    type: "array"6196                    items:6197                      type: "object"6198                      properties:6199                        address:6200                          type: "string"6201                        status:6202                          type: "string"6203                        smtp_reply:6204                          type:6205                            - "string"6206                            - "null"6207                      required:6208                        - "address"6209                        - "status"6210                        - "smtp_reply"6211                      additionalProperties: false6212                  external:6213                    type: "boolean"6214                  send_at:6215                    type:6216                      - "string"6217                      - "null"6218                  attempts:6219                    type: "number"6220                  last_error:6221                    type:6222                      - "string"6223                      - "null"6224                  submitted_at:6225                    type:6226                      - "string"6227                      - "null"6228                  final_at:6229                    type:6230                      - "string"6231                      - "null"6232                  created_at:6233                    type: "string"6234                  updated_at:6235                    type: "string"6236                  approval_id:6237                    type: "string"6238                  thread_id:6239                    type:6240                      - "string"6241                      - "null"6242                  undo_until:6243                    description: "Undo send: the message is held until this instant and can still be cancelled"6244                    type:6245                      - "string"6246                      - "null"6247                required:6248                  - "id"6249                  - "status"6250                  - "from"6251                  - "message_id"6252                  - "recipients"6253                  - "external"6254                  - "send_at"6255                  - "attempts"6256                  - "last_error"6257                  - "submitted_at"6258                  - "final_at"6259                  - "created_at"6260                  - "updated_at"6261                additionalProperties: false6262        "201":6263          description: "Draft saved"6264        "202":6265          description: "Accepted: scheduled, pending approval or queued"6266        default:6267          description: "Error"6268          content:6269            "application/json":6270              schema:6271                "$ref": "#/components/schemas/Error"6272      security:6273        -6274          apiKey: []6275        -6276          session: []6277      x-required-scopes:6278        - "mail.send"6279        - "mail.drafts"6280  "/messages/send-batch":6281    post:6282      operationId: "postMessagesSendBatch"6283      tags:6284        - "Sending"6285      summary: "Send up to 50 messages; each item is validated and limited independently"6286      parameters:6287        -6288          name: "Idempotency-Key"6289          in: "header"6290          required: false6291          description: "Replays the stored response for 24 h; a different payload with the same key answers 409."6292          schema:6293            type: "string"6294            maxLength: 2006295      requestBody:6296        required: true6297        content:6298          "application/json":6299            schema:6300              type: "object"6301              properties:6302                messages:6303                  minItems: 16304                  maxItems: 506305                  type: "array"6306                  items: {}6307              required:6308                - "messages"6309              additionalProperties: false6310      responses:6311        "200":6312          description: "Success"6313          content:6314            "application/json":6315              schema:6316                type: "object"6317                properties:6318                  results:6319                    type: "array"6320                    items:6321                      type: "object"6322                      properties:6323                        index:6324                          type: "number"6325                        ok:6326                          type: "boolean"6327                        status:6328                          type: "number"6329                        message:6330                          type: "object"6331                          properties:6332                            id:6333                              type: "string"6334                              description: "msg_out_… (or the draft's msg_… id when status is draft)"6335                            status:6336                              type: "string"6337                              enum:6338                                - "queued"6339                                - "scheduled"6340                                - "pending_approval"6341                                - "sent"6342                                - "delivered"6343                                - "deferred"6344                                - "bounced"6345                                - "failed"6346                                - "cancelled"6347                                - "draft"6348                            from:6349                              type: "string"6350                            message_id:6351                              type:6352                                - "string"6353                                - "null"6354                            recipients:6355                              type: "array"6356                              items:6357                                type: "object"6358                                properties:6359                                  address:6360                                    type: "string"6361                                  status:6362                                    type: "string"6363                                  smtp_reply:6364                                    type:6365                                      - "string"6366                                      - "null"6367                                required:6368                                  - "address"6369                                  - "status"6370                                  - "smtp_reply"6371                                additionalProperties: false6372                            external:6373                              type: "boolean"6374                            send_at:6375                              type:6376                                - "string"6377                                - "null"6378                            attempts:6379                              type: "number"6380                            last_error:6381                              type:6382                                - "string"6383                                - "null"6384                            submitted_at:6385                              type:6386                                - "string"6387                                - "null"6388                            final_at:6389                              type:6390                                - "string"6391                                - "null"6392                            created_at:6393                              type: "string"6394                            updated_at:6395                              type: "string"6396                            approval_id:6397                              type: "string"6398                            thread_id:6399                              type:6400                                - "string"6401                                - "null"6402                            undo_until:6403                              description: "Undo send: the message is held until this instant and can still be cancelled"6404                              type:6405                                - "string"6406                                - "null"6407                          required:6408                            - "id"6409                            - "status"6410                            - "from"6411                            - "message_id"6412                            - "recipients"6413                            - "external"6414                            - "send_at"6415                            - "attempts"6416                            - "last_error"6417                            - "submitted_at"6418                            - "final_at"6419                            - "created_at"6420                            - "updated_at"6421                          additionalProperties: false6422                        error:6423                          type: "object"6424                          properties:6425                            code:6426                              type: "string"6427                            message:6428                              type: "string"6429                            details: {}6430                          required:6431                            - "code"6432                            - "message"6433                          additionalProperties: false6434                      required:6435                        - "index"6436                        - "ok"6437                        - "status"6438                      additionalProperties: false6439                required:6440                  - "results"6441                additionalProperties: false6442        default:6443          description: "Error"6444          content:6445            "application/json":6446              schema:6447                "$ref": "#/components/schemas/Error"6448      security:6449        -6450          apiKey: []6451        -6452          session: []6453      x-required-scopes:6454        - "mail.send"6455  "/openapi.json":6456    get:6457      operationId: "getOpenapi.json"6458      tags:6459        - "Introspection"6460      summary: "OpenAPI 3.1 description (JSON), generated from the route registry"6461      responses:6462        "200":6463          description: "Success"6464          content:6465            "application/json":6466              schema:6467                type: "object"6468                propertyNames:6469                  type: "string"6470                additionalProperties: {}6471        default:6472          description: "Error"6473          content:6474            "application/json":6475              schema:6476                "$ref": "#/components/schemas/Error"6477      security: []6478      x-required-scopes: []6479  "/openapi.yaml":6480    get:6481      operationId: "getOpenapi.yaml"6482      tags:6483        - "Introspection"6484      summary: "OpenAPI 3.1 description (YAML)"6485      responses:6486        "200":6487          description: "Binary content"6488          content:6489            "application/octet-stream":6490              schema:6491                type: "string"6492                format: "binary"6493        default:6494          description: "Error"6495          content:6496            "application/json":6497              schema:6498                "$ref": "#/components/schemas/Error"6499      security: []6500      x-required-scopes: []6501  "/templates":6502    get:6503      operationId: "getTemplates"6504      tags:6505        - "Templates"6506      summary: "List the templates of the caller's library"6507      responses:6508        "200":6509          description: "Success"6510          content:6511            "application/json":6512              schema:6513                type: "object"6514                properties:6515                  templates:6516                    type: "array"6517                    items:6518                      type: "object"6519                      properties:6520                        id:6521                          type: "string"6522                        name:6523                          type: "string"6524                        category:6525                          type: "string"6526                        subject:6527                          type: "string"6528                        preheader:6529                          type: "string"6530                        variables:6531                          type: "array"6532                          items:6533                            type: "object"6534                            properties:6535                              name:6536                                type: "string"6537                              description:6538                                type: "string"6539                              example:6540                                type: "string"6541                              required:6542                                type: "boolean"6543                            required:6544                              - "name"6545                              - "description"6546                              - "example"6547                              - "required"6548                            additionalProperties: false6549                        source:6550                          type: "string"6551                          enum:6552                            - "manual"6553                            - "ai"6554                        version:6555                          type: "number"6556                        size_bytes:6557                          type: "number"6558                        created_at:6559                          type: "string"6560                        updated_at:6561                          type: "string"6562                      required:6563                        - "id"6564                        - "name"6565                        - "category"6566                        - "subject"6567                        - "preheader"6568                        - "variables"6569                        - "source"6570                        - "version"6571                        - "size_bytes"6572                        - "created_at"6573                        - "updated_at"6574                      additionalProperties: false6575                required:6576                  - "templates"6577                additionalProperties: false6578        default:6579          description: "Error"6580          content:6581            "application/json":6582              schema:6583                "$ref": "#/components/schemas/Error"6584      security:6585        -6586          apiKey: []6587        -6588          session: []6589      x-required-scopes:6590        - "mail.send"6591        - "mail.drafts"6592  "/templates/{id}":6593    get:6594      operationId: "getTemplatesId"6595      tags:6596        - "Templates"6597      summary: "Get a template with its HTML and plain text"6598      parameters:6599        -6600          name: "id"6601          in: "path"6602          required: true6603          schema:6604            type: "string"6605            format: "uuid"6606            pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"6607      responses:6608        "200":6609          description: "Success"6610          content:6611            "application/json":6612              schema:6613                type: "object"6614                properties:6615                  id:6616                    type: "string"6617                  name:6618                    type: "string"6619                  category:6620                    type: "string"6621                  subject:6622                    type: "string"6623                  preheader:6624                    type: "string"6625                  variables:6626                    type: "array"6627                    items:6628                      type: "object"6629                      properties:6630                        name:6631                          type: "string"6632                        description:6633                          type: "string"6634                        example:6635                          type: "string"6636                        required:6637                          type: "boolean"6638                      required:6639                        - "name"6640                        - "description"6641                        - "example"6642                        - "required"6643                      additionalProperties: false6644                  source:6645                    type: "string"6646                    enum:6647                      - "manual"6648                      - "ai"6649                  version:6650                    type: "number"6651                  size_bytes:6652                    type: "number"6653                  created_at:6654                    type: "string"6655                  updated_at:6656                    type: "string"6657                  html:6658                    type: "string"6659                  text:6660                    type: "string"6661                required:6662                  - "id"6663                  - "name"6664                  - "category"6665                  - "subject"6666                  - "preheader"6667                  - "variables"6668                  - "source"6669                  - "version"6670                  - "size_bytes"6671                  - "created_at"6672                  - "updated_at"6673                  - "html"6674                  - "text"6675                additionalProperties: false6676        default:6677          description: "Error"6678          content:6679            "application/json":6680              schema:6681                "$ref": "#/components/schemas/Error"6682      security:6683        -6684          apiKey: []6685        -6686          session: []6687      x-required-scopes:6688        - "mail.send"6689        - "mail.drafts"6690  "/templates/{id}/render":6691    post:6692      operationId: "postTemplatesIdRender"6693      tags:6694        - "Templates"6695      summary: "Render a template with variable values, without sending"6696      description: "Values are HTML-escaped; a value placed in an href/src attribute must be an http(s) or mailto URL, otherwise it becomes `#`. With `use_examples` (default false) missing variables take their example value."6697      parameters:6698        -6699          name: "id"6700          in: "path"6701          required: true6702          schema:6703            type: "string"6704            format: "uuid"6705            pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"6706      requestBody:6707        required: true6708        content:6709          "application/json":6710            schema:6711              type: "object"6712              properties:6713                variables:6714                  default: {}6715                  type: "object"6716                  propertyNames:6717                    type: "string"6718                  additionalProperties:6719                    type: "string"6720                    maxLength: 200006721                use_examples:6722                  default: false6723                  type: "boolean"6724              additionalProperties: false6725      responses:6726        "200":6727          description: "Success"6728          content:6729            "application/json":6730              schema:6731                type: "object"6732                properties:6733                  subject:6734                    type: "string"6735                  preheader:6736                    type: "string"6737                  html:6738                    type: "string"6739                  text:6740                    type: "string"6741                  missing:6742                    type: "array"6743                    items:6744                      type: "string"6745                required:6746                  - "subject"6747                  - "preheader"6748                  - "html"6749                  - "text"6750                  - "missing"6751                additionalProperties: false6752        default:6753          description: "Error"6754          content:6755            "application/json":6756              schema:6757                "$ref": "#/components/schemas/Error"6758      security:6759        -6760          apiKey: []6761        -6762          session: []6763      x-required-scopes:6764        - "mail.send"6765        - "mail.drafts"6766  "/threads":6767    get:6768      operationId: "getThreads"6769      tags:6770        - "Messages"6771      summary: "List conversations (one entry per thread, newest message first)"6772      description: "Same filters and cursor as GET /messages. For address-restricted (alias-level) views threads are collapsed per page, so a thread may reappear on a later page."6773      parameters:6774        -6775          name: "address"6776          in: "query"6777          required: false6778          description: "Comma-separated addresses to read (each must be allowed). A mailbox's primary address means the whole mailbox; an alias means only mail delivered to / sent from it. Omitted = every address the caller may read."6779          schema:6780            type: "string"6781            maxLength: 20006782        -6783          name: "mailbox"6784          in: "query"6785          required: false6786          description: "Synonym of `address` for primary mailbox addresses"6787          schema:6788            type: "string"6789            maxLength: 20006790        -6791          name: "folder"6792          in: "query"6793          required: false6794          description: "Folder role (inbox, drafts, sent, trash, junk, archive) resolved in each mailbox, or a folder id (fld_…)"6795          schema:6796            type: "string"6797            maxLength: 3006798        -6799          name: "unread"6800          in: "query"6801          required: false6802          schema:6803            type: "string"6804            enum:6805              - "true"6806              - "false"6807        -6808          name: "flagged"6809          in: "query"6810          required: false6811          description: "Starred / important"6812          schema:6813            type: "string"6814            enum:6815              - "true"6816              - "false"6817        -6818          name: "has_attachment"6819          in: "query"6820          required: false6821          schema:6822            type: "string"6823            enum:6824              - "true"6825              - "false"6826        -6827          name: "from"6828          in: "query"6829          required: false6830          schema:6831            type: "string"6832            maxLength: 2006833        -6834          name: "to"6835          in: "query"6836          required: false6837          schema:6838            type: "string"6839            maxLength: 2006840        -6841          name: "subject"6842          in: "query"6843          required: false6844          schema:6845            type: "string"6846            maxLength: 2006847        -6848          name: "text"6849          in: "query"6850          required: false6851          description: "Full-text search (headers, bodies and, as far as the server indexes them, attachments)"6852          schema:6853            type: "string"6854            maxLength: 3006855        -6856          name: "before"6857          in: "query"6858          required: false6859          description: "Received strictly before (ISO 8601)"6860          schema:6861            type: "string"6862        -6863          name: "after"6864          in: "query"6865          required: false6866          description: "Received at or after (ISO 8601)"6867          schema:6868            type: "string"6869        -6870          name: "label"6871          in: "query"6872          required: false6873          schema:6874            type: "string"6875        -6876          name: "limit"6877          in: "query"6878          required: false6879          schema:6880            default: 256881            type: "integer"6882            minimum: 16883            maximum: 1006884        -6885          name: "cursor"6886          in: "query"6887          required: false6888          schema:6889            type: "string"6890            maxLength: 20006891      responses:6892        "200":6893          description: "Success"6894          content:6895            "application/json":6896              schema:6897                type: "object"6898                properties:6899                  data:6900                    type: "array"6901                    items:6902                      type: "object"6903                      properties:6904                        id:6905                          type: "string"6906                        mailbox:6907                          type: "string"6908                        latest:6909                          type: "object"6910                          properties:6911                            id:6912                              type: "string"6913                            thread_id:6914                              type: "string"6915                            mailbox:6916                              type: "string"6917                              description: "Primary address of the physical mailbox holding the message"6918                            delivered_to:6919                              type: "array"6920                              items:6921                                type: "string"6922                              description: "Envelope recipients recorded by the mail server (Delivered-To)"6923                            folders:6924                              type: "array"6925                              items:6926                                type: "object"6927                                properties:6928                                  id:6929                                    type: "string"6930                                  role:6931                                    type:6932                                      - "string"6933                                      - "null"6934                                  name:6935                                    type: "string"6936                                required:6937                                  - "id"6938                                  - "role"6939                                  - "name"6940                                additionalProperties: false6941                            from:6942                              type: "array"6943                              items:6944                                type: "object"6945                                properties:6946                                  email:6947                                    type: "string"6948                                  name:6949                                    type:6950                                      - "string"6951                                      - "null"6952                                required:6953                                  - "email"6954                                  - "name"6955                                additionalProperties: false6956                            to:6957                              type: "array"6958                              items:6959                                type: "object"6960                                properties:6961                                  email:6962                                    type: "string"6963                                  name:6964                                    type:6965                                      - "string"6966                                      - "null"6967                                required:6968                                  - "email"6969                                  - "name"6970                                additionalProperties: false6971                            cc:6972                              type: "array"6973                              items:6974                                type: "object"6975                                properties:6976                                  email:6977                                    type: "string"6978                                  name:6979                                    type:6980                                      - "string"6981                                      - "null"6982                                required:6983                                  - "email"6984                                  - "name"6985                                additionalProperties: false6986                            subject:6987                              type: "string"6988                            preview:6989                              type: "string"6990                            received_at:6991                              type: "string"6992                            sent_at:6993                              type:6994                                - "string"6995                                - "null"6996                            size:6997                              type: "number"6998                            unread:6999                              type: "boolean"7000                            starred:7001                              type: "boolean"7002                            draft:7003                              type: "boolean"7004                            answered:7005                              type: "boolean"7006                            forwarded:7007                              type: "boolean"7008                            has_attachment:7009                              type: "boolean"7010                            labels:7011                              type: "array"7012                              items:7013                                type: "string"7014                            pinned:7015                              type: "boolean"7016                              description: "Pinned to the top of its lists (`$pinned` keyword)"7017                            snoozed:7018                              type: "boolean"7019                              description: "Currently snoozed (`$snoozed` keyword); it returns to the inbox when the snooze ends"7020                            followup:7021                              type: "boolean"7022                              description: "A follow-up reminder is set on the message (`$followup` keyword)"7023                          required:7024                            - "id"7025                            - "thread_id"7026                            - "mailbox"7027                            - "delivered_to"7028                            - "folders"7029                            - "from"7030                            - "to"7031                            - "cc"7032                            - "subject"7033                            - "preview"7034                            - "received_at"7035                            - "sent_at"7036                            - "size"7037                            - "unread"7038                            - "starred"7039                            - "draft"7040                            - "answered"7041                            - "forwarded"7042                            - "has_attachment"7043                            - "labels"7044                            - "pinned"7045                            - "snoozed"7046                            - "followup"7047                          additionalProperties: false7048                      required:7049                        - "id"7050                        - "mailbox"7051                        - "latest"7052                      additionalProperties: false7053                  next_cursor:7054                    type:7055                      - "string"7056                      - "null"7057                  has_more:7058                    type: "boolean"7059                required:7060                  - "data"7061                  - "next_cursor"7062                  - "has_more"7063                additionalProperties: false7064        default:7065          description: "Error"7066          content:7067            "application/json":7068              schema:7069                "$ref": "#/components/schemas/Error"7070      security:7071        -7072          apiKey: []7073        -7074          session: []7075      x-required-scopes:7076        - "mail.read"7077  "/threads/{id}":7078    get:7079      operationId: "getThreadsId"7080      tags:7081        - "Messages"7082      summary: "Messages of a conversation, oldest first"7083      parameters:7084        -7085          name: "id"7086          in: "path"7087          required: true7088          schema:7089            type: "string"7090            maxLength: 4007091      responses:7092        "200":7093          description: "Success"7094          content:7095            "application/json":7096              schema:7097                type: "object"7098                properties:7099                  id:7100                    type: "string"7101                  mailbox:7102                    type: "string"7103                  messages:7104                    type: "array"7105                    items:7106                      type: "object"7107                      properties:7108                        id:7109                          type: "string"7110                        thread_id:7111                          type: "string"7112                        mailbox:7113                          type: "string"7114                          description: "Primary address of the physical mailbox holding the message"7115                        delivered_to:7116                          type: "array"7117                          items:7118                            type: "string"7119                          description: "Envelope recipients recorded by the mail server (Delivered-To)"7120                        folders:7121                          type: "array"7122                          items:7123                            type: "object"7124                            properties:7125                              id:7126                                type: "string"7127                              role:7128                                type:7129                                  - "string"7130                                  - "null"7131                              name:7132                                type: "string"7133                            required:7134                              - "id"7135                              - "role"7136                              - "name"7137                            additionalProperties: false7138                        from:7139                          type: "array"7140                          items:7141                            type: "object"7142                            properties:7143                              email:7144                                type: "string"7145                              name:7146                                type:7147                                  - "string"7148                                  - "null"7149                            required:7150                              - "email"7151                              - "name"7152                            additionalProperties: false7153                        to:7154                          type: "array"7155                          items:7156                            type: "object"7157                            properties:7158                              email:7159                                type: "string"7160                              name:7161                                type:7162                                  - "string"7163                                  - "null"7164                            required:7165                              - "email"7166                              - "name"7167                            additionalProperties: false7168                        cc:7169                          type: "array"7170                          items:7171                            type: "object"7172                            properties:7173                              email:7174                                type: "string"7175                              name:7176                                type:7177                                  - "string"7178                                  - "null"7179                            required:7180                              - "email"7181                              - "name"7182                            additionalProperties: false7183                        subject:7184                          type: "string"7185                        preview:7186                          type: "string"7187                        received_at:7188                          type: "string"7189                        sent_at:7190                          type:7191                            - "string"7192                            - "null"7193                        size:7194                          type: "number"7195                        unread:7196                          type: "boolean"7197                        starred:7198                          type: "boolean"7199                        draft:7200                          type: "boolean"7201                        answered:7202                          type: "boolean"7203                        forwarded:7204                          type: "boolean"7205                        has_attachment:7206                          type: "boolean"7207                        labels:7208                          type: "array"7209                          items:7210                            type: "string"7211                        pinned:7212                          type: "boolean"7213                          description: "Pinned to the top of its lists (`$pinned` keyword)"7214                        snoozed:7215                          type: "boolean"7216                          description: "Currently snoozed (`$snoozed` keyword); it returns to the inbox when the snooze ends"7217                        followup:7218                          type: "boolean"7219                          description: "A follow-up reminder is set on the message (`$followup` keyword)"7220                      required:7221                        - "id"7222                        - "thread_id"7223                        - "mailbox"7224                        - "delivered_to"7225                        - "folders"7226                        - "from"7227                        - "to"7228                        - "cc"7229                        - "subject"7230                        - "preview"7231                        - "received_at"7232                        - "sent_at"7233                        - "size"7234                        - "unread"7235                        - "starred"7236                        - "draft"7237                        - "answered"7238                        - "forwarded"7239                        - "has_attachment"7240                        - "labels"7241                        - "pinned"7242                        - "snoozed"7243                        - "followup"7244                      additionalProperties: false7245                required:7246                  - "id"7247                  - "mailbox"7248                  - "messages"7249                additionalProperties: false7250        default:7251          description: "Error"7252          content:7253            "application/json":7254              schema:7255                "$ref": "#/components/schemas/Error"7256      security:7257        -7258          apiKey: []7259        -7260          session: []7261      x-required-scopes:7262        - "mail.read"7263  "/webhook-deliveries/{id}/replay":7264    post:7265      operationId: "postWebhookDeliveriesIdReplay"7266      tags:7267        - "Webhooks"7268      summary: "Replay a delivery (same event id, new signature and timestamp)"7269      description: "Queues the delivery again with the attempt counter reset; the normal backoff applies if the receiver fails again."7270      parameters:7271        -7272          name: "id"7273          in: "path"7274          required: true7275          schema:7276            type: "string"7277            maxLength: 607278      responses:7279        "200":7280          description: "Success"7281          content:7282            "application/json":7283              schema:7284                type: "object"7285                properties:7286                  id:7287                    type: "string"7288                  webhook_id:7289                    type: "string"7290                  event_id:7291                    type: "string"7292                  event_type:7293                    type: "string"7294                  status:7295                    type: "string"7296                    enum:7297                      - "pending"7298                      - "retrying"7299                      - "delivered"7300                      - "failed"7301                  attempt:7302                    type: "number"7303                  next_attempt_at:7304                    type:7305                      - "string"7306                      - "null"7307                  last_status:7308                    type:7309                      - "number"7310                      - "null"7311                  last_error:7312                    type:7313                      - "string"7314                      - "null"7315                  delivered_at:7316                    type:7317                      - "string"7318                      - "null"7319                  created_at:7320                    type: "string"7321                required:7322                  - "id"7323                  - "webhook_id"7324                  - "event_id"7325                  - "event_type"7326                  - "status"7327                  - "attempt"7328                  - "next_attempt_at"7329                  - "last_status"7330                  - "last_error"7331                  - "delivered_at"7332                  - "created_at"7333                additionalProperties: false7334        default:7335          description: "Error"7336          content:7337            "application/json":7338              schema:7339                "$ref": "#/components/schemas/Error"7340      security:7341        -7342          apiKey: []7343        -7344          session: []7345      x-required-scopes:7346        - "mail.webhooks.manage"7347  "/webhooks":7348    get:7349      operationId: "getWebhooks"7350      tags:7351        - "Webhooks"7352      summary: "List webhooks"7353      responses:7354        "200":7355          description: "Success"7356          content:7357            "application/json":7358              schema:7359                type: "object"7360                properties:7361                  data:7362                    type: "array"7363                    items:7364                      type: "object"7365                      properties:7366                        id:7367                          type: "string"7368                        name:7369                          type: "string"7370                        url:7371                          type: "string"7372                        events:7373                          type: "array"7374                          items:7375                            type: "string"7376                        address_ids:7377                          type: "array"7378                          items:7379                            type: "string"7380                        include_content:7381                          type: "boolean"7382                        active:7383                          type: "boolean"7384                        owner:7385                          type: "string"7386                          enum:7387                            - "key"7388                            - "admin"7389                        key_id:7390                          type:7391                            - "string"7392                            - "null"7393                        created_at:7394                          type: "string"7395                        updated_at:7396                          type: "string"7397                        secret:7398                          description: "Only present at creation and after a secret rotation; never shown again"7399                          type: "string"7400                      required:7401                        - "id"7402                        - "name"7403                        - "url"7404                        - "events"7405                        - "address_ids"7406                        - "include_content"7407                        - "active"7408                        - "owner"7409                        - "key_id"7410                        - "created_at"7411                        - "updated_at"7412                      additionalProperties: false7413                required:7414                  - "data"7415                additionalProperties: false7416        default:7417          description: "Error"7418          content:7419            "application/json":7420              schema:7421                "$ref": "#/components/schemas/Error"7422      security:7423        -7424          apiKey: []7425        -7426          session: []7427      x-required-scopes:7428        - "mail.webhooks.manage"7429    post:7430      operationId: "postWebhooks"7431      tags:7432        - "Webhooks"7433      summary: "Create a webhook (the signing secret is returned once)"7434      description: "The URL must be https on port 443 and resolve only to public addresses, unless its host:port is in the administrator-managed internal allowlist. Redirects are never followed. A key-owned webhook only receives events for addresses the key can see."7435      parameters:7436        -7437          name: "Idempotency-Key"7438          in: "header"7439          required: false7440          description: "Replays the stored response for 24 h; a different payload with the same key answers 409."7441          schema:7442            type: "string"7443            maxLength: 2007444      requestBody:7445        required: true7446        content:7447          "application/json":7448            schema:7449              type: "object"7450              properties:7451                name:7452                  type: "string"7453                  minLength: 17454                  maxLength: 807455                url:7456                  type: "string"7457                  maxLength: 20007458                events:7459                  minItems: 17460                  maxItems: 127461                  type: "array"7462                  items:7463                    type: "string"7464                    enum:7465                      - "message.received"7466                      - "message.sent"7467                      - "message.delivered"7468                      - "message.deferred"7469                      - "message.bounced"7470                      - "message.failed"7471                      - "message.read"7472                      - "message.deleted"7473                      - "draft.created"7474                      - "address.created"7475                      - "address.suspended"7476                      - "rule.matched"7477                address_ids:7478                  default: []7479                  maxItems: 2007480                  type: "array"7481                  items:7482                    type: "string"7483                    format: "uuid"7484                    pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"7485                include_content:7486                  default: false7487                  type: "boolean"7488                active:7489                  default: true7490                  type: "boolean"7491              required:7492                - "name"7493                - "url"7494                - "events"7495              additionalProperties: false7496      responses:7497        "201":7498          description: "Success"7499          content:7500            "application/json":7501              schema:7502                type: "object"7503                properties:7504                  id:7505                    type: "string"7506                  name:7507                    type: "string"7508                  url:7509                    type: "string"7510                  events:7511                    type: "array"7512                    items:7513                      type: "string"7514                  address_ids:7515                    type: "array"7516                    items:7517                      type: "string"7518                  include_content:7519                    type: "boolean"7520                  active:7521                    type: "boolean"7522                  owner:7523                    type: "string"7524                    enum:7525                      - "key"7526                      - "admin"7527                  key_id:7528                    type:7529                      - "string"7530                      - "null"7531                  created_at:7532                    type: "string"7533                  updated_at:7534                    type: "string"7535                  secret:7536                    description: "Only present at creation and after a secret rotation; never shown again"7537                    type: "string"7538                required:7539                  - "id"7540                  - "name"7541                  - "url"7542                  - "events"7543                  - "address_ids"7544                  - "include_content"7545                  - "active"7546                  - "owner"7547                  - "key_id"7548                  - "created_at"7549                  - "updated_at"7550                additionalProperties: false7551        default:7552          description: "Error"7553          content:7554            "application/json":7555              schema:7556                "$ref": "#/components/schemas/Error"7557      security:7558        -7559          apiKey: []7560        -7561          session: []7562      x-required-scopes:7563        - "mail.webhooks.manage"7564  "/webhooks/{id}":7565    delete:7566      operationId: "deleteWebhooksId"7567      tags:7568        - "Webhooks"7569      summary: "Delete a webhook and its delivery history"7570      parameters:7571        -7572          name: "id"7573          in: "path"7574          required: true7575          schema:7576            type: "string"7577            maxLength: 607578      responses:7579        "200":7580          description: "Success"7581          content:7582            "application/json":7583              schema:7584                type: "object"7585                properties:7586                  ok:7587                    type: "boolean"7588                    const: true7589                required:7590                  - "ok"7591                additionalProperties: false7592        default:7593          description: "Error"7594          content:7595            "application/json":7596              schema:7597                "$ref": "#/components/schemas/Error"7598      security:7599        -7600          apiKey: []7601        -7602          session: []7603      x-required-scopes:7604        - "mail.webhooks.manage"7605    get:7606      operationId: "getWebhooksId"7607      tags:7608        - "Webhooks"7609      summary: "Read a webhook"7610      parameters:7611        -7612          name: "id"7613          in: "path"7614          required: true7615          schema:7616            type: "string"7617            maxLength: 607618      responses:7619        "200":7620          description: "Success"7621          content:7622            "application/json":7623              schema:7624                type: "object"7625                properties:7626                  id:7627                    type: "string"7628                  name:7629                    type: "string"7630                  url:7631                    type: "string"7632                  events:7633                    type: "array"7634                    items:7635                      type: "string"7636                  address_ids:7637                    type: "array"7638                    items:7639                      type: "string"7640                  include_content:7641                    type: "boolean"7642                  active:7643                    type: "boolean"7644                  owner:7645                    type: "string"7646                    enum:7647                      - "key"7648                      - "admin"7649                  key_id:7650                    type:7651                      - "string"7652                      - "null"7653                  created_at:7654                    type: "string"7655                  updated_at:7656                    type: "string"7657                  secret:7658                    description: "Only present at creation and after a secret rotation; never shown again"7659                    type: "string"7660                required:7661                  - "id"7662                  - "name"7663                  - "url"7664                  - "events"7665                  - "address_ids"7666                  - "include_content"7667                  - "active"7668                  - "owner"7669                  - "key_id"7670                  - "created_at"7671                  - "updated_at"7672                additionalProperties: false7673        default:7674          description: "Error"7675          content:7676            "application/json":7677              schema:7678                "$ref": "#/components/schemas/Error"7679      security:7680        -7681          apiKey: []7682        -7683          session: []7684      x-required-scopes:7685        - "mail.webhooks.manage"7686    patch:7687      operationId: "patchWebhooksId"7688      tags:7689        - "Webhooks"7690      summary: "Update a webhook, or rotate its secret"7691      description: "`rotate_secret: true` returns a new secret once (sessions need a recent re-authentication)."7692      parameters:7693        -7694          name: "id"7695          in: "path"7696          required: true7697          schema:7698            type: "string"7699            maxLength: 607700      requestBody:7701        required: true7702        content:7703          "application/json":7704            schema:7705              type: "object"7706              properties:7707                name:7708                  type: "string"7709                  minLength: 17710                  maxLength: 807711                url:7712                  type: "string"7713                  maxLength: 20007714                events:7715                  minItems: 17716                  maxItems: 127717                  type: "array"7718                  items:7719                    type: "string"7720                    enum:7721                      - "message.received"7722                      - "message.sent"7723                      - "message.delivered"7724                      - "message.deferred"7725                      - "message.bounced"7726                      - "message.failed"7727                      - "message.read"7728                      - "message.deleted"7729                      - "draft.created"7730                      - "address.created"7731                      - "address.suspended"7732                      - "rule.matched"7733                address_ids:7734                  default: []7735                  maxItems: 2007736                  type: "array"7737                  items:7738                    type: "string"7739                    format: "uuid"7740                    pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"7741                include_content:7742                  default: false7743                  type: "boolean"7744                active:7745                  default: true7746                  type: "boolean"7747                rotate_secret:7748                  type: "boolean"7749              additionalProperties: false7750      responses:7751        "200":7752          description: "Success"7753          content:7754            "application/json":7755              schema:7756                type: "object"7757                properties:7758                  id:7759                    type: "string"7760                  name:7761                    type: "string"7762                  url:7763                    type: "string"7764                  events:7765                    type: "array"7766                    items:7767                      type: "string"7768                  address_ids:7769                    type: "array"7770                    items:7771                      type: "string"7772                  include_content:7773                    type: "boolean"7774                  active:7775                    type: "boolean"7776                  owner:7777                    type: "string"7778                    enum:7779                      - "key"7780                      - "admin"7781                  key_id:7782                    type:7783                      - "string"7784                      - "null"7785                  created_at:7786                    type: "string"7787                  updated_at:7788                    type: "string"7789                  secret:7790                    description: "Only present at creation and after a secret rotation; never shown again"7791                    type: "string"7792                required:7793                  - "id"7794                  - "name"7795                  - "url"7796                  - "events"7797                  - "address_ids"7798                  - "include_content"7799                  - "active"7800                  - "owner"7801                  - "key_id"7802                  - "created_at"7803                  - "updated_at"7804                additionalProperties: false7805        default:7806          description: "Error"7807          content:7808            "application/json":7809              schema:7810                "$ref": "#/components/schemas/Error"7811      security:7812        -7813          apiKey: []7814        -7815          session: []7816      x-required-scopes:7817        - "mail.webhooks.manage"7818  "/webhooks/{id}/deliveries":7819    get:7820      operationId: "getWebhooksIdDeliveries"7821      tags:7822        - "Webhooks"7823      summary: "Delivery attempts of a webhook, newest first"7824      parameters:7825        -7826          name: "id"7827          in: "path"7828          required: true7829          schema:7830            type: "string"7831            maxLength: 607832        -7833          name: "status"7834          in: "query"7835          required: false7836          schema:7837            type: "string"7838            enum:7839              - "pending"7840              - "retrying"7841              - "delivered"7842              - "failed"7843        -7844          name: "limit"7845          in: "query"7846          required: false7847          schema:7848            default: 257849            type: "integer"7850            minimum: 17851            maximum: 1007852        -7853          name: "cursor"7854          in: "query"7855          required: false7856          schema:7857            type: "string"7858            maxLength: 20007859      responses:7860        "200":7861          description: "Success"7862          content:7863            "application/json":7864              schema:7865                type: "object"7866                properties:7867                  data:7868                    type: "array"7869                    items:7870                      type: "object"7871                      properties:7872                        id:7873                          type: "string"7874                        webhook_id:7875                          type: "string"7876                        event_id:7877                          type: "string"7878                        event_type:7879                          type: "string"7880                        status:7881                          type: "string"7882                          enum:7883                            - "pending"7884                            - "retrying"7885                            - "delivered"7886                            - "failed"7887                        attempt:7888                          type: "number"7889                        next_attempt_at:7890                          type:7891                            - "string"7892                            - "null"7893                        last_status:7894                          type:7895                            - "number"7896                            - "null"7897                        last_error:7898                          type:7899                            - "string"7900                            - "null"7901                        delivered_at:7902                          type:7903                            - "string"7904                            - "null"7905                        created_at:7906                          type: "string"7907                      required:7908                        - "id"7909                        - "webhook_id"7910                        - "event_id"7911                        - "event_type"7912                        - "status"7913                        - "attempt"7914                        - "next_attempt_at"7915                        - "last_status"7916                        - "last_error"7917                        - "delivered_at"7918                        - "created_at"7919                      additionalProperties: false7920                  next_cursor:7921                    type:7922                      - "string"7923                      - "null"7924                  has_more:7925                    type: "boolean"7926                required:7927                  - "data"7928                  - "next_cursor"7929                  - "has_more"7930                additionalProperties: false7931        default:7932          description: "Error"7933          content:7934            "application/json":7935              schema:7936                "$ref": "#/components/schemas/Error"7937      security:7938        -7939          apiKey: []7940        -7941          session: []7942      x-required-scopes:7943        - "mail.webhooks.manage"7944  "/webhooks/{id}/test":7945    post:7946      operationId: "postWebhooksIdTest"7947      tags:7948        - "Webhooks"7949      summary: "Send a signed `webhook.test` event to this webhook now"7950      parameters:7951        -7952          name: "id"7953          in: "path"7954          required: true7955          schema:7956            type: "string"7957            maxLength: 607958      responses:7959        "200":7960          description: "Success"7961          content:7962            "application/json":7963              schema:7964                type: "object"7965                properties:7966                  delivery:7967                    type: "object"7968                    properties:7969                      id:7970                        type: "string"7971                      webhook_id:7972                        type: "string"7973                      event_id:7974                        type: "string"7975                      event_type:7976                        type: "string"7977                      status:7978                        type: "string"7979                        enum:7980                          - "pending"7981                          - "retrying"7982                          - "delivered"7983                          - "failed"7984                      attempt:7985                        type: "number"7986                      next_attempt_at:7987                        type:7988                          - "string"7989                          - "null"7990                      last_status:7991                        type:7992                          - "number"7993                          - "null"7994                      last_error:7995                        type:7996                          - "string"7997                          - "null"7998                      delivered_at:7999                        type:8000                          - "string"8001                          - "null"8002                      created_at:8003                        type: "string"8004                    required:8005                      - "id"8006                      - "webhook_id"8007                      - "event_id"8008                      - "event_type"8009                      - "status"8010                      - "attempt"8011                      - "next_attempt_at"8012                      - "last_status"8013                      - "last_error"8014                      - "delivered_at"8015                      - "created_at"8016                    additionalProperties: false8017                  http_status:8018                    type:8019                      - "number"8020                      - "null"8021                  error:8022                    type:8023                      - "string"8024                      - "null"8025                required:8026                  - "delivery"8027                  - "http_status"8028                  - "error"8029                additionalProperties: false8030        default:8031          description: "Error"8032          content:8033            "application/json":8034              schema:8035                "$ref": "#/components/schemas/Error"8036      security:8037        -8038          apiKey: []8039        -8040          session: []8041      x-required-scopes:8042        - "mail.webhooks.manage"8043components:8044  securitySchemes:8045    apiKey:8046      type: "http"8047      scheme: "bearer"8048      description: "API key: Authorization: Bearer spm_<prefix>_<secret>"8049    session:8050      type: "apiKey"8051      in: "cookie"8052      name: "__Host-spmail_session"8053      description: "Web session (or native bearer session token) of the owner"8054  schemas:8055    Error:8056      type: "object"8057      properties:8058        error:8059          type: "object"8060          properties:8061            code:8062              type: "string"8063            message:8064              type: "string"8065            details: {}8066          required:8067            - "code"8068            - "message"8069          additionalProperties: false8070      required:8071        - "error"8072      additionalProperties: false8073
Files main
Menu

Theme