Change the retention settings
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.
apiKeyAuthorizationBearer <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.
application/json- body
mailRetentionDays?|Delete a conversation for good this many days after its last message; null keeps conversations until someone deletes them.
1 <= value <= 3650trashRetentionDays?integerDays a deleted conversation can be brought back (1-365).
1 <= value <= 365deleteConversationsWithMailbox?booleanAlso delete for good the conversations of an inbox that is deleted.
permanentDeleteAllowed?booleanWhether anything may be deleted for good.
legalHold?booleanKeep everything while on.
expectedVersion?integerThe version you read; refused if the settings moved since.
0 <= valueThe settings after the change
application/json- response
settings*sources*version*integer0 <= valuelines*array<string>summary*stringcurl -X PATCH https://api.vlayers.ai/v1/retention \ -H "Authorization: Bearer $VOICELAYER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "trashRetentionDays": 14 }'{ "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."}