> ## Documentation Index
> Fetch the complete documentation index at: https://pigeonpost-developer.27communication.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Read, star, move and trash

> Change an email in the user's mailbox.

Changes are made **at the provider**, so the user sees them in Gmail or their email app too.

## Mark as read, star, move

```bash theme={null}
curl -X PATCH "$EE_URL/api/v1/emails/email_94a0d77db739407e932c3b97fef44aac" \
  -H "X-API-KEY: $EE_KEY" -H "Content-Type: application/json" \
  -d '{ "unread": false, "starred": true, "folder": "ARCHIVE" }'
```

Send only what you want to change.

<ParamField body="unread" type="boolean">`false` marks it read, `true` unread.</ParamField>
<ParamField body="starred" type="boolean">Flag (IMAP) or star (Gmail).</ParamField>

<ParamField body="folder" type="string">
  Move to a folder: its `fld_…` id, provider id, or a role such as `ARCHIVE`, `INBOX`, `SPAM`. For Gmail (IMAP), moving to a label folder adds that label and removes the one it came from; Gmail has no `ARCHIVE` folder over IMAP.
</ParamField>

The response is the updated [email object](/emails/retrieve). The email keeps its `id` when it moves. An `email.update` event follows, with the updated email.

## Move to trash

```bash theme={null}
curl -X DELETE "$EE_URL/api/v1/emails/email_94a0d77db739407e932c3b97fef44aac" -H "X-API-KEY: $EE_KEY"
```

```json Response theme={null}
{ "object": "EmailDeleted", "id": "email_94a0d77db739407e932c3b97fef44aac" }
```

The email goes to the mailbox's Trash: its `role` becomes `TRASH`, and an `email.update` event follows. The email stays in the API while it's in Trash. The provider empties the trash on its own schedule (Gmail after 30 days). When it's gone for good, you receive `email.delete`.

## Changes made elsewhere

When the user reads, stars, moves or deletes an email in their own email app, the engine picks it up on the next sync and sends the same events: `email.update` for a change or a move, `email.delete` when it's deleted for good.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.