ConnectCloud Developers

Write a mail: saved as draft, sent with send=true (desk:write, agent role)

POST /api/desk/v1/items/{ref}/mail

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

Sending queues the mail in the transaction that stores the entry; comms sends it from the chosen mailbox (Reply-To with the ticket's tag for SES mailboxes) and reports the delivery. The entry's mail.deliveryState goes queued → sent → delivered (or bounced, failed, suppressed). The first response of the SLA is met when the mail is sent.

Parameters

Name In Type Required Description
ref path string yes Item id or number

Request body

application/json (required)

  • aiGenerated (boolean): The text was written with AI help
  • attachmentIds (array of string): Documents of the ticket
  • bcc (array of Address): Recipients in blind copy
    • address (string): E-mail address
    • name (string): Display name (may be empty)
  • body (string): Markdown
  • cc (array of Address): Recipients in copy
    • address (string): E-mail address
    • name (string): Display name (may be empty)
  • inReplyToEntryId (string): The mail entry of the ticket this mail answers (threading). An internal mail answers only internal mails (422 public_thread). Empty on an existing draft keeps the mail it answers.
  • includeChain (boolean): Add every earlier mail of the ticket the recipients may see (received and sent, public, no automatic answers or failed deliveries) below the text, newest first, Outlook style ("-----Original Message-----", Von, Gesendet, An, Cc, Betreff; never Bcc); at most 100 mails and 200 KB of text, older ones are left out with a note. An internal mail carries only its own thread (the mail it answers and its ancestors). Default true; stored with the mail and kept on a resend.
  • mailboxId (string): Empty uses the default mailbox
  • send (boolean): Send now; false saves a draft
  • signature (boolean): Append the signature (default true)
  • subject (string): Subject
  • to (array of Address): Recipients
    • address (string): E-mail address
    • name (string): Display name (may be empty)
  • visibility (string): internal: an internal mail to third parties (suppliers, …). It is sent, but the entry stays internal and is never shown to customers. It needs explicit recipients, none of them a participant of the ticket (422 recipient_is_participant on the field), its subject carries no [#N] token, its Reply-To an internal tag, and answers to it are stored internal. Empty: public, unless inReplyToEntryId is an internal mail (then internal; public is refused with 422 internal_thread). Saving or sending an existing draft with it empty keeps the draft's kind (internal or not); only an explicit value changes it. Kept on a resend. (one of public, internal)

Example:

{
  "body": "Der Switch ist getauscht, alle Access Points laufen wieder stabil. Bitte geben Sie uns Bescheid, falls Gäste noch Probleme melden.",
  "includeChain": true,
  "send": true,
  "signature": true,
  "subject": "[#1] WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "to": [
    {
      "address": "katrin.stadler@alpenhotel-seeblick.example",
      "name": "Katrin Stadler"
    }
  ],
  "visibility": "public"
}

Responses

  • 201 The entry with its mail (application/json)
  • 422 Internal mail to a participant (recipient_is_participant, field to/cc/bcc), public answer to an internal mail (internal_thread), internal answer to a customer mail (public_thread)
  • 503 Desk sends no mail (code unavailable)

Fields of the 201 answer:

  • aiGenerated (boolean): The text was written with AI help
  • authorKind (string): external: a third party who answered an internal mail (the entry is internal) (one of agent, requester, system, ai, rule, external)
  • authorName (string): Name of the author
  • authorRef (string): Login (e-mail) of the author
  • automated (boolean): Written by a rule or service; never counts as a first response
  • body (string): Markdown
  • channel (string): Where the entry came from (one of ui, mail, portal, api)
  • createdAt (string (date-time)): When the entry was written
  • editedAt (string (date-time)): When the entry was last edited
  • id (string): Id of the entry
  • itemId (string): Item the entry belongs to
  • kind (string): comment, email_in, email_out or system
  • mail (object): Mail of email_in and email_out entries: direction, from, to, cc, subject, deliveryState (draft, queued, sent, delivered, deferred, bounced, failed, suppressed), recipientStates, attachments
    • inReplyToEntryId (string): Outgoing mails: the mail entry of the ticket it answers; a draft keeps it when it is saved or sent without inReplyToEntryId
    • includeChain (boolean): Sent mails: whether the earlier mails of the ticket went out below the text
    • mainText (string): Received mails: the text without quoted history, signature, closing and legal footer; missing when nothing was cut or the entry was edited. body stays the full text.
    • thirdParty (boolean): An internal mail to or from third parties (suppliers, …; sent with visibility internal or answering one). An internal mail without it – a customer mail a merge or move hid – still belongs to the customer's thread.
    • trimMethod (string): How mainText was found: rules on the text, or the AI for a long mail (settings.mail.aiTrim) (one of heuristic, ai)
  • mailNote (string): why no mail was sent for a public comment (work_type: the ticket type has the work focus, comments on it are never mailed) (one of no_mailbox, no_recipient, mail_unavailable, work_type)
  • movedFromId (string): Item the entry was moved from
  • visibility (string): internal: only staff see it; public: the requester sees it too (one of internal, public)

Example 201 answer:

{
  "aiGenerated": false,
  "authorKind": "agent",
  "authorName": "Lukas Wimmer",
  "authorRef": "lukas.wimmer@muster-it.example",
  "automated": false,
  "body": "Controller zeigt AP-207 mit ständigen Neustarts (PoE-Budget am Switch im Technikraum 2. OG überschritten). AP-201 läuft stabil.",
  "channel": "ui",
  "createdAt": "2026-11-17T08:40:00Z",
  "id": "1b8c9d0e-2f3a-4b4c-9d6e-8f9a0b1c2d03",
  "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "kind": "comment",
  "visibility": "internal"
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/mail' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"body":"Der Switch ist getauscht, alle Access Points laufen wieder stabil. Bitte geben Sie uns Bescheid, falls Gäste noch Probleme melden.","includeChain":true,"send":true,"signature":true,"subject":"[#1] WLAN in den Gästezimmern 2. OG fällt immer wieder aus","to":[{"address":"katrin.stadler@alpenhotel-seeblick.example","name":"Katrin Stadler"}],"visibility":"public"}'

View as Markdown · Interactive reference · OpenAPI