### Get Available Domains API Response

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Example response listing the available domains for email addresses.

```json
["example.com", "mail.example.com"]

```

--------------------------------

### Get Mailboxes List API Response

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Example response for the list of mailboxes associated with the current user, including details like address, creation date, and status.

```json
[
  {
    "id": 1,
    "address": "test@example.com",
    "created_at": "2024-01-01 00:00:00",
    "is_pinned": 1,
    "password_is_default": 1,
    "can_login": 0,
    "forward_to": "backup@gmail.com",
    "is_favorite": 1
  }
]

```

--------------------------------

### Curl Examples for Root Admin Override Token

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Demonstrates how to use the root admin override token with different HTTP headers and query parameters for authentication.

```bash
curl -H "Authorization: Bearer <JWT_TOKEN>" https://your.domain/api/mailboxes

```

```bash
curl -H "X-Admin-Token: <JWT_TOKEN>" https://your.domain/api/domains

```

```bash
curl "https://your.domain/api/session?admin_token=<JWT_TOKEN>"

```

--------------------------------

### Get User List

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Retrieves a list of users with pagination and sorting options. Requires strictAdmin privileges.

```json
[
  {
    "id": 1,
    "username": "testuser",
    "role": "user",
    "mailbox_limit": 10,
    "can_send": 0,
    "mailbox_count": 3,
    "created_at": "2024-01-01 00:00:00"
  }
]
```

--------------------------------

### User Login API Response

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Example response upon successful user login, indicating authentication status and user role.

```json
{
  "success": true,
  "role": "admin",
  "can_send": 1,
  "mailbox_limit": 9999
}

```

--------------------------------

### Wrangler Configuration - Mail Forwarding Rules

Source: https://context7.com/fiz2z/mailfree/llms.txt

Examples for configuring mail forwarding rules based on email prefixes using key-value pairs, JSON format, or disabling forwarding.

```bash
# 键值对格式
FORWARD_RULES="vip=admin@company.com,news=newsletter@company.com,*=fallback@company.com"
```

```bash
# JSON 格式
FORWARD_RULES='[
  {"prefix":"vip","email":"admin@company.com"},
  {"prefix":"news","email":"newsletter@company.com"},
  {"prefix":"*","email":"fallback@company.com"}
]'
```

```bash
# 禁用转发
FORWARD_RULES="disabled"
```

--------------------------------

### Wrangler Configuration - Environment Variables

Source: https://context7.com/fiz2z/mailfree/llms.txt

Example configuration for essential environment variables in wrangler.toml, including mail domains, admin credentials, JWT secret, D1 database binding, and R2 bucket binding.

```toml
# wrangler.toml 配置示例

[vars]
MAIL_DOMAIN = "mail.example.com, temp.example.org"  # 多域名用逗号分隔
ADMIN_PASSWORD = "your_secure_admin_password"
ADMIN_NAME = "admin"  # 可选，默认 admin
JWT_TOKEN = "your_jwt_secret_key"

# D1 数据库绑定
[[d1_databases]]
binding = "TEMP_MAIL_DB"
database_name = "freemail"
database_id = "your-d1-database-id"

# R2 存储桶绑定
[[r2_buckets]]
binding = "MAIL_EML"
bucket_name = "mail-eml"
```

--------------------------------

### Wrangler Configuration - Resend API Key

Source: https://context7.com/fiz2z/mailfree/llms.txt

Configuration examples for Resend API keys in Wrangler, supporting single key, key-value pairs for multiple domains, and JSON format.

```bash
# 单密钥（所有域名使用相同密钥）
wrangler secret put RESEND_API_KEY
# 输入: re_xxxxxxxxxxxxxxxxxxxxxxxx
```

```bash
# 键值对格式（不同域名使用不同密钥）
# RESEND_API_KEY="domain1.com=re_key1,domain2.com=re_key2"
```

```bash
# JSON 格式
# RESEND_API_KEY='{"domain1.com":"re_key1","domain2.com":"re_key2"}'
```

--------------------------------

### GET /api/domains

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Retrieves a list of available domains that can be used for creating email addresses.

```APIDOC
## GET /api/domains

### Description
Retrieves a list of available domains.

### Method
GET

### Endpoint
/api/domains

### Response
#### Success Response (200)
- An array of strings, where each string is a domain name.

#### Response Example
```json
["example.com", "mail.example.com"]
```
```

--------------------------------

### GET /api/session

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Verifies the current user's session status and returns authentication details.

```APIDOC
## GET /api/session

### Description
Verifies the current session status.

### Method
GET

### Endpoint
/api/session

### Response
#### Success Response (200)
- **authenticated** (boolean) - Whether the user is authenticated.
- **role** (string) - The user's role.
- **username** (string) - The username of the authenticated user.
- **strictAdmin** (boolean) - Whether the user has strict admin privileges.

#### Response Example
```json
{
  "authenticated": true,
  "role": "admin",
  "username": "admin",
  "strictAdmin": true
}
```
```

--------------------------------

### Get User Quota Response (Admin)

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Response showing the email quota for an administrator, indicating no limit.

```json
{
  "limit": -1,
  "used": 150,
  "remaining": -1,
  "note": "管理员无邮箱数量限制"
}

```

--------------------------------

### Get User Quota Response (Regular User)

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Response showing the email quota limits for a regular user.

```json
{
  "limit": 10,
  "used": 3,
  "remaining": 7
}

```

--------------------------------

### GET /api/generate

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Generates a new temporary email address with optional length and domain specification.

```APIDOC
## GET /api/generate

### Description
Generates a new random temporary email address.

### Method
GET

### Endpoint
/api/generate

### Query Parameters
- **length** (number) - Optional - The length of the random string for the email local part.
- **domainIndex** (number) - Optional - The index of the domain to use from the available list (defaults to 0).

### Response
#### Success Response (200)
- **email** (string) - The generated temporary email address.
- **expires** (number) - The expiration timestamp of the email address in milliseconds.

#### Response Example
```json
{
  "email": "abc123@example.com",
  "expires": 1704067200000
}
```
```

--------------------------------

### Get Email Details

Source: https://context7.com/fiz2z/mailfree/llms.txt

Fetch the complete content of a single email, including both HTML and plain text versions. Use the email's unique ID.

```bash
curl -X GET https://your.domain/api/email/1 \
  -H "Cookie: session=your_jwt_token"
```

--------------------------------

### Local Debugging with Wrangler

Source: https://github.com/fiz2z/mailfree/blob/main/README.md

Use `wrangler dev` for local development and debugging of Cloudflare Workers. This command starts a local server that mimics the Cloudflare Workers environment, allowing for rapid testing and iteration.

```bash
# Local debugging
wrangler dev
```

--------------------------------

### GET /api/users

Source: https://context7.com/fiz2z/mailfree/llms.txt

Retrieves a list of all users in the system, including their quota usage. This endpoint is intended for administrators.

```APIDOC
## GET /api/users

### Description
Retrieves a list of all users in the system, including their quota usage. This endpoint is intended for administrators.

### Method
GET

### Endpoint
/api/users

### Query Parameters
- **limit** (integer) - Optional - The maximum number of users to return.
- **offset** (integer) - Optional - The number of users to skip before starting to collect the result set.
- **sort** (string) - Optional - The field to sort the results by. Example: `desc`.

### Request Example
```bash
curl -X GET "https://your.domain/api/users?limit=50&offset=0&sort=desc" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the user.
- **username** (string) - The username of the user.
- **role** (string) - The role assigned to the user (e.g., 'user', 'admin').
- **mailbox_limit** (integer) - The maximum number of mailboxes the user can have.
- **can_send** (integer) - Indicates if the user can send emails (1 for yes, 0 for no).
- **mailbox_count** (integer) - The current number of mailboxes assigned to the user.
- **created_at** (string) - The timestamp when the user was created.

#### Response Example
```json
[
  {
    "id": 1,
    "username": "testuser",
    "role": "user",
    "mailbox_limit": 10,
    "can_send": 0,
    "mailbox_count": 3,
    "created_at": "2024-01-01 00:00:00"
  }
]
```
```

--------------------------------

### Get Email List

Source: https://context7.com/fiz2z/mailfree/llms.txt

Retrieve a list of emails for a specified mailbox, including previews and extracted verification codes. Requires a valid session cookie.

```bash
curl -X GET "https://your.domain/api/emails?mailbox=test@example.com&limit=20" \
  -H "Cookie: session=your_jwt_token"
```

--------------------------------

### Get Available Domains API Request

Source: https://context7.com/fiz2z/mailfree/llms.txt

Retrieve a list of all email domains configured in the system. This is useful for populating domain selection dropdowns when creating new email addresses.

```bash
curl -X GET https://your.domain/api/domains
```

```json
["mail.example.com", "temp.example.org"]
```

--------------------------------

### Get User Quota API Request

Source: https://context7.com/fiz2z/mailfree/llms.txt

Query the current user's mailbox limit, usage, and remaining capacity. Administrators receive a different response indicating no limit.

```bash
curl -X GET https://your.domain/api/user/quota \
  -H "Cookie: session=your_jwt_token"
```

```json
# Regular user response
{
  "limit": 10,
  "used": 3,
  "remaining": 7
}
```

```json
# Administrator response
{
  "limit": -1,
  "used": 150,
  "remaining": -1,
  "note": "管理员无邮箱数量限制"
}
```

--------------------------------

### Database Initialization - Query Mailboxes

Source: https://context7.com/fiz2z/mailfree/llms.txt

Queries the 'mailboxes' table to retrieve a sample of data.

```bash
# 查询邮箱数据
wrangler d1 execute TEMP_MAIL_DB --command "SELECT * FROM mailboxes LIMIT 10"
```

--------------------------------

### Get User Mailbox List (GET /api/users/:id/mailboxes)

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Retrieves a list of mailboxes assigned to a specific user. Requires the user's ID in the URL.

```json
[
  {
    "address": "test@example.com",
    "created_at": "2024-01-01 00:00:00",
    "is_pinned": 0
  }
]
```

--------------------------------

### Database Initialization - Execute Script

Source: https://context7.com/fiz2z/mailfree/llms.txt

Executes an SQL script using Wrangler to initialize database tables and indexes.

```bash
# 使用 wrangler 执行初始化脚本
wrangler d1 execute TEMP_MAIL_DB --file=./d1-init.sql
```

--------------------------------

### GET /api/user/quota

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Retrieves the mailbox quota for the current user.

```APIDOC
## GET /api/user/quota

### Description
Retrieves the mailbox quota for the current user.

### Method
GET

### Endpoint
/api/user/quota

### Response
#### Success Response (200)
For regular users:
- **limit** (number) - The maximum number of mailboxes allowed.
- **used** (number) - The number of mailboxes currently used.
- **remaining** (number) - The number of mailboxes remaining.

For administrators:
- **limit** (number) - -1, indicating no limit.
- **used** (number) - The number of mailboxes currently used.
- **remaining** (number) - -1, indicating no limit.
- **note** (string) - A note explaining the unlimited quota for administrators.

#### Response Example (Regular User)
```json
{
  "limit": 10,
  "used": 3,
  "remaining": 7
}
```

#### Response Example (Administrator)
```json
{
  "limit": -1,
  "used": 150,
  "remaining": -1,
  "note": "管理员无邮箱数量限制"
}
```
```

--------------------------------

### Database Initialization - Check Status

Source: https://context7.com/fiz2z/mailfree/llms.txt

Checks the database status by querying for table names.

```bash
# 检查数据库状态
wrangler d1 execute TEMP_MAIL_DB --command "SELECT name FROM sqlite_master WHERE type='table'"
```

--------------------------------

### Get User Mailboxes

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Retrieves a list of mailboxes associated with a specific user.

```APIDOC
## GET /api/users/:id/mailboxes

### Description
Retrieves a list of mailboxes for a specified user.

### Method
GET

### Endpoint
/api/users/:id/mailboxes

### Response
#### Success Response (200)
- **address** (string) - The email address.
- **created_at** (string) - The timestamp when the mailbox was created.
- **is_pinned** (integer) - Indicates if the mailbox is pinned (1 for true, 0 for false).

#### Response Example
```json
[
  {
    "address": "test@example.com",
    "created_at": "2024-01-01 00:00:00",
    "is_pinned": 0
  }
]
```
```

--------------------------------

### Create User (Admin)

Source: https://context7.com/fiz2z/mailfree/llms.txt

Creates a new user with specified role and mailbox quota. Requires JWT token for authorization.

```bash
curl -X POST https://your.domain/api/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "username": "newuser",
    "password": "password123",
    "role": "user",
    "mailboxLimit": 10
  }'
```

```json
{
  "id": 2,
  "username": "newuser",
  "role": "user",
  "mailbox_limit": 10,
  "can_send": 0,
  "created_at": "2024-01-01 00:00:00"
}
```

--------------------------------

### Create User

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Creates a new user with specified username, password, role, and mailbox limit. Requires strictAdmin privileges.

```json
{
  "username": "newuser",
  "password": "password123",
  "role": "user",
  "mailboxLimit": 10
}
```

```json
{
  "id": 2,
  "username": "newuser",
  "role": "user",
  "mailbox_limit": 10,
  "can_send": 0,
  "created_at": "2024-01-01 00:00:00"
}
```

--------------------------------

### Get Sending History

Source: https://context7.com/fiz2z/mailfree/llms.txt

Retrieves the sending history for a specific sender's email address.

```APIDOC
## GET /api/sent

### Description
Queries the sending history for emails sent by a particular sender.

### Method
GET

### Endpoint
/api/sent

### Query Parameters
- **from** (string) - Required - The sender's email address.
- **limit** (integer) - Optional - The maximum number of records to return. Defaults to 20.

### Response
#### Success Response (200)
- **id** (integer) - Unique identifier for the sent email record.
- **resend_id** (string) - The unique identifier from the email sending service (e.g., Resend).
- **recipients** (string) - The recipient(s) of the email.
- **subject** (string) - The subject line of the email.
- **created_at** (string) - Timestamp when the email was sent.
- **status** (string) - The delivery status of the email (e.g., "delivered").

#### Response Example
```json
[
  {
    "id": 1,
    "resend_id": "abc123",
    "recipients": "to@example.com",
    "subject": "邮件主题",
    "created_at": "2024-01-01 12:00:00",
    "status": "delivered"
  }
]
```
```

--------------------------------

### GET /api/mailboxes

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Retrieves a list of mailboxes associated with the current user, with filtering and pagination options.

```APIDOC
## GET /api/mailboxes

### Description
Retrieves the current user's list of mailboxes.

### Method
GET

### Endpoint
/api/mailboxes

### Query Parameters
- **limit** (number) - Optional - Number of items per page (default 100, max 500).
- **offset** (number) - Optional - Offset for pagination.
- **domain** (string) - Optional - Filter by domain name.
- **favorite** (boolean) - Optional - Filter by favorite status.
- **forward** (boolean) - Optional - Filter by forward status.

### Response
#### Success Response (200)
- An array of mailbox objects, each containing details like `id`, `address`, `created_at`, `is_pinned`, `password_is_default`, `can_login`, `forward_to`, and `is_favorite`.

#### Response Example
```json
[
  {
    "id": 1,
    "address": "test@example.com",
    "created_at": "2024-01-01 00:00:00",
    "is_pinned": 1,
    "password_is_default": 1,
    "can_login": 0,
    "forward_to": "backup@gmail.com",
    "is_favorite": 1
  }
]
```
```

--------------------------------

### List Users (Admin)

Source: https://context7.com/fiz2z/mailfree/llms.txt

Retrieves a list of all users in the system, including their quota usage. Requires JWT token for authorization.

```bash
curl -X GET "https://your.domain/api/users?limit=50&offset=0&sort=desc" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

```json
[
  {
    "id": 1,
    "username": "testuser",
    "role": "user",
    "mailbox_limit": 10,
    "can_send": 0,
    "mailbox_count": 3,
    "created_at": "2024-01-01 00:00:00"
  }
]
```

--------------------------------

### POST /api/mailboxes/batch-toggle-login

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Batch toggles login permissions for multiple mailboxes. Requires strict admin privileges.

```APIDOC
## POST /api/mailboxes/batch-toggle-login

### Description
Batch toggles login permissions for multiple mailboxes. Only available to `strictAdmin` users.

### Method
POST

### Endpoint
/api/mailboxes/batch-toggle-login

### Request Body
- **addresses** (array of strings) - Required - A list of email addresses for which to toggle login permission.
- **can_login** (boolean) - Required - The desired login permission status (true to enable, false to disable).

### Request Example
```json
{
  "addresses": ["test1@example.com", "test2@example.com"],
  "can_login": true
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the batch operation was initiated successfully.
- **success_count** (number) - The number of addresses for which the operation succeeded.
- **fail_count** (number) - The number of addresses for which the operation failed.
- **total** (number) - The total number of addresses processed.
- **results** (array of objects) - Details for each address processed, including `address`, `success` (boolean), and `updated` (boolean).

#### Response Example
```json
{
  "success": true,
  "success_count": 2,
  "fail_count": 0,
  "total": 2,
  "results": [
    { "address": "test1@example.com", "success": true, "updated": true }
  ]
}
```
```

--------------------------------

### Get Email List

Source: https://context7.com/fiz2z/mailfree/llms.txt

Retrieves a list of emails from a specified mailbox, including previews and verification codes.

```APIDOC
## GET /api/emails

### Description
Fetches a list of emails from a specified mailbox. Includes email preview and extracted verification codes.

### Method
GET

### Endpoint
/api/emails

### Query Parameters
- **mailbox** (string) - Required - The email address of the mailbox to retrieve emails from.
- **limit** (integer) - Optional - The maximum number of emails to return. Defaults to 20.

### Response
#### Success Response (200)
- **id** (integer) - Unique identifier for the email.
- **sender** (string) - The sender's email address.
- **subject** (string) - The subject line of the email.
- **received_at** (string) - Timestamp when the email was received.
- **is_read** (integer) - Read status (0 for unread, 1 for read).
- **preview** (string) - A short preview of the email content.
- **verification_code** (string) - Extracted verification code, if any.

#### Response Example
```json
[
  {
    "id": 1,
    "sender": "sender@example.com",
    "subject": "验证码邮件",
    "received_at": "2024-01-01 12:00:00",
    "is_read": 0,
    "preview": "您的验证码是 123456，请在...",
    "verification_code": "123456"
  }
]
```
```

--------------------------------

### Admin Login API Request

Source: https://context7.com/fiz2z/mailfree/llms.txt

Use this endpoint to log in as an administrator. Requires username and password.

```bash
curl -X POST https://your.domain/api/login \
  -H "Content-Type: application/json" \
  -d '{ \
    "username": "admin", \
    "password": "your_admin_password" \
  }'
```

```json
{
  "success": true,
  "role": "admin",
  "can_send": 1,
  "mailbox_limit": 9999
}
```

--------------------------------

### Get Sent Email Details

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Retrieves detailed information about a specific sent email, including content and status.

```json
{
  "id": 1,
  "resend_id": "abc123",
  "from_addr": "from@example.com",
  "recipients": "to@example.com",
  "subject": "邮件主题",
  "html_content": "<p>内容</p>",
  "text_content": "内容",
  "status": "delivered",
  "scheduled_at": null,
  "created_at": "2024-01-01 12:00:00"
}
```

--------------------------------

### Create Custom Email API Request

Source: https://context7.com/fiz2z/mailfree/llms.txt

Create an email address with a specific local part and domain. Ensure the local part is valid before sending the request.

```bash
curl -X POST https://your.domain/api/create \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your_jwt_token" \
  -d '{ \
    "local": "myname", \
    "domainIndex": 0 \
  }'
```

```json
{
  "email": "myname@mail.example.com",
  "expires": 1704067200000
}
```

```json
{
  "error": "非法用户名"
}
```

--------------------------------

### Batch Get Email Metadata

Source: https://context7.com/fiz2z/mailfree/llms.txt

Retrieves metadata for multiple emails in a single request, suitable for batch processing.

```APIDOC
## GET /api/emails/batch

### Description
Fetches metadata for multiple emails concurrently. Useful for batch operations.

### Method
GET

### Endpoint
/api/emails/batch

### Query Parameters
- **ids** (string) - Required - A comma-separated list of email IDs.

### Response
#### Success Response (200)
- **id** (integer) - Unique identifier for the email.
- **sender** (string) - The sender's email address.
- **to_addrs** (string) - The recipient's email address.
- **subject** (string) - The subject line of the email.
- **verification_code** (string) - Extracted verification code, if any.
- **preview** (string) - A short preview of the email content.
- **r2_bucket** (string) - The R2 bucket name where the email is stored.
- **r2_object_key** (string) - The object key for the email in the R2 bucket.
- **received_at** (string) - Timestamp when the email was received.
- **is_read** (integer) - Read status (0 for unread, 1 for read).

#### Response Example
```json
[
  {
    "id": 1,
    "sender": "sender@example.com",
    "to_addrs": "recipient@example.com",
    "subject": "邮件主题",
    "verification_code": "123456",
    "preview": "预览...",
    "r2_bucket": "mail-eml",
    "r2_object_key": "2024/01/01/test@example.com/xxx.eml",
    "received_at": "2024-01-01 12:00:00",
    "is_read": 0
  }
]
```
```

--------------------------------

### Configure RESEND_API_KEY for Multiple Domains

Source: https://github.com/fiz2z/mailfree/blob/main/README.md

This snippet shows how to configure the RESEND_API_KEY environment variable to support multiple domains with different API keys. The system automatically selects the appropriate key based on the sender's domain. Recommended for flexible sender configurations.

```bash
# Single key (backward compatible)
RESEND_API_KEY="re_xxxxxxxxxxxxxxxxxxxxxxxx"

# Key-value format (recommended)
RESEND_API_KEY="domain1.com=re_key1,domain2.com=re_key2"

# JSON format
RESEND_API_KEY='{"domain1.com":"re_key1","domain2.com":"re_key2"}'
```

--------------------------------

### Get Email Details

Source: https://context7.com/fiz2z/mailfree/llms.txt

Retrieves the full content of a single email, including HTML and plain text versions.

```APIDOC
## GET /api/email/{id}

### Description
Fetches the complete content of a specific email, including both HTML and plain text versions.

### Method
GET

### Endpoint
/api/email/{id}

### Path Parameters
- **id** (integer) - Required - The unique identifier of the email.

### Response
#### Success Response (200)
- **id** (integer) - Unique identifier for the email.
- **sender** (string) - The sender's email address.
- **to_addrs** (string) - The recipient's email address.
- **subject** (string) - The subject line of the email.
- **verification_code** (string) - Extracted verification code, if any.
- **content** (string) - The plain text content of the email.
- **html_content** (string) - The HTML content of the email.
- **received_at** (string) - Timestamp when the email was received.
- **is_read** (integer) - Read status (0 for unread, 1 for read).
- **download** (string) - URL to download the raw EML file.

#### Response Example
```json
{
  "id": 1,
  "sender": "sender@example.com",
  "to_addrs": "recipient@example.com",
  "subject": "邮件主题",
  "verification_code": "123456",
  "content": "纯文本内容",
  "html_content": "<p>HTML内容</p>",
  "received_at": "2024-01-01 12:00:00",
  "is_read": 1,
  "download": "/api/email/1/download"
}
```
```

--------------------------------

### 本地开发与部署 Cloudflare Worker

Source: https://github.com/fiz2z/mailfree/blob/main/docs/resend.md

使用 Wrangler CLI 进行本地开发和部署 Cloudflare Worker。确保 `wrangler.toml` 已配置 D1 数据库和静态资源。

```bash
# 本地开发
wrangler dev

# 正式部署
wrangler deploy
```

--------------------------------

### Get Single Email Details

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Retrieves the full details of a single email by its ID, including content and read status.

```json
{
  "id": 1,
  "sender": "sender@example.com",
  "to_addrs": "recipient@example.com",
  "subject": "邮件主题",
  "verification_code": "123456",
  "content": "纯文本内容",
  "html_content": "<p>HTML内容</p>",
  "received_at": "2024-01-01 12:00:00",
  "is_read": 1,
  "download": "/api/email/1/download"
}
```

--------------------------------

### 配置 Resend API Key 和 Domain (Cloudflare Workers)

Source: https://github.com/fiz2z/mailfree/blob/main/docs/resend.md

使用 Wrangler 命令行工具设置 Resend API Key 作为 Secret 变量，以及 MAIL_DOMAIN 作为普通变量。推荐使用 RESEND_API_KEY。

```bash
wrangler secret put RESEND_API_KEY
# 或者使用下面同义变量（不推荐）：RESEND_TOKEN / RESEND 

# 设置普通变量（可写入 wrangler.toml 的 [vars]）
# 多域名用逗号/空格分隔
# 例：MAIL_DOMAIN="iding.asia, example.com"
```

--------------------------------

### Get Batch Email Metadata

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Retrieves metadata for multiple emails using a comma-separated list of IDs. Supports up to 50 IDs.

```json
[
  {
    "id": 1,
    "sender": "sender@example.com",
    "to_addrs": "recipient@example.com",
    "subject": "邮件主题",
    "verification_code": "123456",
    "preview": "预览...",
    "r2_bucket": "mail-eml",
    "r2_object_key": "2024/01/01/test@example.com/xxx.eml",
    "received_at": "2024-01-01 12:00:00",
    "is_read": 0
  }
]
```

--------------------------------

### Configure FORWARD_RULES for Email Forwarding

Source: https://github.com/fiz2z/mailfree/blob/main/README.md

This snippet demonstrates how to configure the FORWARD_RULES environment variable for email forwarding. Rules are matched by prefix, with '*' serving as a fallback. It's crucial to verify forwarding target emails in Cloudflare's Email Routing settings.

```bash
# Key-value format
FORWARD_RULES="vip=a@example.com,news=b@example.com,*=fallback@example.com"

# JSON format
FORWARD_RULES='[{"prefix":"vip","email":"a@example.com"},{"prefix":"*","email":"fallback@example.com"}]'

# Disable forwarding
FORWARD_RULES="" || "disabled" || "none"
```

--------------------------------

### Inspect D1 Database with Wrangler

Source: https://github.com/fiz2z/mailfree/blob/main/README.md

This command allows you to execute SQL queries directly against your D1 database. Replace `TEMP_MAIL_DB` with your actual database name and adjust the query as needed to inspect data.

```bash
# Inspect the database
wrangler d1 execute TEMP_MAIL_DB --command "SELECT * FROM mailboxes LIMIT 10"
```

--------------------------------

### Download Raw EML File

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Provides a direct download link for the raw EML file of a specific email.

```text
message/rfc822
```

--------------------------------

### Get Email List

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Retrieves a list of emails for a specified mailbox. Requires the mailbox address and optionally accepts a limit for the number of results.

```json
[
  {
    "id": 1,
    "sender": "sender@example.com",
    "subject": "邮件主题",
    "received_at": "2024-01-01 12:00:00",
    "is_read": 0,
    "preview": "邮件内容预览...",
    "verification_code": "123456"
  }
]
```

--------------------------------

### Fetch Session and Load App

Source: https://github.com/fiz2z/mailfree/blob/main/public/index.html

This snippet fetches session data, checks user roles, and dynamically loads either the main application script or a mobile-specific script based on screen width. It includes error handling and timeout mechanisms.

```javascript
sCookie = document.cookie.split(';').some(function(c){ return c.trim().indexOf('iding-session=') === 0; }); }catch(\_){ } const controller = new AbortController(); const tid = setTimeout(function(){ try{ controller.abort(); }catch(\_){ } }, 2000); // 延长超时到2秒 fetch('/api/session', { headers: { 'Cache-Control': 'no-cache' }, signal: controller.signal, credentials: 'include' }) .then(function(r){ clearTimeout(tid); if (r && r.ok){ return r.json().then(function(s){ if (s && s.role === 'mailbox') { window.location.replace('/html/mailbox.html'); return null; } return s; }); } else { // 如果有cookie但验证失败，让应用内部处理而不是立即跳转到登录页 if (hasCookie) { try{ sessionStorage.setItem('auth\_checked','true'); sessionStorage.setItem('auth\_checked\_ts', String(Date.now())); }catch(\_){ } var s1 = document.createElement('script'); s1.type = 'module'; s1.src = '/js/app.js'; document.body.appendChild(s1); try{ if (window.matchMedia && window.matchMedia('(max-width: 900px)').matches){ var sm=document.createElement('script'); sm.type='module'; sm.src='/js/app-mobile.js'; document.body.appendChild(sm); } }catch(\_){ } return null; } window.location.replace('/html/login.html'); return null; } }) .then(function(s){ if (!s) return; try{ sessionStorage.setItem('auth\_checked','true'); sessionStorage.setItem('auth\_checked\_ts', String(Date.now())); }catch(\_){ } var s1 = document.createElement('script'); s1.type = 'module'; s1.src = '/js/app.js'; document.body.appendChild(s1); try{ if (window.matchMedia && window.matchMedia('(max-width: 900px)').matches){ var sm=document.createElement('script'); sm.type='module'; sm.src='/js/app-mobile.js'; document.body.appendChild(sm); } }catch(\_){ } }) .catch(function(){ // 网络错误时，如果有cookie就直接加载应用 if (hasCookie) { try{ sessionStorage.setItem('auth\_checked','true'); sessionStorage.setItem('auth\_checked\_ts', String(Date.now())); }catch(\_){ } var s1 = document.createElement('script'); s1.type = 'module'; s1.src = '/js/app.js'; document.body.appendChild(s1); try{ if (window.matchMedia && window.matchMedia('(max-width: 900px)').matches){ var sm=document.createElement('script'); sm.type='module'; sm.src='/js/app-mobile.js'; document.body.appendChild(sm); } }catch(\_){ } } else { window.location.replace('/html/login.html'); } }); } }catch(\_){ window.location.replace('/templates/loading.html?redirect=/'); } })();
```

--------------------------------

### Get Mailboxes

Source: https://github.com/fiz2z/mailfree/blob/main/docs/pin-feature.md

Retrieves a list of all mailboxes, sorted according to their pinned status and last access time. Pinned mailboxes appear at the top.

```APIDOC
## GET /api/mailboxes

### Description

Fetches a list of all mailboxes. The list is intelligently sorted with pinned mailboxes appearing first, followed by non-pinned mailboxes sorted by last access time.

### Method

GET

### Endpoint

/api/mailboxes

### Parameters

#### Query Parameters

- **page** (integer) - Optional - The page number for pagination.
- **limit** (integer) - Optional - The number of items per page.

### Response

#### Success Response (200)

- **mailboxes** (array) - A list of mailbox objects.
  - **address** (string) - The email address.
  - **is_pinned** (integer) - Indicates if the mailbox is pinned (1 for pinned, 0 for not pinned).
  - **last_accessed** (string) - Timestamp of the last access.

#### Response Example

```json
{
  "mailboxes": [
    {
      "address": "pinned@example.com",
      "is_pinned": 1,
      "last_accessed": "2023-10-27T10:00:00Z"
    },
    {
      "address": "another@example.com",
      "is_pinned": 0,
      "last_accessed": "2023-10-27T09:30:00Z"
    }
  ]
}
```
```

--------------------------------

### Get Sent Email List

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Retrieves a list of sent email records. Requires the sender's email address and optionally accepts a limit.

```json
[
  {
    "id": 1,
    "resend_id": "abc123",
    "recipients": "to@example.com",
    "subject": "邮件主题",
    "created_at": "2024-01-01 12:00:00",
    "status": "delivered"
  }
]
```

--------------------------------

### POST /api/users

Source: https://context7.com/fiz2z/mailfree/llms.txt

Creates a new user in the system, allowing administrators to set their role and mailbox quota.

```APIDOC
## POST /api/users

### Description
Creates a new user in the system, allowing administrators to set their role and mailbox quota.

### Method
POST

### Endpoint
/api/users

### Request Body
- **username** (string) - Required - The desired username for the new user.
- **password** (string) - Required - The password for the new user.
- **role** (string) - Required - The role to assign to the user (e.g., 'user', 'admin').
- **mailboxLimit** (integer) - Required - The maximum number of mailboxes the user can have.

### Request Example
```json
{
  "username": "newuser",
  "password": "password123",
  "role": "user",
  "mailboxLimit": 10
}
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the newly created user.
- **username** (string) - The username of the new user.
- **role** (string) - The role assigned to the new user.
- **mailbox_limit** (integer) - The maximum number of mailboxes the new user can have.
- **can_send** (integer) - Indicates if the new user can send emails (1 for yes, 0 for no).
- **created_at** (string) - The timestamp when the user was created.

#### Response Example
```json
{
  "id": 2,
  "username": "newuser",
  "role": "user",
  "mailbox_limit": 10,
  "can_send": 0,
  "created_at": "2024-01-01 00:00:00"
}
```
```

--------------------------------

### Batch Toggle Email Login Permission

Source: https://context7.com/fiz2z/mailfree/llms.txt

Allows administrators to toggle login permissions for multiple email addresses simultaneously. The response provides counts for successful and failed operations.

```bash
curl -X POST https://your.domain/api/mailboxes/batch-toggle-login \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "addresses": ["test1@example.com", "test2@example.com"],
    "can_login": true
  }'
```

--------------------------------

### POST /api/login

Source: https://github.com/fiz2z/mailfree/blob/main/docs/api.md

Authenticates a user by username and password, supporting various login methods.

```APIDOC
## POST /api/login

### Description
User login endpoint.

### Method
POST

### Endpoint
/api/login

### Request Body
- **username** (string) - Required - Username or email address
- **password** (string) - Required - Password

### Request Example
```json
{
  "username": "username or email address",
  "password": "password"
}
```

### Supported Login Methods:
1. Administrator login: Use `ADMIN_NAME` / `ADMIN_PASSWORD` environment variables.
2. Guest login: Username `guest`, password from `GUEST_PASSWORD` environment variable.
3. Regular user login: Users from the `users` table in the database.
4. Mailbox login: Log in using an email address (requires `can_login` to be enabled).

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the login was successful.
- **role** (string) - The role of the logged-in user.
- **can_send** (number) - Indicates if the user can send emails.
- **mailbox_limit** (number) - The maximum number of mailboxes the user can manage.

#### Response Example
```json
{
  "success": true,
  "role": "admin",
  "can_send": 1,
  "mailbox_limit": 9999
}
```
```

--------------------------------

### Get Sending History

Source: https://context7.com/fiz2z/mailfree/llms.txt

Query the sending history for a specific sender. The response includes details like recipients, subject, and delivery status. Requires a valid session cookie.

```bash
curl -X GET "https://your.domain/api/sent?from=sender@yourdomain.com&limit=20" \
  -H "Cookie: session=your_jwt_token"
```

--------------------------------

### Batch Get Email Metadata

Source: https://context7.com/fiz2z/mailfree/llms.txt

Request metadata for multiple emails in a single API call, suitable for batch processing scenarios. Provide a comma-separated list of email IDs.

```bash
curl -X GET "https://your.domain/api/emails/batch?ids=1,2,3,4,5" \
  -H "Cookie: session=your_jwt_token"
```

--------------------------------

### Check Login Status and Redirect

Source: https://github.com/fiz2z/mailfree/blob/main/public/html/login.html

Immediately checks login status via cookies and API before other scripts execute. Redirects to the homepage if logged in, otherwise proceeds with further checks. Handles cases with and without referrer.

```javascript
body{ visibility: hidden; } // 立即检查登录状态（在任何其他脚本之前） (function(){ try{ var hasToken = document.cookie.split(';').some(function(c){ return c.trim().indexOf('iding-session=') === 0; }); // 如果有cookie但是从其他页面跳转过来的，先验证有效性再跳转 // 避免无效cookie导致的循环跳转和页面闪现 if (hasToken && document.referrer) { // 异步验证，不阻止页面渲染 (async function(){ try{ const controller = new AbortController(); const tid = setTimeout(function(){ try{ controller.abort(); }catch(_){ } }, 1500); const r = await fetch('/api/session', { method: 'GET', headers: { 'Cache-Control': 'no-cache' }, credentials: 'include', signal: controller.signal }); clearTimeout(tid); if (r && r.ok){ location.replace('/'); } else { // cookie无效，清除它 document.cookie = 'iding-session=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;'; } }catch(_){ // 验证失败，保持在登录页面 } })(); return; } else if (hasToken && !document.referrer) { // 直接访问登录页且有cookie，立即重定向 location.replace('/'); return; } // 没有cookie，做一次网络检查（可能cookie刚设置还没生效） fetch('/api/session', { method: 'GET', headers: { 'Cache-Control': 'no-cache' }, credentials: 'include' }).then(function(r){ if (r && r.ok){ location.replace('/'); } }).catch(function(){ // 会话检查失败，保持在登录页面 }); }catch(_){ // 错误处理，保持在登录页面 } })();
```

--------------------------------

### Batch Forward Emails by Address

Source: https://context7.com/fiz2z/mailfree/llms.txt

Allows setting up forwarding for multiple email addresses in a single request.

```APIDOC
## POST /api/mailboxes/batch-forward-by-address

### Description
Sets up email forwarding for a list of email addresses to a specified destination.

### Method
POST

### Endpoint
/api/mailboxes/batch-forward-by-address

### Request Body
- **addresses** (array[string]) - Required - A list of email addresses to set forwarding for.
- **forward_to** (string) - Required - The email address to forward messages to.

### Request Example
```json
{
  "addresses": ["test1@example.com", "test2@example.com"],
  "forward_to": "backup@gmail.com"
}
```
```

--------------------------------

### Get Mailboxes List API Request

Source: https://context7.com/fiz2z/mailfree/llms.txt

Retrieve a list of all mailboxes associated with the current user. Supports pagination, searching, and filtering by domain, favorite status, and forwarding status.

```bash
# Basic pagination
curl -X GET "https://your.domain/api/mailboxes?page=1&size=20" \
  -H "Cookie: session=your_jwt_token"
```

```bash
# Pagination using limit/offset
curl -X GET "https://your.domain/api/mailboxes?limit=100&offset=0" \
  -H "Cookie: session=your_jwt_token"
```

```bash
# Search and filter
curl -X GET "https://your.domain/api/mailboxes?q=test&domain=example.com&favorite=true&forward=true" \
  -H "Cookie: session=your_jwt_token"
```

```json
{
  "list": [
    {
      "id": 1,
      "address": "test@example.com",
      "created_at": "2024-01-01 00:00:00",
      "is_pinned": 1,
      "password_is_default": 1,
      "can_login": 0,
      "forward_to": "backup@gmail.com",
      "is_favorite": 1
    }
  ],
  "total": 150
}
```