Upload a file to the ticket, within the tenant's mail limits (desk:write, agent role)
POST /api/desk/v1/items/{ref}/attachments
Module: Desk · operationId: createItemAttachment · Tag: Mail · Auth: access token (Authorization: Bearer <accessToken>)
The file is stored in DMS and scanned for malware afterwards: until the scan cleared it, its content answers 409 scan_pending, a file the scan found something in 403 infected.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
ref |
path | string | yes | Item id or number |
Request body
multipart/form-data (required)
file(string (binary), required)
Responses
- 201 The stored file (
application/json) - 400 No multipart
filepart, no usable file name, or the file breaks the tenant's mail limits (size, blocked type) – code invalid, field file (application/json) - 403 No desk:write, or not at least the agent role in the ticket's space (code forbidden) (
application/json) - 404 No such ticket, or one the caller does not see (
application/json) - 503 The file store is not configured (code unavailable) (
application/json)
Fields of the 201 answer:
contentId(string): Content-ID of an inline imagecreatedAt(string (date-time)): When the file was addeddocumentId(string): DMS document holding the fileentryId(string): Entry (mail or comment) the file came withid(string): Id of the file recordinline(boolean): An inline image of a mail bodyitemId(string): Item the file belongs tomime(string): MIME typename(string): File nameportalVisible(boolean): Requesters see the file in the customer portalsize(integer): Size in bytessource(string): mail: attachment of a mail; upload: staff upload; portal: requester upload; conversion: brought along by a conversion; eml: the original (.eml) of a received or sent mail (entryId set, never visible to requesters, never handed to forge); generated: made by desk (meeting transcripts) (one ofmail,upload,portal,conversion,eml,generated)uploadedBy(string): Login (e-mail) of who uploaded it
Example 201 answer:
{
"contentId": "",
"createdAt": "2026-11-17T08:41:00Z",
"documentId": "3d0e1f2a-4b5c-4d6e-9f8a-0b1c2d3e4f01",
"entryId": "",
"id": "2c9d0e1f-3a4b-4c5d-8e7f-9a0b1c2d3e01",
"inline": false,
"itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
"mime": "text/plain",
"name": "Controller-Log_AP-207.txt",
"portalVisible": false,
"size": 18233,
"source": "upload",
"uploadedBy": "lukas.wimmer@muster-it.example"
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/attachments' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: multipart/form-data' \
-F 'file=@document.pdf'