## Create a container (tenant:dms:write)

`POST /api/dms/v1/containers`

Module: DMS · operationId: `createContainer` · Tag: Containers · Auth: access token (`Authorization: Bearer <accessToken>`)

Creates a container and adds the given documents as `ATTACHMENT` items in order; an
`emlDocumentId` is added first as `EML` item. Every referenced document must be an existing
document of the tenant (`400` otherwise).

### Request body

`application/json` (required)

- `containerType` (string, required): Upper-cased by the server (max length 64)
- `title` (string, required): Title (max length 255)
- `documentIds` (array of string (uuid)): Added as `ATTACHMENT` items in this order
- `emlDocumentId` (string (uuid)): The original mail; added as `EML` item
- `metadata` (object): Free metadata (JSON object)
- `retentionYears` (integer): Retention period in years (max 100)
- `sourceChannel` (string): Where the container came from, an upper-case code (default `"MANUAL"`)
- `sourceReference` (string): Reference in the source, e.g. a Message-ID

Example:

```json
{
  "containerType": "EMAIL",
  "documentIds": [
    "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42"
  ],
  "emlDocumentId": "2e4a6c8e-0f2a-4b4c-8d6e-8f0a2b4c6d8e",
  "retentionYears": 10,
  "sourceChannel": "MAIL",
  "sourceReference": "\u003c20260930064512.4711@nordlicht-distribution.example\u003e",
  "title": "Rechnung RE-482117 zu Ihrer Bestellung BE-2026-0815"
}
```

### Responses

- **201** The container with its items (`application/json`)
- **400** Error (`application/json`)

Fields of the 201 answer:

- `containerNumber` (string, required): Per-tenant, per-year container number
- `containerType` (string, required): Kind of container, an upper-case code
- `createdAt` (string (date-time), required): Creation time
- `createdBy` (string, required): Who created the container
- `customerNo` (string, required): Customer number of the tenant
- `id` (string (uuid), required): Container id
- `retentionYears` (integer, required): Retention period in years
- `sourceChannel` (string, required): Where the container came from, an upper-case code
- `tenantName` (string, required): Tenant name
- `title` (string, required): Title
- `updatedAt` (string (date-time), required): Time of the last change
- `emlDocumentId` (string (uuid)): The original mail (EML item), if any
- `items` (array of DocumentContainerItem): The documents of the container (detail only)
  - `containerId` (string (uuid), required): Container id
  - `createdAt` (string (date-time), required): Time the document was added
  - `customerNo` (string, required): Customer number of the tenant
  - `documentId` (string (uuid), required): Document id
  - `id` (string (uuid), required): Item id
  - `itemRole` (string, required): `EML`, `ATTACHMENT` or another code
  - `sortOrder` (integer, required): Position in the container
  - `tenantName` (string, required): Tenant name
  - `document` (Document)
    - `confidentialLevel` (ConfidentialLevel, required)
    - `createdAt` (string (date-time), required): Upload time
    - `currentVersion` (integer, required): Current version number
    - `customerNo` (string, required): Customer number of the tenant
    - `documentNumber` (string, required): Per-tenant, per-year document number
    - `extraction` (Extraction, required)
    - `fileName` (string, required): File name of the current version
    - `fileSize` (integer (int64), required): Size of the current version
    - `id` (string (uuid), required): Document id
    - `isArchived` (boolean, required): Same as `isLocked`
    - `isEncrypted` (boolean, required): Content is client-side encrypted
    - `isLocked` (boolean, required): WORM lock (same as `isArchived`)
    - `isPortalVisible` (boolean, required): Visible in the customer portal
    - `legalHold` (boolean, required): A legal hold blocks deletion regardless of retention
    - `mimeType` (string, required): MIME type of the current version
    - `retentionYears` (integer, required): Retention period in years (from the document type)
    - `s3Bucket` (string, required): Storage bucket of the current version
    - `s3Key` (string, required): Storage key of the current version
    - `s3Path` (string, required): Same as `s3Key`
    - `scanStatus` (ScanStatus, required)
    - `sha256Hash` (string, required): Same as `hashSha256` (empty when unknown)
    - `sizeBytes` (integer (int64), required): Size of the current version (same as `fileSize`)
    - `tenantName` (string, required): Tenant name
    - `title` (string, required): Defaults to the file name
    - `updatedAt` (string (date-time), required): Time of the last change
    - `uploadedBy` (string, required): Who uploaded the document
    - `version` (integer, required): Current version number (same as `currentVersion`)
    - `category` (string): Document type code
    - `classificationStatus` (string): Document classifier: type taken over automatically, proposal waiting for review, or chosen by a person; omitted when never classified (one of `classified`, `needs_review`, `confirmed`)
    - `deletedAt` (string (date-time)): Time of the soft delete
    - `encryptionAlgorithm` (string): Only for encrypted documents
    - `folderId` (string (uuid)): Folder the document is filed in; omitted when it has none
    - `folderPath` (array of FolderRef): The folder and its ancestors, top level first (detail only)
    - `hashSha256` (string): SHA-256 (hex) of the current version
    - `links` (array of DocumentLink): Omitted when the document has none
    - `lockRetentionUntil` (string (date-time)): End of the WORM lock
    - `metadata` (object): Free metadata (JSON object)
    - `retentionUntil` (string (date-time)): End of the retention period; deletion is refused before
    - `source` (string): How the document entered the DMS (one of `upload`, `mail`, `internal`, `api`)
    - `versions` (array of DocumentVersion): Only in the detail and after a version upload
- `metadata` (object): Free metadata (JSON object)
- `sourceReference` (string): Reference in the source, e.g. a Message-ID

Example 201 answer:

```json
{
  "containerNumber": "CNT-2026-000007",
  "containerType": "EMAIL",
  "createdAt": "2026-09-30T08:40:12Z",
  "createdBy": "christina.adler@muster-it.example",
  "customerNo": "99999",
  "emlDocumentId": "2e4a6c8e-0f2a-4b4c-8d6e-8f0a2b4c6d8e",
  "id": "0c2e4a6c-8d0e-4f2a-9b4c-6d8e0f2a4b6c",
  "items": [
    {
      "containerId": "0c2e4a6c-8d0e-4f2a-9b4c-6d8e0f2a4b6c",
      "createdAt": "2026-09-30T08:40:12Z",
      "customerNo": "99999",
      "documentId": "2e4a6c8e-0f2a-4b4c-8d6e-8f0a2b4c6d8e",
      "id": "4a6c8e0a-2b4c-4d6e-8f0a-0b2c4d6e8f0a",
      "itemRole": "EML",
      "sortOrder": 0,
      "tenantName": "DEMO"
    },
    {
      "containerId": "0c2e4a6c-8d0e-4f2a-9b4c-6d8e0f2a4b6c",
      "createdAt": "2026-09-30T08:40:12Z",
      "customerNo": "99999",
      "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
      "id": "6c8e0a2c-4d6e-4f8a-9b2c-2d4e6f8a0b2c",
      "itemRole": "ATTACHMENT",
      "sortOrder": 1,
      "tenantName": "DEMO"
    }
  ],
  "metadata": {
    "from": "rechnungen@nordlicht-distribution.example"
  },
  "retentionYears": 10,
  "sourceChannel": "MAIL",
  "sourceReference": "\u003c20260930064512.4711@nordlicht-distribution.example\u003e",
  "tenantName": "DEMO",
  "title": "Rechnung RE-482117 zu Ihrer Bestellung BE-2026-0815",
  "updatedAt": "2026-09-30T08:40:12Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/dms/v1/containers' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"containerType":"EMAIL","documentIds":["3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42"],"emlDocumentId":"2e4a6c8e-0f2a-4b4c-8d6e-8f0a2b4c6d8e","retentionYears":10,"sourceChannel":"MAIL","sourceReference":"\u003c20260930064512.4711@nordlicht-distribution.example\u003e","title":"Rechnung RE-482117 zu Ihrer Bestellung BE-2026-0815"}'
```
