Move messages
Moves a batch of messages from one folder to another.
Permission
The key must be granted mail.messages.write
A key without it gets 403 insufficient_scope, with the missing permission named in details.
Path parameters
| Field | Type | Description |
|---|---|---|
folder_id required |
string | Where the messages are now. |
Request body
| Field | Type | Description |
|---|---|---|
message_ids required |
string[] | The messages to move. |
to_folder_id required |
string | Where they are going. |
Request
curl https://api.veruapis.com/v1/folders/:folder_id/messages/move \
-X POST \
-H "Authorization: Bearer vak_live_..." \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"message_ids": ["d9038c5a-3bca-4e27-a016-4b7ad1416948"],
"to_folder_id": "43e01b3d-8560-475f-93e9-c8ce9ddbf1f2"
}'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
{
"data": { "moved": 1, "to_folder_id": "43e01b3d-8560-475f-93e9-c8ce9ddbf1f2" },
"meta": { "request_id": "req_01j8z9...", "timestamp": "2026-09-02T10:00:00Z" }
}Folder-scoped and plural, because the messages are addressed within the folder that currently holds them. The folder in the path is where they are now; to_folder_id is where they are going.
Every failure uses the same shape, with a stable string code you can branch on. See the error reference.
Related
- POST Create a draft
- POST Create a mail filter
- POST Create a mail folder
- DELETE Delete a draft
- DELETE Delete a mail filter
- DELETE Delete a mail folder
- DELETE Delete a message
- GET Download an attachment
- GET Get a message
- GET Get display preferences
- GET List attachments
- GET List drafts
- GET List mail filters
- GET List mail folders
- GET List messages
- PUT Replace a draft
- POST Send an email
- POST Change flags and labels
- PATCH Rename a mail folder
- PATCH Update display preferences