ConnectCloud Developers

Let a comms mailbox (consumer desk) feed a space; one source per mailbox (desk:admin)

POST /api/desk/v1/mail-sources

Module: Desk · operationId: createMailSource · Tag: Mail · Auth: access token (Authorization: Bearer <accessToken>)

Request body

application/json (required)

  • defaultSpaceId (string, required): Space of tickets no route matched
  • mailboxId (string, required): Mailbox id in comms
  • aiRouting (object): When no route matches, the AI chooses the space of a new ticket among the candidates (described in the admin's words); below the threshold, or when nothing fits, the default space is used.
    • candidates (array of object): Spaces the AI may choose
      • description (string, required): What belongs in the space, in the admin's words (max length 500)
      • spaceId (string, required): Space the AI may choose
      • typeId (string): Type of tickets created there
    • enabled (boolean): The AI chooses the space when no route matched
    • threshold (number): Default 0.7 (max 1)
  • defaultTypeId (string, nullable): Empty uses the space''s default type
  • enabled (boolean): Whether the mailbox feeds desk
  • id (string, read-only): Id of the mail source
  • name (string): Name of the mail source
  • replyEnabled (boolean): Agents may answer by mail through this mailbox
  • routes (array of object): Routes in order; the first matching one decides space and type
    • condition (string, required): When the route takes a mail: a bool expression in the flow language over trigger.data, the facts of the received mail (from, fromDomain, to, subject, body, hasAttachments, mailbox; GET /conditions/catalog, mail). Required. One that cannot be evaluated for a mail does not hold (the next route, at last the default space). (max length 4000)
    • spaceId (string, required): Space of the route's tickets
    • name (string): Name of the route
    • typeId (string): Type of the route's tickets (default: the space's)
  • updatedAt (string (date-time), read-only): When it was last changed
  • updatedBy (string, read-only): Login (e-mail) of who last changed it
  • version (integer): Version of the mail source; send it back on change

Example:

{
  "defaultSpaceId": "SUP",
  "defaultTypeId": "serviceanfrage",
  "enabled": true,
  "mailboxId": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b01",
  "name": "support@muster-it.example",
  "replyEnabled": true,
  "routes": [
    {
      "condition": "trigger.data.subject contains \"Störung\"",
      "name": "Störungsmeldungen",
      "spaceId": "SUP",
      "typeId": "stoerung"
    }
  ]
}

Responses

  • 201 Created (application/json)
  • 409 The mailbox already feeds desk

Fields of the 201 answer:

  • defaultSpaceId (string, required): Space of tickets no route matched
  • mailboxId (string, required): Mailbox id in comms
  • aiRouting (object): When no route matches, the AI chooses the space of a new ticket among the candidates (described in the admin's words); below the threshold, or when nothing fits, the default space is used.
    • candidates (array of object): Spaces the AI may choose
      • description (string, required): What belongs in the space, in the admin's words (max length 500)
      • spaceId (string, required): Space the AI may choose
      • typeId (string): Type of tickets created there
    • enabled (boolean): The AI chooses the space when no route matched
    • threshold (number): Default 0.7 (max 1)
  • defaultTypeId (string, nullable): Empty uses the space''s default type
  • enabled (boolean): Whether the mailbox feeds desk
  • id (string, read-only): Id of the mail source
  • name (string): Name of the mail source
  • replyEnabled (boolean): Agents may answer by mail through this mailbox
  • routes (array of object): Routes in order; the first matching one decides space and type
    • condition (string, required): When the route takes a mail: a bool expression in the flow language over trigger.data, the facts of the received mail (from, fromDomain, to, subject, body, hasAttachments, mailbox; GET /conditions/catalog, mail). Required. One that cannot be evaluated for a mail does not hold (the next route, at last the default space). (max length 4000)
    • spaceId (string, required): Space of the route's tickets
    • name (string): Name of the route
    • typeId (string): Type of the route's tickets (default: the space's)
  • updatedAt (string (date-time), read-only): When it was last changed
  • updatedBy (string, read-only): Login (e-mail) of who last changed it
  • version (integer): Version of the mail source; send it back on change

Example 201 answer:

{
  "aiRouting": {
    "candidates": [],
    "enabled": false,
    "threshold": 0.8
  },
  "defaultSpaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "defaultTypeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f02",
  "enabled": true,
  "id": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b11",
  "mailboxId": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b01",
  "name": "support@muster-it.example",
  "replyEnabled": true,
  "routes": [
    {
      "condition": "trigger.data.subject contains \"Störung\" || trigger.data.subject contains \"geht nicht\"",
      "name": "Störungsmeldungen",
      "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
      "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01"
    }
  ],
  "updatedAt": "2026-10-20T13:40:00Z",
  "updatedBy": "elias.gruber@muster-it.example",
  "version": 3
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/desk/v1/mail-sources' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"defaultSpaceId":"SUP","defaultTypeId":"serviceanfrage","enabled":true,"mailboxId":"3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b01","name":"support@muster-it.example","replyEnabled":true,"routes":[{"condition":"trigger.data.subject contains \"Störung\"","name":"Störungsmeldungen","spaceId":"SUP","typeId":"stoerung"}]}'

View as Markdown · Interactive reference · OpenAPI