/api/public/v1/emails/{emailId}Update an email
Marks a message read or unread, stars it, or moves it to a folder. `folder` is the whole filing system: `null` puts it back in its natural place, `archive`, `junk` and `trash` are the system folders, and any other value is a custom folder id. **Deleting mail is moving it to `trash`** — there is no destructive delete here. Mail stays in `trash` for 30 days, then it is deleted for good, attachments and all; moving it anywhere else before then restores it.
Required scope
The access token must carry this scope. A token missing it gets 403 Forbidden. Grant them to an API client under Dev Tools → API, to an assistant or CLI sign-in when you approve or edit it under Dev Tools, and to a teammate under Employee → Permissions.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
emailId | string | Required | Email ID. |
Request Body
| Property | Type | Description |
|---|---|---|
unread | boolean | |
starred | boolean | |
folder | string | null, `archive`, `junk`, `trash`, or a custom folder id. |
curl -X PATCH "https://www.pxb.app/api/public/v1/emails/{emailId}" \
-H "Authorization: Bearer your_access_token" \
-H "Content-Type: application/json" \
-d '{
"folder": "archive",
"unread": false
}'{
"message": "Email updated successfully!",
"content": {
"email": {
"id": "eml_3390",
"threadId": "eml_3390",
"from": "sam@acme.example",
"to": "ap@northwind.example",
"cc": null,
"subject": "Invoice 1042",
"snippet": "Attached is the invoice for phase one. Let me know if purchasing needs anything else.",
"direction": "OUTBOUND",
"unread": false,
"starred": false,
"folder": "archive",
"accountId": "acc_7712",
"hasAttachments": true,
"attachments": [
{
"id": "eat_19",
"fileName": "invoice-1042.pdf",
"contentType": "application/pdf",
"fileSize": 84210
}
],
"receivedAt": "2026-08-22T15:04:00.000Z",
"createdAt": "2026-08-22T15:04:00.000Z",
"updatedAt": "2026-08-22T15:04:00.000Z",
"text": "Attached is the invoice for phase one. Let me know if purchasing needs anything else."
}
}
}In the console
The same thing done by hand, for anyone comparing the API against the screen they already use.