### Download Docker Setup Script

Source: https://github.com/frappe/mail/blob/develop/README.md

Download the init.sh script for initializing the Frappe Mail Docker setup.

```bash
wget -O init.sh https://raw.githubusercontent.com/frappe/mail/develop/docker/init.sh
```

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

### Install and Enable Pre-commit Hooks

Source: https://github.com/frappe/mail/blob/develop/README.md

Install pre-commit and enable it for the Frappe Mail repository to ensure code formatting and linting.

```bash
cd apps/mail
pre-commit install
```

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

### Install Frappe Mail App and Create Site

Source: https://github.com/frappe/mail/blob/develop/README.md

Install the Mail app using Frappe Bench and create a new site for Frappe Mail.

```bash
bench get-app mail
bench new-site mail.localhost --install-app mail
bench browse mail.localhost --user Administrator
```

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

### Install Frappe App

Source: https://github.com/frappe/mail/blob/develop/CLAUDE.md

Installs the 'mail' app for a specific Frappe site. Run this command from the bench root directory.

```bash
bench --site <site> install-app mail
```

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

### Development Server

Source: https://github.com/frappe/mail/blob/develop/CLAUDE.md

Starts the Vite development server for the frontend. Can be run from the repository root or the frontend directory.

```bash
# Development (from repo root or frontend/)
npm run dev              # Start Vite dev server via bun
bun run dev              # Equivalent, from frontend/
```

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

### Run Docker Compose

Source: https://github.com/frappe/mail/blob/develop/README.md

Run the Docker containers in detached mode to start Frappe Mail.

```bash
docker compose up -d
```

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

### GET /inbound/pull-raw

Source: https://github.com/frappe/mail/blob/develop/README.md

Fetches a list of emails in their raw MIME format from a specified mailbox. Parameters are the same as for the `/inbound/pull` endpoint.

```APIDOC
## GET /inbound/pull-raw

### Description
Fetches a list of emails in their raw MIME format from a specified mailbox. Parameters are the same as for the `/inbound/pull` endpoint.

### Method
GET

### Endpoint
/inbound/pull-raw or /api/method/mail.api.inbound.pull_raw

### Parameters
#### Query Parameters
- **mailbox** (str | None) - Optional - The mailbox to fetch emails from. Defaults to `inbox`.
- **limit** (int) - Optional - Maximum number of emails to retrieve. Defaults to 50.
- **last_received_at** (str | None) - Optional - Optional timestamp to fetch emails received after this time.

### Response
#### Success Response (200)
Returns raw MIME messages.

#### Response Example
```json
{
  "message": {
    "mails": [
      "Delivered-To: sagar.s@frappemail.com\r\nReceived: from outbound.frappemail.com ..."
    ],
    "last_received_at": "2025-12-08 12:51:10+00:00",
    "last_received_mail": "sagar.s@frappemail.com|bfqaaaaj3"
  }
}
```
```

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

### GET /inbound/pull

Source: https://github.com/frappe/mail/blob/develop/README.md

Fetches a list of emails with their details from a specified mailbox. Supports filtering by mailbox, limit, and last received timestamp.

```APIDOC
## GET /inbound/pull

### Description
Fetches a list of emails with their details from a specified mailbox. Supports filtering by mailbox, limit, and last received timestamp.

### Method
GET

### Endpoint
/inbound/pull or /api/method/mail.api.inbound.pull

### Parameters
#### Query Parameters
- **mailbox** (str | None) - Optional - The mailbox to fetch emails from. Defaults to `inbox`.
- **limit** (int) - Optional - Maximum number of emails to retrieve. Defaults to 50.
- **last_received_at** (str | None) - Optional - Optional timestamp to fetch emails received after this time.

### Response
#### Success Response (200)
Returns a dictionary with a list of email details.

#### Response Example
```json
{
  "message": {
    "mails": [
      {
        "user": "sagar.s@frappemail.com",
        "sent_at": "2025-12-08 12:51:09+00:00",
        "id": "bfqaaaaj3",
        "size": 5243,
        "received_at": "2025-12-08 12:51:10+00:00",
        "blob_id": "ccodqfu9bg1aevchbuyrlcpprhctnqq9ao2h3gkbdy1zysoseq33qpaax2ba",
        "subject": "Hello 👋",
        "thread_id": "jm",
        "name": "sagar.s@frappemail.com|bfqaaaaj3",
        "preview": "Hello, From Frappe Mail...",
        "has_attachment": 0,
        "keywords": "{\n    \"$seen\": true\n}",
        "received_after": 1.0,
        "sender_name": null,
        "sender_email": null,
        "from_name": "Sagar Sharma",
        "from_email": "sagar.s@frappe.io",
        "reply_to": [],
        "recipients": [
          {
            "type": "To",
            "display_name": null,
            "email": "sagar.s@frappemail.com"
          }
        ],
        "html_body": "<div>Hello, From Frappe Mail…</div>",
        "text_body": "Hello, From Frappe Mail...",
        "mailboxes": [
          {
            "mailbox": "sagar.s@frappemail.com|a",
            "mailbox_id": "a",
            "mailbox_name": "Inbox"
          }
        ],
        "draft": 0,
        "junk": 0,
        "seen": 1,
        "flagged": 0,
        "answered": 0,
        "forwarded": 0,
        "message_id": "176519819654.76284.13616894718620722082@frappe.io",
        "in_reply_to": null,
        "attachments": [],
        "_html_body": [
          {
            "part_id": "2",
            "blob_id": "ckodqfu9bg1aevchbuyrlcpprhctnqq9ao2h3gkbdy1zysoseq33qpaax2bjmkbl",
            "size": 37,
            "filename": null,
            "type": "text/html",
            "charset": "utf-8",
            "disposition": null,
            "cid": null,
            "language": "None",
            "location": null
          }
        ],
        "_text_body": [
          {
            "part_id": "1",
            "blob_id": "cgodqfu9bg1aevchbuyrlcpprhctnqq9ao2h3gkbdy1zysoseq33qpaax2bowjq7",
            "size": 26,
            "filename": null,
            "type": "text/plain",
            "charset": "utf-8",
            "disposition": null,
            "cid": null,
            "language": "None",
            "location": null
          }
        ]
      }
    ],
    "last_received_at": "2025-12-08 12:51:10+00:00",
    "last_received_mail": "sagar.s@frappemail.com|bfqaaaaj3"
  }
}
```
```

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

### Build Frontend Assets

Source: https://github.com/frappe/mail/blob/develop/CLAUDE.md

Builds the frontend application and email CSS. Use 'build-app' for frontend only or 'build-email-css' for Tailwind CSS for email templates.

```bash
# Build
npm run build            # Build frontend + email CSS
npm run build-app        # Frontend only
npm run build-email-css  # Tailwind CSS for email templates (output: mail/public/css/email.css)
```

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

### Download Docker Compose File

Source: https://github.com/frappe/mail/blob/develop/README.md

Download the docker-compose.yml file for setting up Frappe Mail using Docker.

```bash
wget -O docker-compose.yml https://raw.githubusercontent.com/frappe/mail/develop/docker/docker-compose.yml
```

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

### Run Pre-commit Hooks

Source: https://github.com/frappe/mail/blob/develop/CLAUDE.md

Executes all pre-commit hooks for Python (ruff), JavaScript (eslint), prettier, and pyupgrade. This ensures code quality across the project.

```bash
pre-commit run --all-files   # Python (ruff) + JS (eslint) + prettier + pyupgrade
```

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

### Configure Mail Server Username and Password

Source: https://github.com/frappe/mail/blob/develop/README.md

Use this JSON configuration for Stalwart API communication with username and password authentication. Ensure `server_url` points to your Mail Server.

```json
{
  "mail": {
    "server_url": "https://mail.example.com",
    "username": "admin",
    "password": "your-password"
  }
}
```

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

### Configure Mail Server API Key

Source: https://github.com/frappe/mail/blob/develop/README.md

Use this JSON configuration for Stalwart API communication with an API key. Ensure `server_url` points to your Mail Server.

```json
{
  "mail": {
    "server_url": "https://mail.example.com",
    "api_key": "your-stalwart-api-key"
  }
}
```

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

### Rebuild Frappe Assets

Source: https://github.com/frappe/mail/blob/develop/CLAUDE.md

Rebuilds the assets for the Frappe application. This command should be run from the bench root.

```bash
bench build                                         # Rebuild assets
```

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

### Run Frappe App Tests

Source: https://github.com/frappe/mail/blob/develop/CLAUDE.md

Executes tests for the 'mail' app. You can run all tests or specify a single module for targeted testing.

```bash
bench --site <site> run-tests --app mail          # All tests
bench --site <site> run-tests --app mail --module mail.tests.test_foo  # Single test
```

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

### Button Macro

Source: https://github.com/frappe/mail/blob/develop/mail/templates/emails/macros.html

Generates a button with a label and a link. Can be styled as primary.

```html
{% macro button(label, link, primary = true) %}

[{{ label }}]({{ link }})

{% endmacro %}
```

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

### Generic Email Template Structure

Source: https://github.com/frappe/mail/blob/develop/mail/templates/emails/generic.html

This Jinja2 template defines the structure for a generic email. It imports utility macros and extends a base template, then defines blocks for dynamic content like title, description, and a call-to-action button.

```html
{% import "templates/emails/macros.html" as utils %} {% extends "templates/emails/base.html" %} {% set title = title %} {% set description = description %} {% set button = button %} {% set link = link %} {% block content %}

{{ 
_('Hello,') }}

{{ title }}

{{ description }}

{{ utils.button(button, link) }} {{ utils.separator() }}

{{ 
_('Team Frappe') }}

{% endblock %}
```

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

### Lint JavaScript Code

Source: https://github.com/frappe/mail/blob/develop/CLAUDE.md

Lints the JavaScript code in the frontend directory using ESLint. Navigate to the frontend directory before running this command.

```bash
cd frontend && bun run lint  # ESLint only
```

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

### Lint Python Code

Source: https://github.com/frappe/mail/blob/develop/CLAUDE.md

Checks the Python code in the 'mail/' directory using ruff for linting. This command focuses solely on Python code quality.

```bash
ruff check mail/             # Python only
```

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

### Validate User Authentication

Source: https://github.com/frappe/mail/blob/develop/README.md

This API endpoint validates user permissions and email ownership. It returns nothing on success and throws an exception on failure.

```python
from frappe import frappe

try:
    frappe.call("mail.api.auth.validate", email="user@example.com")
    print("Email validated successfully.")
except Exception as e:
    print(f"Email validation failed: {e}")
```

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

### Fetch Raw Email Messages

Source: https://github.com/frappe/mail/blob/develop/README.md

Retrieves a list of emails in their raw MIME format. This is useful for detailed analysis or when the structured data is insufficient. Parameters are the same as the standard pull endpoint.

```json
{
  "message": {
    "mails": [
      "Delivered-To: sagar.s@frappemail.com\r\nReceived: from outbound.frappemail.com ..."
    ],
    "last_received_at": "2025-12-08 12:51:10+00:00",
    "last_received_mail": "sagar.s@frappemail.com|bfqaaaaj3"
  }
}
```

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

### POST /outbound/send-raw

Source: https://github.com/frappe/mail/blob/develop/README.md

Sends a raw MIME message, allowing users to send preformatted emails.

```APIDOC
## POST /outbound/send-raw

### Description
Sends a raw MIME message. This can be useful for users who want to send a preformatted email.

### Method
POST

### Endpoint
/outbound/send-raw or /api/method/mail.api.outbound.send_raw

### Parameters
#### Query Parameters
- **from_** (str) - Required - Sender's email address.
- **to** (str | list[str]) - Required - Recipient email(s).
- **raw_message** (str) - Required - The complete raw MIME message.
- **is_newsletter** (bool) - Optional - Flag to mark the email as a newsletter. Defaults to False.

### Response
#### Success Response (200)
Returns a UUID (name) of the created Mail Queue document.

#### Response Example
```json
{
  "message": "019300a4-91fc-741f-9fe5-9ade8976637f"
}
```
```

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

### Separator Macro

Source: https://github.com/frappe/mail/blob/develop/mail/templates/emails/macros.html

Generates a visual separator in the email content.

```html
{% macro separator() %}

{% endmacro %}
```

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

### Fetch List of Emails

Source: https://github.com/frappe/mail/blob/develop/README.md

Retrieves a list of emails with their details from a specified mailbox. Useful for displaying email summaries in an inbox view. Supports filtering by last received time.

```json
{
  "message": {
    "mails": [
      {
        "user": "sagar.s@frappemail.com",
        "sent_at": "2025-12-08 12:51:09+00:00",
        "id": "bfqaaaaj3",
        "size": 5243,
        "received_at": "2025-12-08 12:51:10+00:00",
        "blob_id": "ccodqfu9bg1aevchbuyrlcpprhctnqq9ao2h3gkbdy1zysoseq33qpaax2ba",
        "subject": "Hello 👋",
        "thread_id": "jm",
        "name": "sagar.s@frappemail.com|bfqaaaaj3",
        "preview": "Hello, From Frappe Mail...",
        "has_attachment": 0,
        "keywords": "{
    \"$seen\": true
}",
        "received_after": 1.0,
        "sender_name": null,
        "sender_email": null,
        "from_name": "Sagar Sharma",
        "from_email": "sagar.s@frappe.io",
        "reply_to": [],
        "recipients": [
          {
            "type": "To",
            "display_name": null,
            "email": "sagar.s@frappemail.com"
          }
        ],
        "html_body": "<div>Hello, From Frappe Mail…</div>",
        "text_body": "Hello, From Frappe Mail...",
        "mailboxes": [
          {
            "mailbox": "sagar.s@frappemail.com|a",
            "mailbox_id": "a",
            "mailbox_name": "Inbox"
          }
        ],
        "draft": 0,
        "junk": 0,
        "seen": 1,
        "flagged": 0,
        "answered": 0,
        "forwarded": 0,
        "message_id": "176519819654.76284.13616894718620722082@frappe.io",
        "in_reply_to": null,
        "attachments": [],
        "_html_body": [
          {
            "part_id": "2",
            "blob_id": "ckodqfu9bg1aevchbuyrlcpprhctnqq9ao2h3gkbdy1zysoseq33qpaax2bjmkbl",
            "size": 37,
            "filename": null,
            "type": "text/html",
            "charset": "utf-8",
            "disposition": null,
            "cid": null,
            "language": "None",
            "location": null
          }
        ],
        "_text_body": [
          {
            "part_id": "1",
            "blob_id": "cgodqfu9bg1aevchbuyrlcpprhctnqq9ao2h3gkbdy1zysoseq33qpaax2bowjq7",
            "size": 26,
            "filename": null,
            "type": "text/plain",
            "charset": "utf-8",
            "disposition": null,
            "cid": null,
            "language": "None",
            "location": null
          }
        ]
      }
    ],
    "last_received_at": "2025-12-08 12:51:10+00:00",
    "last_received_mail": "sagar.s@frappemail.com|bfqaaaaj3"
  }
}
```

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

### POST /outbound/send

Source: https://github.com/frappe/mail/blob/develop/README.md

Sends an email message through Frappe Mail, supporting various options like attachments, CC, BCC, and HTML content.

```APIDOC
## POST /outbound/send

### Description
Sends an email message with options for attachments, carbon copies (cc), and blind carbon copies (bcc).

### Method
POST

### Endpoint
/outbound/send or /api/method/mail.api.outbound.send

### Parameters
#### Query Parameters
- **from_** (str) - Required - The sender's email address.
- **to** (str | list[str]) - Required - Recipient email(s).
- **subject** (str) - Required - Subject of the email.
- **cc** (str | list[str] | None) - Optional - Carbon copy recipients.
- **bcc** (str | list[str] | None) - Optional - Blind carbon copy recipients.
- **html** (str | None) - Optional - HTML body of the email.
- **reply_to** (str | list[str] | None) - Optional - Reply-to email(s).
- **in_reply_to_mail_type** (str | None) - Optional - Reference type for the email being replied to.
- **in_reply_to_mail_name** (str | None) - Optional - Reference ID for the email being replied to.
- **custom_headers** (dict | None) - Optional - Custom headers.
- **attachments** (list[dict] | None) - Optional - List of attachments.
- **is_newsletter** (bool) - Optional - Flag to mark the email as a newsletter. Defaults to False.

### Response
#### Success Response (200)
Returns a UUID (name) of the created Mail Queue document.

#### Response Example
```json
{
  "message": "019300a4-91fc-741f-9fe5-9ade8976637f"
}
```
```

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

### POST /auth/validate

Source: https://github.com/frappe/mail/blob/develop/README.md

Validates if a user has the required permissions and owns the email address. It is used for authentication purposes within the Frappe Mail system.

```APIDOC
## POST /auth/validate

### Description
Validates if a user has the required permissions and owns the email address.

### Method
POST

### Endpoint
/auth/validate or /api/method/mail.api.auth.validate

### Parameters
#### Query Parameters
- **email** (str) - Required - The email address to validate.

### Response
#### Success Response (200)
Returns nothing if validation is successful.

#### Error Response
Throws an exception with the reason if the email address cannot be validated.
```

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

### Send Email via Outbound API

Source: https://github.com/frappe/mail/blob/develop/README.md

Use this API to send emails with various options including attachments, CC, BCC, and custom headers. It returns the UUID of the created Mail Queue document.

```python
from frappe import frappe

frappe.call("mail.api.outbound.send",
    from_="sender@example.com",
    to=["recipient1@example.com", "recipient2@example.com"],
    subject="Test Email",
    html="<p>This is a test email.</p>",
    attachments=[
        {
            "filename": "test.txt",
            "content": "This is the file content."
        }
    ],
    cc=["cc1@example.com"],
    bcc=["bcc1@example.com"],
    custom_headers={"X-Custom-Header": "Value"},
    is_newsletter=True
)
```

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

### Send Raw MIME Email via Outbound API

Source: https://github.com/frappe/mail/blob/develop/README.md

This API allows sending a pre-formatted raw MIME message. It's useful for sending emails with complex structures or specific MIME types. It returns the UUID of the created Mail Queue document.

```python
from frappe import frappe

raw_message = """
From: sender@example.com
To: recipient@example.com
Subject: Raw Email Test
Content-Type: text/plain; charset=utf-8

This is the raw content of the email.
"""

frappe.call("mail.api.outbound.send_raw",
    from_="sender@example.com",
    to=["recipient@example.com"],
    raw_message=raw_message,
    is_newsletter=False
)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.