ConnectCloud Developers

Change a draft; send it with send=true (desk:write, agent role)

PATCH /api/desk/v1/items/{ref}/entries/{entryId}/mail

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

Parameters

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

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": "Ich komme heute um 14 Uhr vorbei und tausche den Switch aus.",
  "send": false,
  "subject": "[#1] WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "to": [
    {
      "address": "katrin.stadler@alpenhotel-seeblick.example",
      "name": "Katrin Stadler"
    }
  ]
}

Responses

  • 200 The entry with its mail (application/json)
  • 400 Invalid, or already sent
  • 422 Internal mail to a participant (recipient_is_participant, field to/cc/bcc), or a thread it may not answer (internal_thread, public_thread)

Fields of the 200 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 200 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 PATCH 'https://api.mbcom.cloud/api/desk/v1/items/string/entries/string/mail' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"body":"Ich komme heute um 14 Uhr vorbei und tausche den Switch aus.","send":false,"subject":"[#1] WLAN in den Gästezimmern 2. OG fällt immer wieder aus","to":[{"address":"katrin.stadler@alpenhotel-seeblick.example","name":"Katrin Stadler"}]}'

View as Markdown · Interactive reference · OpenAPI