cloudflare_temp_email/vitepress-docs/docs/en/guide/feature/mail-api.md

Mail API

Viewing Emails via Mail API

This is a python example using the requests library to view emails.

limit = 10
offset = 0
res = requests.get(
    f"https://<your-worker-address>/api/mails?limit={limit}&offset={offset}",
    headers={
        "Authorization": f"Bearer {your-JWT-password}",
        # "x-custom-auth": "<your-website-password>", # If private site password is enabled
        "Content-Type": "application/json"
    }
)

Note: /api/mails returns raw RFC822 data by design (for example source/raw), and it does not guarantee parsed fields such as subject, text, or html. Parse the raw source on the client side (for example with mail-parser-wasm or postal-mime) if you need readable message content.

Mail State API

After enabling ENABLE_MAIL_FLAGS and running the database migration, each mail response includes the boolean field unread. The backend owns storage, historical NULL compatibility, and state calculation.

With an Address JWT, use GET /api/mail-states to retrieve available states. The backend combines its system-state enum with address-specific custom states. The frontend uses each returned value directly for filtering and moving, and displays its label_key or label.

Use PATCH /api/mails/state to move the state of up to 100 mail IDs:

requests.patch(
    "https://<your-worker-address>/api/mails/state",
    headers={"Authorization": f"Bearer {your-JWT-password}"},
    json={"ids": [1, 2], "state": "read"}
)

With a User JWT, use GET /user_api/mail-states and PATCH /user_api/mails/state. Only mail belonging to addresses bound to that user can be changed. The response contains the updated unread state.

Mail-list endpoints accept a state value returned by the backend. For example, list unread mail with:

GET /api/mails?limit=20&offset=0&mail_state=unread

/user_api/mails accepts the same parameter. Future custom groups only require the backend to append custom states and resolve their values; clients do not add another enum.

Admin Mail API

Supports address filter

import requests

url = "https://<your-worker-address>/admin/mails"

querystring = {
    "limit":"20",
    "offset":"0",
    # address is optional parameter
    "address":"xxxx@awsl.uk"
}

headers = {
        "x-admin-auth": "<your-Admin-password>",
        # "x-custom-auth": "<your-website-password>", # If private site password is enabled
    }

response = requests.get(url, headers=headers, params=querystring)

print(response.json())

Note: /admin/mails follows the same design as /api/mails: it returns stored raw MIME data. If you need readable subject/body, parse the raw content on the client side.

Note: Keyword filtering has been removed from the backend API. If you need to filter emails by content, please use the frontend filter input in the UI, which filters the currently displayed page.

Admin Get Mail API

Fetch a single mail by mail ID without a mailbox JWT. Authenticate with x-admin-auth. The response matches one entry returned by /admin/mails: gzip-compressed raw content is decompressed into raw, and raw_blob is excluded.

import requests

mail_id = 1
url = f"https://<your-worker-address>/admin/mails/{mail_id}"

headers = {
        "x-admin-auth": "<your-Admin-password>",
        # "x-custom-auth": "<your-website-password>", # If private site password is enabled
    }

response = requests.get(url, headers=headers)

print(response.json())

Admin Delete Mail API

Delete a single mail by mail ID.

import requests

mail_id = 1
url = f"https://<your-worker-address>/admin/mails/{mail_id}"

headers = {
        "x-admin-auth": "<your-Admin-password>",
        # "x-custom-auth": "<your-website-password>", # If private site password is enabled
    }

response = requests.delete(url, headers=headers)

print(response.json())

Admin Delete Address API

Delete an email address by address ID (also deletes associated mails, sender permissions, and user bindings).

import requests

address_id = 1
url = f"https://<your-worker-address>/admin/delete_address/{address_id}"

headers = {
        "x-admin-auth": "<your-Admin-password>",
        # "x-custom-auth": "<your-website-password>", # If private site password is enabled
    }

response = requests.delete(url, headers=headers)

print(response.json())

Admin Clear Inbox API

Clear all received mails for an address by address ID.

import requests

address_id = 1
url = f"https://<your-worker-address>/admin/clear_inbox/{address_id}"

headers = {
        "x-admin-auth": "<your-Admin-password>",
        # "x-custom-auth": "<your-website-password>", # If private site password is enabled
    }

response = requests.delete(url, headers=headers)

print(response.json())

Admin Clear Sent Items API

Clear all sent mails for an address by address ID.

import requests

address_id = 1
url = f"https://<your-worker-address>/admin/clear_sent_items/{address_id}"

headers = {
        "x-admin-auth": "<your-Admin-password>",
        # "x-custom-auth": "<your-website-password>", # If private site password is enabled
    }

response = requests.delete(url, headers=headers)

print(response.json())

User Mail API

::: warning Note: User JWT vs Address JWT This endpoint uses User JWT (obtained via /user_api/login or /user_api/register), with x-user-token header.

Do not confuse with Address JWT:

• Address JWT uses Authorization: Bearer <jwt> to access /api/* endpoints
• User JWT uses x-user-token: <jwt> to access /user_api/* endpoints :::

Bound Address List

GET /user_api/bind_address uses server-side pagination and accepts these query parameters:

Requests without pagination parameters return the default first page. Fetching all bound addresses in one request is not supported.

Parameter	Default	Description
limit	20	Page size, from 1 to 100
offset	0	Pagination offset

The results array contains only the current page. The total is queried only when offset=0; later pages return count: 0, so clients should retain the total from the first page.

import requests

url = "https://<your-worker-address>/user_api/bind_address"
headers = {
    "x-user-token": "<your-user-JWT-token>",
}
querystring = {
    "limit": "20",
    "offset": "0",
}
response = requests.get(url, headers=headers, params=querystring)
print(response.json())

User Mail List

Supports address filter

import requests

url = "https://<your-worker-address>/user_api/mails"

querystring = {
    "limit":"20",
    "offset":"0",
    # address is optional parameter
    "address":"xxxx@awsl.uk"
}

headers = {
        "x-user-token": "<your-user-JWT-token>",
        # "x-custom-auth": "<your-website-password>", # If private site password is enabled
    }

response = requests.get(url, headers=headers, params=querystring)

print(response.json())

Note: /user_api/mails also returns raw RFC822 content from storage; parse it in your client to extract subject, text, and html.

Note: Keyword filtering has been removed from the backend API. If you need to filter emails by content, please use the frontend filter input in the UI, which filters the currently displayed page.