ConnectCloud Developers

Change name, switch, address and folders of a mailbox at its revision (comms:admin; desk:admin its ticket mailboxes, hr:recruiting:manage its applicant mailboxes; Microsoft 365 mailboxes only comms:admin)

PUT /api/comms/v1/mailboxes/{id}

Module: Comms · operationId: updateMailbox · Tag: Mailboxes · Auth: access token (Authorization: Bearer <accessToken>)

An empty address keeps the stored one (kind msgraph); kind and consumer cannot change.

Parameters

Name In Type Required Description
id path string yes

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

  • 200 Mailbox (application/json)
  • 400 Error (application/json)
  • 403 Error (application/json)
  • 404 Error (application/json)
  • 409 Error (application/json)

Fields of the 200 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 200 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 PUT 'https://api.mbcom.cloud/api/comms/v1/mailboxes/string' \
  -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