Repository Public
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