Create a mailbox (comms:admin, desk:admin or hr:recruiting:manage; Microsoft 365 only comms:admin)
POST /api/comms/v1/mailboxes
Module: Comms · operationId: createMailbox · Tag: Mailboxes · Auth: access token (Authorization: Bearer <accessToken>)
kind ses creates the address <localPart>@<subdomain>.<mail domain> (with randomSuffix
<localPart>-<6 random characters>@…) for consumer desk or recruiting; 400 with field subdomain while the
tenant has no subdomain, field localPart when the address is taken. kind msgraph reads the folders of the
mailbox address with the Microsoft 365 connection channelId (consumer desk, recruiting or invoice – the
Belegeingang moves new mail to the progress folder and queues its PDF/XML attachments and the raw mail for DMS;
the app needs Mail.ReadWrite, for answers Mail.Send). Several mailboxes may share a connection; 400 with field
fetchFolder when another mailbox of the connection reads the same folder of the same address.
Request body
application/json (required)
address(string (email)): Microsoft 365 mailbox the connection reads and answers from (msgraph; required on create, stored lower-case; empty on change keeps it) (max length 254)archiveFolder(string): Folder processed mail is moved to (msgraph)channelId(string (uuid)): Microsoft 365 connection (create, msgraph)consumer(string): Create only; invoice only with kind msgraph (the platform address of the Belegeingang: /mail-intake) (one ofdesk,recruiting,invoice)enabled(boolean): Import mails; omitted keeps the valuefetchFolder(string): Folder new mail is read from (msgraph)kind(string): Create only (one ofses,msgraph)localPart(string): Part before the @ (create, ses; required there). a–z, 0–9 and inner hyphens; postmaster, abuse and the like are reserved (max length 40)name(string): Display name (max length 100)progressFolder(string): Folder mail is moved to while it is processed (msgraph)randomSuffix(boolean): Adds a random suffix (support-k7m2qa) so the address cannot be guessed (create, ses)rejectedFolder(string): Folder rejected mail is moved to (msgraph)rev(integer): Revision a change is based on (0 creates)
Example:
{
"address": "support@muster-it.example",
"archiveFolder": "Posteingang/Erledigt",
"channelId": "5e7a9c1b-3d4f-4a6b-9c8d-0e1f2a3b4c5d",
"consumer": "desk",
"enabled": true,
"fetchFolder": "Posteingang",
"kind": "msgraph",
"name": "Service Desk",
"progressFolder": "Posteingang/In Bearbeitung",
"rejectedFolder": "Posteingang/Abgelehnt",
"rev": 0
}
Responses
- 201 Mailbox (
application/json) - 400 Error (
application/json) - 403 Error (
application/json)
Fields of the 201 answer:
address(string): Platform address (ses) or the Microsoft 365 mailbox address (msgraph)archiveFolder(string): Folder processed mail is moved to (msgraph)channelId(string (uuid)): Microsoft 365 connection that reads the mailbox (msgraph)channelName(string): Name of that connectionconsumer(string): The module the mails go to (one ofinvoice,desk,recruiting)enabled(boolean): Mails are importedfetchFolder(string): Folder new mail is read from (msgraph)id(string (uuid)): Mailbox idkind(string): ses: a platform address; msgraph: a Microsoft 365 mailbox (one ofses,msgraph)lastError(string): Error of the last import runlastImported(integer): Mails imported by the last run (msgraph) or received in total (ses)lastReceivedAt(string (date-time)): Time of the last received maillastRunAt(string (date-time)): Time of the last import run (msgraph)name(string): Display namepending(integer): Received mails still waiting for their consumer (state PENDING)previous(array of object): Rotated addresses that are still accepted (ses)address(string): The old addressvalidUntil(string (date-time)): Until when it is accepted
progressFolder(string): Folder mail is moved to while it is processed (msgraph)rejectedFolder(string): Folder rejected mail is moved to (msgraph)rev(integer): Revision for optimistic locking (send it back asrev)updatedAt(string (date-time)): Time of the last changeupdatedBy(string): Who changed the mailbox last
Example 201 answer:
{
"address": "support@muster-it.example",
"archiveFolder": "Posteingang/Erledigt",
"channelId": "5e7a9c1b-3d4f-4a6b-9c8d-0e1f2a3b4c5d",
"channelName": "Microsoft 365 Muster IT",
"consumer": "desk",
"enabled": true,
"fetchFolder": "Posteingang",
"id": "3d5f7a9b-1c2e-4f4a-8b6c-8d0e1f2a3b4c",
"kind": "msgraph",
"lastImported": 3,
"lastReceivedAt": "2026-11-18T07:58:41Z",
"lastRunAt": "2026-11-18T08:00:03Z",
"name": "Service Desk",
"pending": 0,
"progressFolder": "Posteingang/In Bearbeitung",
"rejectedFolder": "Posteingang/Abgelehnt",
"rev": 7,
"updatedAt": "2026-10-21T15:30:00Z",
"updatedBy": "sophie.huber@muster-it.example"
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/comms/v1/mailboxes' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"address":"support@muster-it.example","archiveFolder":"Posteingang/Erledigt","channelId":"5e7a9c1b-3d4f-4a6b-9c8d-0e1f2a3b4c5d","consumer":"desk","enabled":true,"fetchFolder":"Posteingang","kind":"msgraph","name":"Service Desk","progressFolder":"Posteingang/In Bearbeitung","rejectedFolder":"Posteingang/Abgelehnt","rev":0}'