ConnectCloud Developers

Replace the address of a ticket or applicant mailbox (kind ses); the old one is accepted for graceDays (default 14) (comms:admin; desk:admin its ticket mailboxes, hr:recruiting:manage its applicant mailboxes)

POST /api/comms/v1/mailboxes/{id}/rotate

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

Parameters

Name In Type Required Description
id path string yes

Request body

application/json (required)

  • rev (integer, required): Revision the change is based on
  • graceDays (integer): Days the old address stays accepted (default 14; 0 stops it at once) (max 90)
  • localPart (string): Part before the @ of the new address; default the current chosen part (max length 40)
  • randomSuffix (boolean): Adds a new random suffix (default true)

Example:

{
  "graceDays": 14,
  "randomSuffix": true,
  "rev": 5
}

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 POST 'https://api.mbcom.cloud/api/comms/v1/mailboxes/string/rotate' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"graceDays":14,"randomSuffix":true,"rev":5}'

View as Markdown · Interactive reference · OpenAPI