mirror of
https://github.com/mailcow/mailcow-dockerized.git
synced 2026-11-08 02:07:07 +00:00
[Web][Dovecot] Add retention rules: nightly deletion of mail by folder and age for domains, groups and mailboxes
This commit is contained in:
36 files changed
+3013
-16
No files matched your search
@@ -1486,6 +1486,117 @@ paths:
|
||||
type: boolean
|
||||
type: object
|
||||
summary: Create mail policy
|
||||
/api/v1/add/retention-rule:
|
||||
post:
|
||||
responses:
|
||||
"401":
|
||||
$ref: "#/components/responses/Unauthorized"
|
||||
"200":
|
||||
content:
|
||||
application/json:
|
||||
examples:
|
||||
response:
|
||||
value:
|
||||
- log:
|
||||
- retention
|
||||
- add
|
||||
- rule
|
||||
- domain: example.org
|
||||
name: Trash
|
||||
folders:
|
||||
- trash
|
||||
days: 30
|
||||
msg:
|
||||
- retention_rule_added
|
||||
- Trash
|
||||
type: success
|
||||
schema:
|
||||
properties:
|
||||
log:
|
||||
description: contains request object
|
||||
items: {}
|
||||
type: array
|
||||
msg:
|
||||
items: {}
|
||||
type: array
|
||||
type:
|
||||
enum:
|
||||
- success
|
||||
- danger
|
||||
- warning
|
||||
- error
|
||||
type: string
|
||||
type: object
|
||||
description: OK
|
||||
headers: {}
|
||||
tags:
|
||||
- Retention rules
|
||||
description: >-
|
||||
Create a retention rule (admins; domain admins with the "retention" ACL
|
||||
for their domains). Every night mail is deleted from the folders of the
|
||||
rule once it was saved there more than "days" days ago. If several
|
||||
rules apply to the same folder of a mailbox, the most specific one
|
||||
wins, per folder: mailbox before group before domain, then the folder
|
||||
itself (special folder, inbox, own name) before an own name with *,
|
||||
before the subfolders of a special folder or the inbox, before all
|
||||
folders, then the longer period. New rules simulate by default. Rules
|
||||
of inactive domains do not run.
|
||||
operationId: Create retention rule
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
example:
|
||||
domain: example.org
|
||||
name: Trash
|
||||
folders:
|
||||
- trash
|
||||
- junk
|
||||
days: 30
|
||||
keep_flagged: "1"
|
||||
mode: simulate
|
||||
all_mailboxes: "1"
|
||||
active: "1"
|
||||
properties:
|
||||
domain:
|
||||
description: domain of the rule (required)
|
||||
type: string
|
||||
name:
|
||||
description: unique per domain, max. 100 characters
|
||||
type: string
|
||||
description:
|
||||
description: max. 255 characters
|
||||
type: string
|
||||
folders:
|
||||
description: trash, junk, sent, drafts, archive, inbox (each with its subfolders), all (folders no other rule decides about) and folder:<name> (exactly this own folder, / for subfolders, * as wildcard), max. 50; replaces the list
|
||||
type: array
|
||||
own_folders:
|
||||
description: own folder names, one per line or as a list, replacing the folder:<name> entries (the UI sends them apart)
|
||||
oneOf:
|
||||
- type: string
|
||||
- type: array
|
||||
days:
|
||||
description: delete mail saved in the folder more than this many days ago, 1 to 36500
|
||||
type: number
|
||||
keep_flagged:
|
||||
description: flagged mail stays
|
||||
type: boolean
|
||||
mode:
|
||||
description: simulate (the nightly run only counts, default) or delete
|
||||
type: string
|
||||
all_mailboxes:
|
||||
description: applies to all mailboxes of the domain
|
||||
type: boolean
|
||||
mailboxes:
|
||||
description: mailboxes of the domain the rule applies to (replaces the list), max. 500
|
||||
type: array
|
||||
groups:
|
||||
description: group IDs of the domain (their members of that domain), max. 500; domain admins need the mailbox_groups ACL, without it the groups stay unchanged
|
||||
type: array
|
||||
active:
|
||||
type: boolean
|
||||
type: object
|
||||
summary: Create retention rule
|
||||
/api/v1/add/oauth2-client:
|
||||
post:
|
||||
responses:
|
||||
@@ -3018,6 +3129,63 @@ paths:
|
||||
type: object
|
||||
type: object
|
||||
summary: Delete mail policies
|
||||
/api/v1/delete/retention-rule:
|
||||
post:
|
||||
responses:
|
||||
"401":
|
||||
$ref: "#/components/responses/Unauthorized"
|
||||
"200":
|
||||
content:
|
||||
application/json:
|
||||
examples:
|
||||
response:
|
||||
value:
|
||||
- log:
|
||||
- retention
|
||||
- delete
|
||||
- rule
|
||||
- id:
|
||||
- "3"
|
||||
msg:
|
||||
- retention_rule_removed
|
||||
- Trash
|
||||
type: success
|
||||
schema:
|
||||
properties:
|
||||
log:
|
||||
description: contains request object
|
||||
items: {}
|
||||
type: array
|
||||
msg:
|
||||
items: {}
|
||||
type: array
|
||||
type:
|
||||
enum:
|
||||
- success
|
||||
- danger
|
||||
- warning
|
||||
- error
|
||||
type: string
|
||||
type: object
|
||||
description: OK
|
||||
headers: {}
|
||||
tags:
|
||||
- Retention rules
|
||||
description: >-
|
||||
Delete retention rules by ID.
|
||||
operationId: Delete retention rules
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
example:
|
||||
- "3"
|
||||
properties:
|
||||
items:
|
||||
description: contains list of rule IDs you want to delete
|
||||
type: object
|
||||
type: object
|
||||
summary: Delete retention rules
|
||||
/api/v1/delete/identity-link:
|
||||
post:
|
||||
responses:
|
||||
@@ -4762,6 +4930,105 @@ paths:
|
||||
type: object
|
||||
type: object
|
||||
summary: Update mail policies
|
||||
/api/v1/edit/retention-rule:
|
||||
post:
|
||||
responses:
|
||||
"401":
|
||||
$ref: "#/components/responses/Unauthorized"
|
||||
"200":
|
||||
content:
|
||||
application/json:
|
||||
examples:
|
||||
response:
|
||||
value:
|
||||
- log:
|
||||
- retention
|
||||
- edit
|
||||
- rule
|
||||
- id:
|
||||
- "3"
|
||||
mode: delete
|
||||
msg:
|
||||
- retention_rule_modified
|
||||
- Trash
|
||||
type: success
|
||||
schema:
|
||||
properties:
|
||||
log:
|
||||
description: contains request object
|
||||
items: {}
|
||||
type: array
|
||||
msg:
|
||||
items: {}
|
||||
type: array
|
||||
type:
|
||||
enum:
|
||||
- success
|
||||
- danger
|
||||
- warning
|
||||
- error
|
||||
type: string
|
||||
type: object
|
||||
description: OK
|
||||
headers: {}
|
||||
tags:
|
||||
- Retention rules
|
||||
description: >-
|
||||
Update retention rules. Attributes you do not send keep their value.
|
||||
The domain cannot be changed.
|
||||
operationId: Update retention rules
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
example:
|
||||
items:
|
||||
- "3"
|
||||
attr:
|
||||
mode: delete
|
||||
properties:
|
||||
attr:
|
||||
properties:
|
||||
name:
|
||||
description: unique per domain, max. 100 characters
|
||||
type: string
|
||||
description:
|
||||
description: max. 255 characters
|
||||
type: string
|
||||
folders:
|
||||
description: trash, junk, sent, drafts, archive, inbox (each with its subfolders), all (folders no other rule decides about) and folder:<name> (exactly this own folder, / for subfolders, * as wildcard), max. 50; replaces the list
|
||||
type: array
|
||||
own_folders:
|
||||
description: own folder names, one per line or as a list, replacing the folder:<name> entries (the UI sends them apart)
|
||||
oneOf:
|
||||
- type: string
|
||||
- type: array
|
||||
days:
|
||||
description: delete mail saved in the folder more than this many days ago, 1 to 36500
|
||||
type: number
|
||||
keep_flagged:
|
||||
description: flagged mail stays
|
||||
type: boolean
|
||||
mode:
|
||||
description: simulate (the nightly run only counts, default) or delete
|
||||
type: string
|
||||
all_mailboxes:
|
||||
description: applies to all mailboxes of the domain
|
||||
type: boolean
|
||||
mailboxes:
|
||||
description: mailboxes of the domain the rule applies to (replaces the list), max. 500
|
||||
type: array
|
||||
groups:
|
||||
description: group IDs of the domain (their members of that domain), max. 500; domain admins need the mailbox_groups ACL, without it the groups stay unchanged
|
||||
type: array
|
||||
active:
|
||||
type: boolean
|
||||
type: object
|
||||
items:
|
||||
description: contains list of rule IDs you want to update
|
||||
type: object
|
||||
type: object
|
||||
summary: Update retention rules
|
||||
/api/v1/edit/identity-provider-sync:
|
||||
post:
|
||||
responses:
|
||||
@@ -6492,6 +6759,70 @@ paths:
|
||||
the end of the api url.
|
||||
operationId: Get SOGo logs
|
||||
summary: Get SOGo logs
|
||||
"/api/v1/get/logs/retention/{count}":
|
||||
get:
|
||||
parameters:
|
||||
- description: Number of logs to return (default 1000)
|
||||
in: path
|
||||
name: count
|
||||
required: true
|
||||
schema:
|
||||
type: number
|
||||
- description: e.g. api-key-string
|
||||
example: api-key-string
|
||||
in: header
|
||||
name: X-API-Key
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
"401":
|
||||
$ref: "#/components/responses/Unauthorized"
|
||||
"200":
|
||||
content:
|
||||
application/json:
|
||||
examples:
|
||||
response:
|
||||
value:
|
||||
- time: "1794368412"
|
||||
domain: example.org
|
||||
username: user@example.org
|
||||
rule_id: 3
|
||||
rule_name: Trash
|
||||
folder: "Trash\nTrash/Old"
|
||||
days: 30
|
||||
mailboxes: 0
|
||||
matched: 12
|
||||
deleted: 12
|
||||
errors: 0
|
||||
simulated: 0
|
||||
error: null
|
||||
- time: "1794368400"
|
||||
domain: ""
|
||||
username: ""
|
||||
rule_id: null
|
||||
rule_name: ""
|
||||
folder: null
|
||||
days: 0
|
||||
mailboxes: 120
|
||||
matched: 4211
|
||||
deleted: 312
|
||||
errors: 0
|
||||
simulated: 0
|
||||
error: null
|
||||
description: OK
|
||||
headers: {}
|
||||
tags:
|
||||
- Logs
|
||||
description: >-
|
||||
Results of the nightly retention runs of the last 90 days, newest
|
||||
first: mailboxes with found mail or an error, per mailbox and rule
|
||||
(folder: the folder names separated by line breaks); of simulating
|
||||
rules only the last run. Admins see all domains and one row per run
|
||||
(rule_id null, username empty, error if the run failed), domain admins
|
||||
with the "retention" ACL their domains.
|
||||
operationId: Get retention logs
|
||||
summary: Get retention logs
|
||||
"/api/v1/get/logs/watchdog/{count}":
|
||||
get:
|
||||
parameters:
|
||||
@@ -6821,6 +7152,111 @@ paths:
|
||||
input.
|
||||
operationId: Test mail policies
|
||||
summary: Test mail policies
|
||||
"/api/v1/get/retention-rule/{id}":
|
||||
get:
|
||||
parameters:
|
||||
- description: id of the rule, or "all" (optionally followed by /domain1,domain2)
|
||||
example: all
|
||||
in: path
|
||||
name: id
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
"401":
|
||||
$ref: "#/components/responses/Unauthorized"
|
||||
"200":
|
||||
content:
|
||||
application/json:
|
||||
examples:
|
||||
response:
|
||||
value:
|
||||
- id: 3
|
||||
domain: example.org
|
||||
name: Trash
|
||||
description: ""
|
||||
folders:
|
||||
- trash
|
||||
days: 30
|
||||
keep_flagged: 0
|
||||
mode: delete
|
||||
all_mailboxes: 1
|
||||
active: 1
|
||||
mailboxes: []
|
||||
groups: []
|
||||
created: "2026-11-07 12:00:00"
|
||||
modified: null
|
||||
can_edit: 1
|
||||
last_run:
|
||||
created: "2026-11-08 03:30:12"
|
||||
mailboxes: 120
|
||||
matched: 4211
|
||||
deleted: 4211
|
||||
errors: 0
|
||||
simulated: 0
|
||||
description: OK
|
||||
headers: {}
|
||||
tags:
|
||||
- Retention rules
|
||||
description: >-
|
||||
Retention rules visible to the caller (admins all, domain admins with
|
||||
the "retention" ACL their domains), with the summary of their last
|
||||
nightly run (null = not run yet).
|
||||
operationId: Get retention rules
|
||||
summary: Get retention rules
|
||||
"/api/v1/get/retention-rule/effective/{username}":
|
||||
get:
|
||||
parameters:
|
||||
- description: mailbox
|
||||
example: user@example.org
|
||||
in: path
|
||||
name: username
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
"401":
|
||||
$ref: "#/components/responses/Unauthorized"
|
||||
"200":
|
||||
content:
|
||||
application/json:
|
||||
examples:
|
||||
response:
|
||||
value:
|
||||
- folder: trash
|
||||
match: folder
|
||||
days: 30
|
||||
keep_flagged: 0
|
||||
mode: delete
|
||||
rule_id: 3
|
||||
rule_name: Trash
|
||||
- folder: trash
|
||||
match: subfolders
|
||||
days: 30
|
||||
keep_flagged: 0
|
||||
mode: delete
|
||||
rule_id: 3
|
||||
rule_name: Trash
|
||||
- folder: all
|
||||
match: all
|
||||
days: 365
|
||||
keep_flagged: 1
|
||||
mode: simulate
|
||||
rule_id: 4
|
||||
rule_name: One year
|
||||
description: OK
|
||||
headers: {}
|
||||
tags:
|
||||
- Retention rules
|
||||
description: >-
|
||||
What the rules delete in a mailbox, in order of "most specific wins":
|
||||
each folder of the mailbox goes to the first entry that matches it.
|
||||
match: folder (the folder itself), pattern (own name with *),
|
||||
subfolders (of a special folder or the inbox), all. Mailbox users ask for their own
|
||||
mailbox, admins and domain admins with the "retention" ACL for
|
||||
mailboxes they manage.
|
||||
operationId: Get effective retention rules
|
||||
summary: Get effective retention rules
|
||||
/api/v1/get/identity-provider/sync-status:
|
||||
get:
|
||||
responses:
|
||||
@@ -8379,6 +8815,8 @@ tags:
|
||||
description: Mailbox groups (distribution lists, send-as rights, templates)
|
||||
- name: Mail policies
|
||||
description: Whom mailboxes and groups may send to and receive from
|
||||
- name: Retention rules
|
||||
description: Delete mail from folders after a number of days
|
||||
- name: Routing
|
||||
description: Define your own email routes
|
||||
- name: Resources
|
||||
|
||||
Reference in new issue
Block a user