Change the retention settings

PATCH
/v1/retention

Changes any of the retention settings. Turning on mailRetentionDays, turning on deleteConversationsWithMailbox or shortening trashRetentionDays makes the daily clean-up delete conversations for good, so a key needs the permission to delete for good as well as to change retention. legalHold: true stops every permanent delete, whoever asks. Pass expectedVersion to refuse the change if someone changed the settings since you read them. Every change is recorded.

Requires an API key with the retention:manage scope.

Authorization

apiKey
headerAuthorizationBearer <token>

A secret API key from the dashboard (Developers → API keys): vl_live_…, or vl_test_… for test mode. Each operation says which scope the key needs.

Request Body

application/json
  1. body
mailRetentionDays?|

Delete a conversation for good this many days after its last message; null keeps conversations until someone deletes them.

Range1 <= value <= 3650
trashRetentionDays?integer

Days a deleted conversation can be brought back (1-365).

Range1 <= value <= 365
deleteConversationsWithMailbox?boolean

Also delete for good the conversations of an inbox that is deleted.

permanentDeleteAllowed?boolean

Whether anything may be deleted for good.

legalHold?boolean

Keep everything while on.

expectedVersion?integer

The version you read; refused if the settings moved since.

Range0 <= value

Response Body

The settings after the change

application/json
  1. response
settings*
sources*
version*integer
Range0 <= value
lines*array<string>
summary*string
Example Request
curl -X PATCH https://api.vlayers.ai/v1/retention \  -H "Authorization: Bearer $VOICELAYER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "trashRetentionDays": 14  }'
Example Response
{  "settings": {    "mailRetentionDays": null,    "trashRetentionDays": 14,    "deleteConversationsWithMailbox": false,    "permanentDeleteAllowed": true,    "legalHold": false  },  "sources": {    "mailRetentionDays": "platform",    "trashRetentionDays": "workspace",    "deleteConversationsWithMailbox": "platform",    "permanentDeleteAllowed": "platform",    "legalHold": "platform"  },  "version": 1,  "lines": [    "Conversations are kept until someone deletes them.",    "A deleted conversation can be brought back for 14 days.",    "Deleting an inbox keeps its conversations.",    "Conversations may be deleted for good.",    "No legal hold: nothing is blocking a permanent delete."  ],  "summary": "The trash now holds a deleted conversation for 14 days."}