### Install Dependencies and Start Database (Bash)

Source: https://github.com/mail-0/zero/blob/staging/README.md

This snippet demonstrates how to clone the Zero repository, install project dependencies using pnpm, and start the local PostgreSQL database using Docker Compose. It's a crucial first step for setting up the development environment.

```bash
git clone https://github.com/Mail-0/Zero.git
cd Zero
pnpm install
pnpm docker:db:up
```

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

### Initialize and Start Zero Application (Bash)

Source: https://github.com/mail-0/zero/blob/staging/README.md

This sequence of commands initializes the PostgreSQL database by pushing the schema and then starts the Zero development server. After running these, the application can be accessed via a local web browser.

```bash
pnpm db:push
pnpm dev
```

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

### Start Local PostgreSQL Database

Source: https://github.com/mail-0/zero/blob/staging/README.md

Initiate a local PostgreSQL instance using the provided pnpm command. This command sets up a database named 'zerodotemail' with default credentials and port.

```bash
pnpm docker:db:up
```

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

### Run Zero Mail Scripts

Source: https://github.com/mail-0/zero/blob/staging/scripts/README.md

Demonstrates how to execute utility scripts for the Zero email application from the project root using pnpm. It shows the general command structure and an example for running the 'seed-style' script.

```bash
# Run a script from the project root
pnpm scripts <script-name> [options]

# Example: Run the seed-style script
pnpm scripts seed-style
```

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

### Create New Script with cmd-ts

Source: https://github.com/mail-0/zero/blob/staging/scripts/README.md

A TypeScript example demonstrating how to create a new utility script using the cmd-ts library. It shows the basic structure for defining a command, its arguments, and the handler function for script logic.

```typescript
import { command, option, string as stringType } from 'cmd-ts';

export const myScriptCommand = command({
  name: 'my-script',
  description: 'Description of what my script does',
  args: {
    // Define command-line arguments
    param1: option({
      type: stringType,
      long: 'param1',
      short: 'p',
      description: 'Description of param1',
    }),
  },
  handler: async (inputs) => {
    // Script implementation
    console.log(`Running my script with param1: ${inputs.param1}`);
    // Do something useful here
  },
});
```

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

### MCP Server Tools Integration (TypeScript)

Source: https://context7.com/mail-0/zero/llms.txt

Demonstrates how to connect to the MCP server and utilize available tools for AI assistant integration. This includes listing threads, getting thread details, managing read status, modifying labels, and building search queries.

```typescript
const threads = await mcpClient.callTool('listThreads', {
  folder: 'inbox',
  maxResults: 10
});

const searchQuery = await mcpClient.callTool('buildGmailSearchQuery', {
  query: 'unread emails from last week about project updates'
});
```

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

### Get User Settings

Source: https://context7.com/mail-0/zero/llms.txt

Retrieves the current user settings and application preferences. This includes language, timezone, dynamic content settings, and more.

```typescript
const settings = await api.settings.get.query();

// { settings: {
//   language: string,
//   timezone: string,
//   dynamicContent: boolean,
//   externalImages: 'always' | 'never' | 'ask',
//   customPrompt: string,
//   trustedSenders: string[],
//   commandPaletteEnabled: boolean,
//   undoSendEnabled: boolean,
//   ...
// }}
```

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

### Register and Execute Dynamic Workflows (TypeScript)

Source: https://github.com/mail-0/zero/blob/staging/apps/server/src/thread-workflow-utils/README.md

Demonstrates how to dynamically discover and execute all registered workflows. The workflow engine provides methods to get all available workflow names and to execute a specific workflow with a given context. Results and errors from the execution are returned.

```typescript
// Get all available workflow names from the engine
const workflowNames = workflowEngine.getWorkflowNames();

// Execute all workflows dynamically
for (const workflowName of workflowNames) {
  const { results, errors } = await workflowEngine.executeWorkflow(workflowName, context);
}
```

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

### Get Thread Details

Source: https://context7.com/mail-0/zero/llms.txt

Fetches complete thread information including all messages, read status, and associated labels.

```APIDOC
## POST /mail/getThread

### Description
Fetches complete thread information including all messages, read status, and associated labels.

### Method
POST

### Endpoint
/mail/getThread

### Parameters
#### Request Body
- **id** (string) - Required - The unique identifier of the thread to retrieve.

### Request Example
```json
{
  "id": "thread_abc123"
}
```

### Response
#### Success Response (200)
- **messages** (array of objects) - An array of parsed message objects within the thread.
- **latest** (object | undefined) - The latest message in the thread.
- **hasUnread** (boolean) - Indicates if the thread has any unread messages.
- **totalReplies** (integer) - The total number of replies in the thread.
- **labels** (array of objects) - A list of labels associated with the thread, each with:
  - **id** (string) - The label ID.
  - **name** (string) - The label name.

#### Response Example
```json
{
  "messages": [
    {
      "id": "message_1",
      "threadId": "thread_abc123",
      "sender": { "email": "sender@example.com", "name": "Sender Name" },
      "to": [{ "email": "recipient@example.com", "name": "Recipient Name" }],
      "subject": "Original Subject",
      "decodedBody": "<p>This is the email body.</p>",
      "date": "2023-10-27T10:00:00Z",
      "isUnread": false
    }
  ],
  "latest": {
    "id": "message_1",
    "threadId": "thread_abc123",
    "sender": { "email": "sender@example.com", "name": "Sender Name" },
    "to": [{ "email": "recipient@example.com", "name": "Recipient Name" }],
    "subject": "Original Subject",
    "decodedBody": "<p>This is the email body.</p>",
    "date": "2023-10-27T10:00:00Z",
    "isUnread": false
  },
  "hasUnread": false,
  "totalReplies": 1,
  "labels": [
    { "id": "label_1", "name": "INBOX" }
  ]
}
```
```

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

### Get and List Email Drafts

Source: https://context7.com/mail-0/zero/llms.txt

Retrieves individual email drafts by ID or lists all drafts with pagination support. Allows specifying the maximum number of results and a page token for fetching subsequent pages.

```typescript
// Get a specific draft
const draft = await api.drafts.get.query({
  id: 'draft_123'
});

// { 
//   id: string,
//   to: string[],
//   subject: string,
//   content: string,
//   cc: string[],
//   bcc: string[]
// }
```

```typescript
// List all drafts
const drafts = await api.drafts.list.query({
  maxResults: 20,
  pageToken: '' // for pagination
});
```

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

### Get Email Attachments

Source: https://context7.com/mail-0/zero/llms.txt

Retrieves attachments from a specific email message.

```APIDOC
## GET /mail/getMessageAttachments

### Description
Retrieves attachments from a specific email message.

### Method
GET

### Endpoint
/mail/getMessageAttachments

### Parameters
#### Query Parameters
- **messageId** (string) - Required - The ID of the message to retrieve attachments from.

### Request Example
```json
{
  "messageId": "message_123"
}
```

### Response
#### Success Response (200)
- **attachments** (array) - An array of attachment objects.
  - **filename** (string) - The name of the attachment file.
  - **mimeType** (string) - The MIME type of the attachment.
  - **size** (number) - The size of the attachment in bytes.
  - **attachmentId** (string) - The unique identifier for the attachment.
  - **body** (string) - The attachment content, base64 encoded.

#### Response Example
```json
[
  {
    "filename": "document.pdf",
    "mimeType": "application/pdf",
    "size": 102400,
    "attachmentId": "att_xyz789",
    "body": "JVBERi0xLjQKJc..."
  }
]
```
```

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

### Set Up Environment Variables (Bash)

Source: https://github.com/mail-0/zero/blob/staging/README.md

These commands are used to manage environment variables for the Zero project. 'pnpm nizzy env' sets up the necessary environment files, and 'pnpm nizzy sync' synchronizes these variables with type definitions, ensuring consistency across the application.

```bash
pnpm nizzy env
pnpm nizzy sync
```

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

### Get Email Attachments

Source: https://context7.com/mail-0/zero/llms.txt

Retrieves attachments from a specific email message. Requires the message ID and returns a list of attachments with their details and base64 encoded body.

```typescript
const attachments = await api.mail.getMessageAttachments.query({
  messageId: 'message_123'
});

// Response structure
// [{
//   filename: string,
//   mimeType: string,
//   size: number,
//   attachmentId: string,
//   body: string (base64 encoded)
// }]
```

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

### Environment Configuration (Bash)

Source: https://context7.com/mail-0/zero/llms.txt

Lists the required environment variables for deploying the Zero application. This includes application URLs, database connection strings, and authentication secrets.

```bash
# Application URLs
VITE_PUBLIC_APP_URL=http://localhost:3000
VITE_PUBLIC_BACKEND_URL=http://localhost:8787

# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/zerodotemail"

# Authentication
BETTER_AUTH_SECRET=your-secret-key  # Use: openssl rand -hex 32
COOKIE_DOMAIN="localhost"
```

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

### Run Custom Script with Arguments

Source: https://github.com/mail-0/zero/blob/staging/scripts/README.md

Demonstrates how to execute a custom script ('my-script') that has been added and registered within the Zero email application's script system. It shows passing a required argument using the command line.

```bash
pnpm scripts my-script --param1 value
```

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

### Environment Configuration

Source: https://context7.com/mail-0/zero/llms.txt

Lists the required environment variables for deploying and running the Zero application.

```APIDOC
## Environment Configuration

### Description
This section details the essential environment variables required for the deployment and operation of the Zero application.

### Required Environment Variables:

```bash
# Application URLs
VITE_PUBLIC_APP_URL=http://localhost:3000
VITE_PUBLIC_BACKEND_URL=http://localhost:8787

# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/zerodotemail"

# Authentication
BETTER_AUTH_SECRET=your-secret-key  # Use: openssl rand -hex 32
COOKIE_DOMAIN="localhost"
```
```

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

### Local PostgreSQL Database Connection String

Source: https://github.com/mail-0/zero/blob/staging/README.md

Specify the DATABASE_URL in the .env file for local development to connect to the PostgreSQL instance. Ensure the connection string matches the database configuration.

```env
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/zerodotemail"
```

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

### Get Thread Details with Zero Mail API

Source: https://context7.com/mail-0/zero/llms.txt

Fetches comprehensive details for a specific email thread, including all associated messages, read status, and labels. This is used to display the full conversation when a user selects a thread. The response includes message content and metadata.

```typescript
// Get a specific thread by ID
const thread = await api.mail.get.query({
  id: 'thread_abc123'
});

// Response structure
// {
//   messages: ParsedMessage[],
//   latest: ParsedMessage | undefined,
//   hasUnread: boolean,
//   totalReplies: number,
//   labels: [{ id: string, name: string }]
// }

// Access thread messages
thread.messages.forEach(message => {
  console.log(`From: ${message.sender.email}`);
  console.log(`Subject: ${message.subject}`);
  console.log(`Body: ${message.decodedBody}`);
});
```

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

### Settings API

Source: https://context7.com/mail-0/zero/llms.txt

Manages user preferences and application settings.

```APIDOC
## Settings API

Manages user preferences and application settings.

### Get Settings

Retrieves current user settings with defaults.

#### GET /settings

##### Description
Retrieves current user settings with defaults.

##### Method
GET

##### Endpoint
/settings

##### Response
###### Success Response (200)
- **settings** (object) - An object containing user settings.
  - **language** (string) - User's preferred language.
  - **timezone** (string) - User's timezone.
  - **dynamicContent** (boolean) - Whether dynamic content is enabled.
  - **externalImages** (string) - Policy for loading external images ('always', 'never', 'ask').
  - **customPrompt** (string) - Custom prompt for AI features.
  - **trustedSenders** (array of strings) - List of trusted sender email addresses.
  - **commandPaletteEnabled** (boolean) - Whether the command palette is enabled.
  - **undoSendEnabled** (boolean) - Whether undo send is enabled.
  - ... (other settings)

###### Response Example
```json
{
  "settings": {
    "language": "en-US",
    "timezone": "America/Los_Angeles",
    "dynamicContent": true,
    "externalImages": "ask",
    "customPrompt": "",
    "trustedSenders": [],
    "commandPaletteEnabled": true,
    "undoSendEnabled": false
  }
}
```

### Save Settings

Updates user preferences (partial updates supported).

#### PUT /settings

##### Description
Updates user preferences (partial updates supported).

##### Method
PUT

##### Endpoint
/settings

##### Parameters
###### Request Body
- **timezone** (string) - Optional - User's timezone.
- **externalImages** (string) - Optional - Policy for loading external images ('always', 'never', 'ask').
- **undoSendEnabled** (boolean) - Optional - Whether undo send is enabled.
- **trustedSenders** (array of strings) - Optional - List of trusted sender email addresses.
- ... (other settable fields)

##### Request Example
```json
{
  "timezone": "America/New_York",
  "externalImages": "always",
  "undoSendEnabled": true,
  "trustedSenders": ["trusted@company.com"]
}
```

##### Response
###### Success Response (200)
- **success** (boolean) - Indicates if the settings were saved successfully.

###### Response Example
```json
{
  "success": true
}
```
```

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

### Database Management Commands

Source: https://github.com/mail-0/zero/blob/staging/README.md

A collection of pnpm commands for managing the PostgreSQL database, including pushing schema changes, generating migrations, applying migrations, and accessing the database studio.

```bash
pnpm db:push
pnpm db:generate
pnpm db:migrate
pnpm db:studio
```

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

### Define and Register a Workflow Definition (TypeScript)

Source: https://github.com/mail-0/zero/blob/staging/apps/server/src/thread-workflow-utils/README.md

Demonstrates how to define a workflow using the WorkflowDefinition type, including its name, description, and a series of steps. Each step has an ID, name, description, enablement status, an optional condition, and an action. The defined workflow is then registered with the workflow engine.

```typescript
const autoDraftWorkflow: WorkflowDefinition = {
  name: 'auto-draft-generation',
  description: 'Automatically generates drafts for threads that require responses',
  steps: [
    {
      id: 'check-draft-eligibility',
      name: 'Check Draft Eligibility',
      description: 'Determines if a draft should be generated for this thread',
      enabled: true,
      condition: async (context) => {
        return shouldGenerateDraft(context.thread, context.foundConnection);
      },
      action: async (context) => {
        console.log('[WORKFLOW_ENGINE] Thread eligible for draft generation', context);
        return { eligible: true };
      },
    },
    // ... more steps
  ],
};

engine.registerWorkflow(autoDraftWorkflow);
```

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

### Configure Google OAuth Credentials

Source: https://github.com/mail-0/zero/blob/staging/README.md

Set up Google OAuth by obtaining client ID and secret from Google Cloud Console. These credentials, along with redirect URIs, are added to the .env file for Gmail integration.

```env
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
```

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

### Seed Style Script Usage

Source: https://github.com/mail-0/zero/blob/staging/scripts/README.md

Illustrates the command-line usage for the 'seed-style' script in the Zero email application. It covers both interactive mode and running with specific command-line options for seeding or resetting the style matrix.

```bash
# Interactive mode (will prompt for options)
pnpm scripts seed-style

# With command-line options
pnpm scripts seed-style seed --connection-id <id> --style <style> --size <number> [--reset]
# Or reset the style matrix
pnpm scripts seed-style reset --connection-id <id>
```

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

### Manage AI Prompts

Source: https://context7.com/mail-0/zero/llms.txt

Allows customization of AI behavior through custom prompts. Users can retrieve all existing prompts or update specific prompts to tailor AI responses.

```typescript
// Get all prompts
const prompts = await api.brain.getPrompts.query();

// Update a specific prompt
await api.brain.updatePrompt.mutate({
  promptType: 'Compose', // or 'Chat', 'Classify', etc.
  content: 'You are a professional email assistant...'
});

// { success: true }
```

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

### Create Label

Source: https://context7.com/mail-0/zero/llms.txt

Creates a new custom label for email organization. Supports optional color customization with background and text colors.

```typescript
await api.labels.create.mutate({
  name: 'Project Alpha',
  color: {
    backgroundColor: '#4285f4',
    textColor: '#ffffff'
  }
});
```

```typescript
// Create label without color
await api.labels.create.mutate({
  name: 'Follow Up'
});
```

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

### Client-Side Thread Actions

Source: https://context7.com/mail-0/zero/llms.txt

Helper utilities for managing thread movements between folders, including moving to archive, spam, or trash.

```APIDOC
## Client-Side Thread Actions

### Description
Helper utilities for managing thread movements between folders. These functions facilitate actions like moving threads to archive, spam, or trash, and retrieving available actions for a given folder.

### Move Threads

**Function:** `moveThreadsTo(options)`

**Parameters:**
- **threadIds** (array of strings) - Required - IDs of the threads to move.
- **currentFolder** (string) - Required - The current folder of the threads.
- **destination** (string) - Required - The destination folder ('archive', 'spam', 'bin').

**Examples:**
```typescript
// Move threads to archive
await moveThreadsTo({
  threadIds: ['thread_123', 'thread_456'],
  currentFolder: 'inbox',
  destination: 'archive'
});

// Move threads to spam
await moveThreadsTo({
  threadIds: ['thread_123'],
  currentFolder: 'inbox',
  destination: 'spam'
});

// Move threads to trash
await moveThreadsTo({
  threadIds: ['thread_123'],
  currentFolder: 'inbox',
  destination: 'bin'
});
```

### Get Available Actions

**Function:** `getAvailableActions(folderName)`

**Parameters:**
- **folderName** (string) - Required - The name of the folder.

**Returns:**
- (array of strings) - A list of available actions for the specified folder.

**Examples:**
```typescript
// Get actions for 'inbox'
const actions = getAvailableActions('inbox');
// Expected output: ['archive', 'spam', 'bin']

// Get actions for 'spam'
const spamActions = getAvailableActions('spam');
// Expected output: ['inbox', 'bin']
```
```

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

### AI Generate Search Query

Source: https://context7.com/mail-0/zero/llms.txt

Converts natural language search into Gmail-compatible search syntax.

```APIDOC
## POST /ai/generateSearchQuery

### Description
Converts natural language search into Gmail-compatible search syntax.

### Method
POST

### Endpoint
/ai/generateSearchQuery

### Parameters
#### Request Body
- **userQuery** (string) - Required - The natural language search query.

### Request Example
```json
{
  "userQuery": "emails from John about the budget sent last month with attachments"
}
```

### Response
#### Success Response (200)
- **query** (string) - The generated Gmail search syntax.

#### Response Example
```json
{
  "query": "from:john subject:budget has:attachment after:2024/11/01 before:2024/12/01"
}
```
```

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

### Package.json Script for Running Zero Mail Scripts

Source: https://github.com/mail-0/zero/blob/staging/scripts/README.md

This JSON snippet from the root package.json defines the command used to execute the Zero email application's utility scripts. It utilizes 'dotenv' for environment variables and specifies the working directory and silent execution.

```json
"scripts": "dotenv -- pnpm run --cwd apps/mail --silent --elide-lines=0 scripts"
```

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

### Save User Settings

Source: https://context7.com/mail-0/zero/llms.txt

Updates user preferences and application settings. Partial updates are supported, meaning only the specified fields need to be provided.

```typescript
await api.settings.save.mutate({
  timezone: 'America/New_York',
  externalImages: 'always',
  undoSendEnabled: true,
  trustedSenders: ['trusted@company.com']
});

// { success: true }
```

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

### Configure Twilio Credentials

Source: https://github.com/mail-0/zero/blob/staging/README.md

Add Twilio Account SID, Auth Token, and Phone Number to the .env file for SMS integration. These details are found on the Twilio dashboard.

```env
TWILIO_ACCOUNT_SID=your_account_sid
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_PHONE_NUMBER=your_twilio_phone_number
```

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

### MCP Integration

Source: https://context7.com/mail-0/zero/llms.txt

Provides Model Context Protocol (MCP) support for AI assistant integration, exposing various tools for email management.

```APIDOC
## MCP Integration

### Description
Zero provides Model Context Protocol (MCP) support for AI assistant integration. This section details the available tools for interacting with email functionalities via MCP.

### MCP Server Tools

**Base URL:** `https://api.0.email/mcp`
**Authentication:** Better Auth session token in `Authorization` header.

**Available Tools:**
- **listThreads**: List emails from folders.
- **getThread**: Get thread details with summary.
- **markThreadsRead/Unread**: Update read status.
- **modifyLabels**: Add/remove labels.
- **bulkDelete**: Move to trash.
- **bulkArchive**: Archive emails.
- **getUserLabels**: List custom labels.
- **createLabel**: Create new labels.
- **getConnections**: List email accounts.
- **setActiveConnection**: Switch accounts.
- **buildGmailSearchQuery**: Natural language to Gmail search query.

### Example MCP Tool Call

```typescript
// Assuming mcpClient is an initialized MCP client instance

// List threads
const threads = await mcpClient.callTool('listThreads', {
  folder: 'inbox',
  maxResults: 10
});

// Build Gmail search query
const searchQuery = await mcpClient.callTool('buildGmailSearchQuery', {
  query: 'unread emails from last week about project updates'
});
```
```

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

### List Labels

Source: https://context7.com/mail-0/zero/llms.txt

Retrieves all user-created labels for the connected account. Returns a list of labels, each with an ID, name, optional color information, and type.

```typescript
const labels = await api.labels.list.query();

// [{
//   id: string,
//   name: string,
//   color: { backgroundColor: string, textColor: string } | undefined,
//   type: string
// }]
```

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

### Templates API

Source: https://context7.com/mail-0/zero/llms.txt

APIs for managing reusable email templates, including creation, listing, and deletion.

```APIDOC
## Templates API

### Description
Manages reusable email templates for quick access. Allows users to store and retrieve email templates.

### Create Template

**Method:** POST
**Endpoint:** `/templates/create`

**Request Body:**
- **name** (string) - Required - The name of the template.
- **subject** (string) - Required - The subject line of the email.
- **body** (string) - Required - The HTML body of the email.
- **to** (array of strings) - Optional - Default recipients.
- **cc** (array of strings) - Optional - Default CC recipients.
- **bcc** (array of strings) - Optional - Default BCC recipients.

### List Templates

**Method:** GET
**Endpoint:** `/templates/list`

**Response Body:**
- **templates** (array) - An array of template objects.

### Delete Template

**Method:** DELETE
**Endpoint:** `/templates/delete`

**Request Body:**
- **id** (string) - Required - The ID of the template to delete.
```

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

### Manage Email Templates (TypeScript)

Source: https://context7.com/mail-0/zero/llms.txt

Enables the creation, listing, and deletion of reusable email templates. Templates can include names, subjects, bodies, and recipient lists.

```typescript
const template = await api.templates.create.mutate({
  name: 'Meeting Follow-up',
  subject: 'Following up on our meeting',
  body: '<p>Thank you for taking the time to meet with me...</p>',
  to: ['team@company.com'],
  cc: ['manager@company.com']
});

const templates = await api.templates.list.query();

await api.templates.delete.mutate({
  id: 'template_123'
});
```

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

### Manage Auto-Labels

Source: https://context7.com/mail-0/zero/llms.txt

Configures automatic labeling rules for emails. Users can retrieve current labels or update them by providing a list of desired labels with their use cases.

```typescript
// Get current labels
const labels = await api.brain.getLabels.query();
// [{ name: string, usecase: string }]

// Update labels
await api.brain.updateLabels.mutate({
  labels: [
    { name: 'Urgent', usecase: 'Emails requiring immediate response' },
    { name: 'Newsletter', usecase: 'Marketing and subscription emails' }
  ]
});
```

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

### Sync Environment Variables Configuration

Source: https://github.com/mail-0/zero/blob/staging/README.md

Configure environment variables related to email synchronization. These include DROP_AGENT_TABLES to clear threads before sync, THREAD_SYNC_MAX_COUNT for batch size, and THREAD_SYNC_LOOP to ensure full folder sync.

```env
DROP_AGENT_TABLES=true
THREAD_SYNC_MAX_COUNT=500
THREAD_SYNC_LOOP=true
```

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

### Create Email Draft

Source: https://context7.com/mail-0/zero/llms.txt

Creates a new email draft that can be edited and sent later. Requires recipient, subject, and body. Optional fields include CC, BCC, and thread ID for replies.

```typescript
const draft = await api.drafts.create.mutate({
  to: ['recipient@example.com'],
  subject: 'Draft Email Subject',
  body: '<p>Draft content here...</p>',
  cc: ['cc@example.com'],
  bcc: [],
  threadId: 'thread_123' // optional, for reply drafts
});

// { id: string, success: boolean }
```

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

### Database Schema

Source: https://context7.com/mail-0/zero/llms.txt

Details the PostgreSQL database schema used by Zero, including key tables like users, connections, notes, and templates.

```APIDOC
## Database Schema

### Description
Zero utilizes a PostgreSQL database managed with Drizzle ORM. This section outlines the structure of key tables and their relationships.

### Key Tables:

**1. User Table**
```typescript
const user = {
  id: 'text primary key',
  name: 'text not null',
  email: 'text unique not null',
  emailVerified: 'boolean',
  image: 'text',
  defaultConnectionId: 'text',
  customPrompt: 'text'
};
```

**2. Connection Table (Email Accounts)**
```typescript
const connection = {
  id: 'text primary key',
  userId: 'text references user(id)',
  email: 'text not null',
  name: 'text',
  providerId: 'google | microsoft',
  accessToken: 'text',
  refreshToken: 'text',
  scope: 'text',
  expiresAt: 'timestamp'
};
```

**3. User Settings Table**
```typescript
const userSettings = {
  id: 'text primary key',
  userId: 'text references user(id)',
  settings: 'jsonb' // includes timezone, language, preferences
};
```

**4. Email Template Table**
```typescript
const emailTemplate = {
  id: 'text primary key',
  userId: 'text references user(id)',
  name: 'text not null',
  subject: 'text',
  body: 'text',
  to: 'jsonb',
  cc: 'jsonb',
  bcc: 'jsonb'
};
```

**5. Note Table (Thread Notes)**
```typescript
const note = {
  id: 'text primary key',
  userId: 'text references user(id)',
  threadId: 'text not null',
  content: 'text',
  color: 'text',
  isPinned: 'boolean',
  order: 'integer'
};
```
```

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

### Notes API

Source: https://context7.com/mail-0/zero/llms.txt

APIs for creating, managing, and organizing notes attached to email threads.

```APIDOC
## Notes API

### Description
Attaches notes to email threads for personal reference. Provides functionality to create, list, update, delete, and reorder notes.

### Create Note

**Method:** POST
**Endpoint:** `/notes/create`

**Request Body:**
- **threadId** (string) - Required - The ID of the thread to attach the note to.
- **content** (string) - Required - The content of the note.
- **color** (string) - Optional - The color of the note (e.g., 'yellow').
- **isPinned** (boolean) - Optional - Whether the note is pinned.

### List Notes

**Method:** GET
**Endpoint:** `/notes/list`

**Query Parameters:**
- **threadId** (string) - Required - The ID of the thread to list notes for.

### Update Note

**Method:** PUT
**Endpoint:** `/notes/update`

**Request Body:**
- **noteId** (string) - Required - The ID of the note to update.
- **data** (object) - Required - The fields to update.
  - **content** (string) - Optional - The new content of the note.
  - **color** (string) - Optional - The new color of the note.
  - **isPinned** (boolean) - Optional - Whether the note is pinned.

### Delete Note

**Method:** DELETE
**Endpoint:** `/notes/delete`

**Request Body:**
- **noteId** (string) - Required - The ID of the note to delete.

### Reorder Notes

**Method:** POST
**Endpoint:** `/notes/reorder`

**Request Body:**
- **notes** (array) - Required - An array of note objects with their new order and pin status.
  - **id** (string) - Required - The ID of the note.
  - **order** (integer) - Required - The new order index.
  - **isPinned** (boolean) - Required - The new pin status.
```

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

### Connections API

Source: https://context7.com/mail-0/zero/llms.txt

Manages email provider connections (Gmail, Outlook) for the user account.

```APIDOC
## Connections API

Manages email provider connections (Gmail, Outlook) for the user account.

### List Connections

Retrieves all connected email accounts.

#### GET /connections

##### Description
Retrieves all connected email accounts.

##### Method
GET

##### Endpoint
/connections

##### Response
###### Success Response (200)
- **connections** (array of objects) - A list of connected email accounts.
  - **id** (string) - Unique identifier for the connection.
  - **email** (string) - The email address.
  - **name** (string) - The name associated with the account.
  - **picture** (string) - URL to the user's profile picture.
  - **createdAt** (Date) - Timestamp when the connection was created.
  - **providerId** (string) - The email provider ('google' or 'microsoft').
- **disconnectedIds** (array of strings) - List of IDs for disconnected accounts.

###### Response Example
```json
{
  "connections": [
    {
      "id": "connection_123",
      "email": "user@gmail.com",
      "name": "User Name",
      "picture": "http://example.com/pic.jpg",
      "createdAt": "2023-01-01T10:00:00Z",
      "providerId": "google"
    }
  ],
  "disconnectedIds": []
}
```

### Set Default Connection

Sets the primary email connection for the user.

#### PUT /connections/default

##### Description
Sets the primary email connection for the user.

##### Method
PUT

##### Endpoint
/connections/default

##### Parameters
###### Request Body
- **connectionId** (string) - Required - The ID of the connection to set as default.

##### Request Example
```json
{
  "connectionId": "connection_123"
}
```

### Delete Connection

Removes an email provider connection.

#### DELETE /connections/{connectionId}

##### Description
Removes an email provider connection.

##### Method
DELETE

##### Endpoint
/connections/{connectionId}

##### Parameters
###### Path Parameters
- **connectionId** (string) - Required - The ID of the connection to delete.

##### Request Example
```json
{
  "connectionId": "connection_123"
}
```
```

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

### Manage Email Notes (TypeScript)

Source: https://context7.com/mail-0/zero/llms.txt

Provides functions to create, list, update, delete, and reorder notes attached to email threads. These operations interact with an API to persist note data.

```typescript
const note = await api.notes.create.mutate({
  threadId: 'thread_123',
  content: 'Remember to follow up on Friday',
  color: 'yellow',
  isPinned: true
});

const notes = await api.notes.list.query({
  threadId: 'thread_123'
});

await api.notes.update.mutate({
  noteId: 'note_123',
  data: {
    content: 'Updated note content',
    color: 'blue',
    isPinned: false
  }
});

await api.notes.delete.mutate({
  noteId: 'note_123'
});

await api.notes.reorder.mutate({
  notes: [
    { id: 'note_123', order: 0, isPinned: true },
    { id: 'note_456', order: 1, isPinned: false }
  ]
});
```

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

### Generate Email Summary with AI

Source: https://context7.com/mail-0/zero/llms.txt

Creates an AI-generated summary for a given email thread. This helps users quickly grasp the main points of a conversation without reading the entire thread.

```typescript
const summary = await api.brain.generateSummary.query({
  threadId: 'thread_123'
});

// { data: { short: string } } or null if not available
```

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

### Generate Search Query for Gmail

Source: https://context7.com/mail-0/zero/llms.txt

Converts natural language search queries into Gmail-compatible search syntax. This allows users to search their emails using conversational language.

```typescript
const query = await api.ai.generateSearchQuery.mutate({
  userQuery: 'emails from John about the budget sent last month with attachments'
});

// Returns Gmail search syntax like:
// "from:john subject:budget has:attachment after:2024/11/01 before:2024/12/01"
```

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

### AI API

Source: https://context7.com/mail-0/zero/llms.txt

Provides AI-powered features for email composition and search query generation.

```APIDOC
## AI API

### Description
Provides AI-powered features for email composition and search query generation.

### Endpoints
(Specific AI API endpoints are not detailed in the provided text, but this section serves as a placeholder for future documentation.)
```

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

### Client-Side Thread Actions (TypeScript)

Source: https://context7.com/mail-0/zero/llms.txt

Provides utility functions for managing email threads on the client side, specifically for moving threads between folders (archive, spam, trash) and retrieving available actions for a given folder.

```typescript
import { moveThreadsTo, getAvailableActions } from '@/lib/thread-actions';

await moveThreadsTo({
  threadIds: ['thread_123', 'thread_456'],
  currentFolder: 'inbox',
  destination: 'archive'
});

await moveThreadsTo({
  threadIds: ['thread_123'],
  currentFolder: 'inbox',
  destination: 'spam'
});

await moveThreadsTo({
  threadIds: ['thread_123'],
  currentFolder: 'inbox',
  destination: 'bin'
});

const actions = getAvailableActions('inbox');

const spamActions = getAvailableActions('spam');
```

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

### Database Schema Definition (TypeScript)

Source: https://context7.com/mail-0/zero/llms.txt

Defines the structure of key tables in the PostgreSQL database used by Zero, including users, connections, sessions, notes, templates, and settings. This uses Drizzle ORM syntax.

```typescript
const user = {
  id: 'text primary key',
  name: 'text not null',
  email: 'text unique not null',
  emailVerified: 'boolean',
  image: 'text',
  defaultConnectionId: 'text',
  customPrompt: 'text'
};

const connection = {
  id: 'text primary key',
  userId: 'text references user(id)',
  email: 'text not null',
  name: 'text',
  providerId: 'google | microsoft',
  accessToken: 'text',
  refreshToken: 'text',
  scope: 'text',
  expiresAt: 'timestamp'
};

const userSettings = {
  id: 'text primary key',
  userId: 'text references user(id)',
  settings: 'jsonb'
};

const emailTemplate = {
  id: 'text primary key',
  userId: 'text references user(id)',
  name: 'text not null',
  subject: 'text',
  body: 'text',
  to: 'jsonb',
  cc: 'jsonb',
  bcc: 'jsonb'
};

const note = {
  id: 'text primary key',
  userId: 'text references user(id)',
  threadId: 'text not null',
  content: 'text',
  color: 'text',
  isPinned: 'boolean',
  order: 'integer'
};
```

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

### Compose Email with AI

Source: https://context7.com/mail-0/zero/llms.txt

Generates email content using AI based on a prompt and optional thread context. It can draft new emails or reply to existing threads. The output is an HTML-formatted email body.

```typescript
const result = await api.ai.compose.mutate({
  prompt: 'Write a professional response declining the meeting invitation politely',
  emailSubject: 'Re: Meeting Request',
  to: ['sender@example.com'],
  threadMessages: [
    {
      from: 'sender@example.com',
      to: ['me@example.com'],
      subject: 'Meeting Request',
      body: 'Can we schedule a meeting next week to discuss the project?'
    }
  ]
});

// { newBody: string } - HTML formatted email body

// Generate email without context
const newEmail = await api.ai.compose.mutate({
  prompt: 'Draft an introduction email for a job application to a software company'
});
```

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

### List Email Connections

Source: https://context7.com/mail-0/zero/llms.txt

Retrieves a list of all connected email accounts for the user, including details like email address, name, and provider. It also returns IDs of disconnected accounts.

```typescript
const result = await api.connections.list.query();

// {
//   connections: [{
//     id: string,
//     email: string,
//     name: string,
//     picture: string,
//     createdAt: Date,
//     providerId: 'google' | 'microsoft'
//   }],
//   disconnectedIds: string[]
// }
```

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

### AI Generate Email Subject

Source: https://context7.com/mail-0/zero/llms.txt

Creates a professional subject line based on email content.

```APIDOC
## POST /ai/generateEmailSubject

### Description
Creates a professional subject line based on email content.

### Method
POST

### Endpoint
/ai/generateEmailSubject

### Parameters
#### Request Body
- **message** (string) - Required - The content of the email message.

### Request Example
```json
{
  "message": "Hi team, I wanted to follow up on the quarterly report we discussed last week..."
}
```

### Response
#### Success Response (200)
- **subject** (string) - The generated email subject line.

#### Response Example
```json
{
  "subject": "Following Up: Quarterly Report Discussion"
}
```
```

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

### Send Email

Source: https://context7.com/mail-0/zero/llms.txt

Sends a new email with support for attachments, CC/BCC recipients, thread replies, and scheduled sending.

```APIDOC
## POST /mail/send

### Description
Sends a new email with support for attachments, CC/BCC recipients, thread replies, and scheduled sending.

### Method
POST

### Endpoint
/mail/send

### Parameters
#### Request Body
- **to** (array of objects) - Required - Recipients of the email. Each object should have:
  - **email** (string) - Required - Recipient's email address.
  - **name** (string) - Optional - Recipient's name.
- **cc** (array of objects) - Optional - CC recipients.
- **bcc** (array of objects) - Optional - BCC recipients.
- **subject** (string) - Required - The subject of the email.
- **message** (string) - Required - The HTML or plain text body of the email.
- **threadId** (string) - Optional - If replying to an existing thread, provide the thread ID.
- **attachments** (array of objects) - Optional - Attachments for the email.
- **scheduleAt** (string) - Optional - ISO 8601 formatted date string for scheduling the email.
- **headers** (object) - Optional - Custom headers for the email, useful for replies (e.g., 'In-Reply-To', 'References').

### Request Example
```json
{
  "to": [{ "email": "recipient@example.com", "name": "John Doe" }],
  "subject": "Hello from Zero",
  "message": "<p>This is the email body in HTML format.</p>",
  "attachments": [],
  "threadId": "thread_abc123",
  "scheduleAt": "2024-12-25T10:00:00Z",
  "headers": {
    "In-Reply-To": "<original-message-id>",
    "References": "<original-message-id>"
  }
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the email was successfully queued or sent.
- **queued** (boolean) - Indicates if the email has been queued for sending (especially for scheduled emails).
- **messageId** (string) - The unique identifier of the sent or queued email.
- **sendAt** (number) - The timestamp (in milliseconds) when the email is scheduled to be sent.

#### Response Example
```json
{
  "success": true,
  "queued": true,
  "messageId": "message_xyz789",
  "sendAt": 1735096800000
}
```
```

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

### Define a Workflow Step with Error Handling (TypeScript)

Source: https://github.com/mail-0/zero/blob/staging/apps/server/src/thread-workflow-utils/README.md

Shows the structure for defining a single step within a workflow. It includes an ID, name, description, enablement status, an action function, and an optional error handling strategy. The errorHandling property can be set to 'continue', 'fail', or 'retry'.

```typescript
{
  id: 'my-new-step',
  name: 'My New Step',
  description: 'Description of what this step does',
  enabled: true,
  action: async (context) => {
    // Your logic here
    return { success: true };
  },
  errorHandling: 'continue',
}
```

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

### Generate Email Subject with AI

Source: https://context7.com/mail-0/zero/llms.txt

Creates a professional email subject line based on the provided email message content. This helps in organizing and quickly understanding the email's purpose.

```typescript
const subject = await api.ai.generateEmailSubject.mutate({
  message: 'Hi team, I wanted to follow up on the quarterly report we discussed last week...'
});

// { subject: string }
```

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

### Bulk Operations

Source: https://context7.com/mail-0/zero/llms.txt

Performs bulk actions on multiple email threads, including delete, archive, and mute. Also includes an endpoint to delete all spam.

```APIDOC
## POST /mail/bulkDelete

### Description
Performs a bulk delete operation, moving multiple email threads to the trash.

### Method
POST

### Endpoint
/mail/bulkDelete

### Parameters
#### Request Body
- **ids** (string[]) - Required - The IDs of the threads to delete.

### Request Example
```json
{
  "ids": ["thread_123", "thread_456", "thread_789"]
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "success": true
}
```

## POST /mail/bulkArchive

### Description
Performs a bulk archive operation on multiple email threads.

### Method
POST

### Endpoint
/mail/bulkArchive

### Parameters
#### Request Body
- **ids** (string[]) - Required - The IDs of the threads to archive.

### Request Example
```json
{
  "ids": ["thread_123", "thread_456"]
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "success": true
}
```

## POST /mail/bulkMute

### Description
Performs a bulk mute operation on multiple email threads.

### Method
POST

### Endpoint
/mail/bulkMute

### Parameters
#### Request Body
- **ids** (string[]) - Required - The IDs of the threads to mute.

### Request Example
```json
{
  "ids": ["thread_123"]
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "success": true
}
```

## POST /mail/deleteAllSpam

### Description
Deletes all spam emails.

### Method
POST

### Endpoint
/mail/deleteAllSpam

### Parameters
No parameters required.

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **message** (string) - A message describing the result of the operation.
- **count** (number) - The number of spam emails deleted.

#### Response Example
```json
{
  "success": true,
  "message": "All spam emails have been deleted.",
  "count": 50
}
```
```