Create a mail filter

Adds a rule applied to incoming mail.

POST /v1/mail/filters

Permission

The key must be granted mail.settings.write

A key without it gets 403 insufficient_scope, with the missing permission named in details.

Rules run in priority order, lowest first, and every matching rule contributes. discard wins if any rule sets it; move takes the folder from the last matching rule that names one; flag actions accumulate.

Request body

Field	Type	Description
`name` required	string	A label for you, not used in matching.
`priority` required	integer	Lower numbers run first.
`enabled`	boolean	Defaults to `true`
`rule` required	object	What to match, and what to do about it. Its fields are below.

The rule

Field	Type	Description
`match`	string	all requires every condition; any requires one. `allany` Defaults to `all`
`conditions` required	object[]	What to test. At least one. Its fields are below.
`actions` required	object[]	What to do when it matches. At least one. Its fields are below.

Each item in conditions

Field	Type	Description
`field` required	string	Or header:<name>, for example header:list-id. `fromtoccsubjectbody`
`op` required	string	Matching ignores case. regex is reserved and refused. `containsequalsstarts_withends_with`
`value` required	string	What to look for.

Each item in actions

Field	Type	Description
`type` required	string	`moveset_flagmark_readmark_unreaddiscard`
`folder`	string	Required for move. The folder is created if it does not exist.
`flag`	string	Required for set_flag.

Request

curl https://api.veruapis.com/v1/mail/filters \
  -X POST \
  -H "Authorization: Bearer vak_live_..." \
  -H "Idempotency-Key: $(uuidgen)"

Idempotency-Key is required on every write. Retrying with the same key returns the original response rather than repeating the operation, so a timeout is something you retry rather than something you investigate.

Response

Answers 201.

{
  "data": { ... },
  "meta": { "request_id": "req_01j8z9...", "timestamp": "2026-09-02T10:00:00Z" }
}

A worked example for this endpoint has not been written yet.

Errors

Every failure uses the same shape, with a stable string code you can branch on. See the error reference.

POST `/v1/mail/filters`

Your API key Used once, never stored.