ConnectCloud Developers

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 of desk, recruiting, invoice)
  • enabled (boolean): Import mails; omitted keeps the value
  • fetchFolder (string): Folder new mail is read from (msgraph)
  • kind (string): Create only (one of ses, 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 connection
  • consumer (string): The module the mails go to (one of invoice, desk, recruiting)
  • enabled (boolean): Mails are imported
  • fetchFolder (string): Folder new mail is read from (msgraph)
  • id (string (uuid)): Mailbox id
  • kind (string): ses: a platform address; msgraph: a Microsoft 365 mailbox (one of ses, msgraph)
  • lastError (string): Error of the last import run
  • lastImported (integer): Mails imported by the last run (msgraph) or received in total (ses)
  • lastReceivedAt (string (date-time)): Time of the last received mail
  • lastRunAt (string (date-time)): Time of the last import run (msgraph)
  • name (string): Display name
  • pending (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 address
    • validUntil (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 as rev)
  • updatedAt (string (date-time)): Time of the last change
  • updatedBy (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}'

View as Markdown · Interactive reference · OpenAPI