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 ongraceDays(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 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 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}'