# Osprey Documentation

> Osprey is company email where humans and AI work together. Connect your domain, create mailboxes, and deploy AI agents that automate email workflows.

Generated: 2026-02-18T04:14:47.152Z
Source: https://docs.osprey.sh

---

# Introduction

> Learn how to set up company email where humans and AI agents work together.

Osprey is company email built for teams that want humans and AI to work side by side. Connect your domain, create mailboxes for your team, and deploy AI agents that can read, process, and respond to email automatically.

## What you can do

- **Connect your domain** — Add DNS records and start receiving email in minutes
- **Create mailboxes** — Set up addresses for employees and departments
- **Deploy agents** — AI-powered mailboxes that automate workflows like invoice processing, support tickets, and sales inquiries
- **Integrate tools** — Connect Slack, QuickBooks, your CRM, and more

## Quick links

| Section | Description |
| --- | --- |
| [Quickstart](/docs/getting-started/quickstart) | Get up and running in 5 minutes |
| [Domains](/docs/domains) | Add and verify your custom domain |
| [Mailboxes](/docs/mailboxes) | Create email addresses for your team |
| [Agents](/docs/agents) | Set up AI agents that work autonomously |
| [API Reference](/api/reference) | Full API documentation |

## How it works

1. **Sign up** and create your organization
2. **Add your domain** (e.g., `acme.com`) and configure DNS
3. **Create mailboxes** for team members (`sarah@acme.com`) or agents (`invoices@acme.com`)
4. **Configure agents** with plain-English instructions and tool integrations
5. **Monitor activity** in the dashboard or via webhooks

Ready to get started? Head to the [Quickstart guide](/docs/getting-started/quickstart).

---

# Quickstart

> Get your first Osprey mailbox up and running in 5 minutes.

Get from zero to sending email in 5 minutes.

## Step 1: Create your organization

After signing up, you'll be prompted to create an organization. This is your workspace — all domains, mailboxes, and settings live here.

Enter your company name and you're ready to go.

## Step 2: Add your domain

Navigate to **Domains** and click **Add Domain**.

Enter your domain (e.g., `acme.com`).

> **Tip:** If your domain is on Cloudflare, connect your API token and we'll configure DNS automatically. No manual record entry needed.

For other DNS providers, you'll see the records to add manually:

| Type | Name | Value |
| --- | --- | --- |
| MX | @ | `mail.mailsio.com` (priority 10) |
| TXT | @ | `v=spf1 include:mail.mailsio.com ~all` |
| TXT | `_dmarc` | `v=DMARC1; p=none; rua=mailto:dmarc@acme.com` |
| TXT | `osprey._domainkey` | *(your DKIM key — shown in dashboard)* |

Click **Verify** once records propagate (usually 1-5 minutes).

## Step 3: Create a mailbox

Go to **Mailboxes** and click **Create Mailbox**.

- **Email**: Enter the local part (e.g., `hello` for `hello@acme.com`)
- **Type**: Choose `Human` for team members or `Agent` for AI automation
- **Password**: Set a secure password (min 12 characters)

Click **Create** and your mailbox is live.

## Step 4: Send your first email

You can now:

- **Use webmail** at `mail.osprey.sh` with your new credentials
- **Configure IMAP/SMTP** in any email client:
  - IMAP: `mail.mailsio.com:993` (SSL/TLS)
  - SMTP: `mail.mailsio.com:587` (STARTTLS)
- **Send via API** — see the [API Reference](/api/reference)

## Next steps

- [Create an agent mailbox](/docs/agents) that processes email automatically
- [Connect integrations](/docs/agents/instructions) like Slack or QuickBooks
- [Explore the API](/api/reference) for programmatic access

---

# Core Concepts

> Understand the building blocks of Osprey — organizations, domains, mailboxes, and agents.

Osprey is built around a few simple concepts. Understanding these will help you get the most out of the platform.

## Organizations

An **organization** is your workspace. It contains all your domains, mailboxes, team members, and settings.

- One organization = one company/team
- All billing is at the organization level
- Team members can be invited with different roles (admin, member)

## Domains

A **domain** is your email identity (e.g., `acme.com`). Before you can create mailboxes, you need to:

1. Add the domain to Osprey
2. Configure DNS records (MX, SPF, DKIM, DMARC)
3. Verify ownership

Once verified, you can create unlimited mailboxes on that domain.

## Mailboxes

A **mailbox** is an email address that can send and receive mail. There are two types:

### Human mailboxes

Standard email accounts for your team members.

- `sarah@acme.com` — Sarah's work email
- `support@acme.com` — Shared team inbox

Human mailboxes work with any email client via IMAP/SMTP, or through the Osprey webmail interface.

### Agent mailboxes

AI-powered mailboxes that process email automatically.

- `invoices@acme.com` — Extracts data from invoices, saves to QuickBooks
- `support@acme.com` — Categorizes tickets, drafts responses, escalates when needed
- `sales@acme.com` — Qualifies leads, enriches contacts, schedules meetings

Agent mailboxes have:

- **Instructions** — Plain-English rules for how to handle email
- **Integrations** — Connected tools like Slack, QuickBooks, CRMs
- **Approval flows** — Human-in-the-loop for sensitive actions

## Integrations

Integrations connect Osprey to your existing tools:

- **Cloudflare** — Auto-configure DNS records
- **QuickBooks** — Create bills from invoices
- **Slack** — Send notifications, request approvals
- **Google Drive** — Save attachments
- **CRMs** — Update contacts and deals

Agents can use any connected integration to take actions based on incoming email.

## API

Everything in Osprey is available via API:

- Create/manage domains and mailboxes
- Send email programmatically
- Query activity logs and agent traces
- Set up webhooks for real-time events

See the [API Reference](/api/reference) for full documentation.

---

# DNS Configuration

> Configure DNS records to enable email delivery for your domain

After adding your domain to Osprey, you need to configure DNS records to enable email delivery. This guide walks you through the required records and how to set them up.

## Required DNS Records

Osprey requires several DNS records to send and receive email on your domain:

| Record Type | Purpose |
|-------------|---------|
| **MX** | Routes incoming email to Osprey's mail servers |
| **SPF** | Authorizes Osprey to send email on your behalf |
| **DKIM** | Cryptographically signs outgoing emails |
| **DMARC** | Defines policy for handling authentication failures |

## Automatic Setup with Cloudflare

If you connect your Cloudflare account, Osprey can automatically configure all required DNS records for you.

1. Go to **Settings > Integrations**
2. Click **Connect Cloudflare**
3. Enter your Cloudflare API token (we'll help you create one with the right permissions)
4. Select the zone for your domain
5. Click **Auto-configure DNS**

> **Note:** Cloudflare integration requires a token with Zone Read and DNS Edit permissions.

## Manual DNS Setup

If you prefer to configure DNS manually, add the following records at your DNS provider:

### MX Record

Routes incoming email to Osprey:

```
Type: MX
Host: @
Value: mail.osprey.sh
Priority: 10
TTL: 3600
```

### SPF Record

Authorizes Osprey to send email:

```
Type: TXT
Host: @
Value: v=spf1 include:_spf.osprey.sh ~all
TTL: 3600
```

> **Warning:** If you already have an SPF record, merge it by adding `include:_spf.osprey.sh` to your existing record. Only one SPF record is allowed per domain.

### DKIM Record

Osprey generates a unique DKIM key for each domain. Find your DKIM record in the Osprey dashboard:

1. Go to **Domains**
2. Click on your domain
3. Copy the DKIM record shown

The record will look like:

```
Type: TXT
Host: osprey._domainkey
Value: v=DKIM1; k=rsa; p=MIIBIjANBgkqh...
TTL: 3600
```

### DMARC Record

Defines how receiving servers should handle authentication failures:

```
Type: TXT
Host: _dmarc
Value: v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com
TTL: 3600
```

> **Note:** Start with `p=none` to monitor without affecting delivery, then move to `p=quarantine` or `p=reject` once you confirm everything works.

## Verifying DNS Configuration

After adding records, verify them in the Osprey dashboard:

1. Go to **Domains**
2. Click on your domain
3. Click **Verify DNS**

DNS changes can take up to 48 hours to propagate, but typically complete within a few minutes.

### Verification Status

| Status | Meaning |
|--------|---------|
| **Pending** | Records not yet detected |
| **Verified** | All records configured correctly |
| **Partial** | Some records missing or incorrect |
| **Error** | Configuration problem detected |

## Troubleshooting

### Records not found after 24 hours

- Double-check record values for typos
- Ensure you're editing the correct DNS zone
- Try a DNS lookup tool like [MXToolbox](https://mxtoolbox.com)

### SPF record conflicts

If you have multiple email providers, combine them in one SPF record:

```
v=spf1 include:_spf.osprey.sh include:_spf.google.com ~all
```

### DKIM signature failures

- Ensure the full DKIM value is copied (it's long)
- Check that your DNS provider doesn't truncate TXT records
- Some providers require removing quotes from the value

## Next Steps

Once DNS is verified:

- [Create mailboxes](/docs/mailboxes/create-mailbox) for your team
- [Set up agents](/docs/agents) to handle incoming email

---

# Domains

> Add and configure custom email domains in Osprey.

Domains are the foundation of your email setup. Before creating mailboxes, you need to add and verify at least one domain.

## In this section

- [Add a Domain](/docs/domains/add-domain) — Register your domain with Osprey
- [DNS Configuration](/docs/domains/dns-setup) — Set up MX, SPF, DKIM, and DMARC records

## Overview

When you add a domain to Osprey, we:

1. **Generate DNS records** — MX for mail routing, TXT for authentication
2. **Create DKIM keys** — Unique signing keys for your domain
3. **Monitor verification** — Check that records are configured correctly
4. **Enable mail flow** — Once verified, you can create mailboxes

## Domain requirements

- You must own the domain or have permission to modify its DNS
- The domain cannot already be configured with another email provider's MX records (unless you're migrating)
- Subdomains work too (e.g., `mail.acme.com`)

## Cloudflare integration

If your domain uses Cloudflare for DNS, you can connect your Cloudflare API token and we'll configure everything automatically:

1. Go to **Settings** → **Integrations** → **Cloudflare**
2. Add your API token with Zone:Read and DNS:Edit permissions
3. When adding a domain, select it from your Cloudflare zones
4. Click **Auto-configure** — done in seconds

For non-Cloudflare domains, see [DNS Configuration](/docs/domains/dns-setup) for manual setup instructions.

---

# Add a Domain

> Step-by-step guide to adding your domain to Osprey.

This guide walks you through adding a domain to Osprey.

## Prerequisites

- Access to your domain's DNS settings
- (Optional) Cloudflare API token for auto-configuration

## Steps

### 1. Navigate to Domains

From your dashboard, click **Domains** in the sidebar, then click **Add Domain**.

### 2. Enter your domain

Type your domain name (e.g., `acme.com`) and click **Continue**.

> **Note:** You can also add subdomains like `mail.acme.com` if you want to keep your main domain's email separate.

### 3. Configure DNS

You'll see the required DNS records. You have two options:

**Option A: Cloudflare auto-config**

If you've connected Cloudflare, click **Auto-configure DNS** and we'll add all records automatically.

**Option B: Manual setup**

Copy each record and add it to your DNS provider:

- **MX record** — Routes incoming mail to Osprey
- **SPF record** — Authorizes Osprey to send on your behalf
- **DKIM record** — Signs outgoing mail for authenticity
- **DMARC record** — Tells receivers how to handle authentication failures

### 4. Verify

Click **Verify Domain**. We'll check that all records are configured correctly.

- Green checkmarks = record found and correct
- Red X = record missing or incorrect

> **Warning:** DNS changes can take 1-5 minutes to propagate. If verification fails, wait a few minutes and try again.

### 5. Done

Once all records are verified, your domain is active. You can now create mailboxes on this domain.

## Troubleshooting

**MX record not found**
- Ensure priority is set (usually 10)
- Check for typos in the mail server address

**SPF record not found**
- Make sure it's a TXT record, not SPF type
- Only one SPF record allowed per domain — merge if needed

**DKIM record not found**
- The selector must match exactly (e.g., `osprey._domainkey`)
- Long DKIM values may need to be split into multiple strings

**DMARC record not found**
- Must be at `_dmarc.yourdomain.com`
- Start with `p=none` for monitoring before enforcing

---

# Mailboxes

> Create and manage email addresses for your team and AI agents

Mailboxes are email addresses on your domain. In Osprey, mailboxes can belong to humans or AI agents — they're both just users with email addresses.

## What is a Mailbox?

A mailbox is an email address like `rob@yourcompany.com` or `invoices@yourcompany.com`. Each mailbox:

- Receives incoming email
- Can send outgoing email
- Has its own inbox, sent folder, and drafts
- Belongs to either a human user or an AI agent

## Human vs Agent Mailboxes

| | Human Mailboxes | Agent Mailboxes |
|---|-----------------|-----------------|
| **Owner** | Team member | AI agent |
| **Access** | Web app, IMAP, mobile | API, webhooks |
| **Example** | `sarah@company.com` | `support@company.com` |
| **Processing** | Manual | Automated |

## Mailbox Features

### For Humans

- Full inbox with search and filters
- Compose and reply to emails
- Mobile access via IMAP
- Delegate to agents when needed

### For Agents

- Automatic email processing
- Custom handling logic per agent
- Escalation to humans when uncertain
- Full audit trail of actions

## Getting Started

1. [Create a mailbox](/docs/mailboxes/create-mailbox) for a team member or agent
2. Configure access and permissions
3. Start sending and receiving email

## Common Patterns

### Shared Inboxes

Create mailboxes like `support@` or `sales@` and assign an AI agent to handle initial triage, with escalation to humans for complex issues.

### Personal + Agent Pairs

Each team member can have a personal agent that helps manage their inbox, draft replies, and handle routine correspondence.

### Department Mailboxes

Create department-wide mailboxes (`engineering@`, `hr@`) that route to the appropriate team members or agents based on content.

---

# Create a Mailbox

> Set up email addresses for team members and AI agents

This guide walks you through creating mailboxes for your team members and AI agents.

## Prerequisites

Before creating a mailbox, you need:

- A verified domain in Osprey
- Admin access to your organization

## Creating a Human Mailbox

Human mailboxes are for team members who will access email through the Osprey web app or IMAP.

### From the Dashboard

1. Go to **Mailboxes** in the sidebar
2. Click **Create Mailbox**
3. Select **Human** as the type
4. Enter the email address (e.g., `sarah`)
5. Select the domain from the dropdown
6. Enter the display name
7. Click **Create**

### Invite the User

After creating the mailbox, invite the team member:

1. Click on the mailbox
2. Click **Invite User**
3. Enter their personal email address
4. They'll receive an invitation to join your organization

> **Note:** Team members sign in with their personal email (via Clerk) and can then access their company mailbox.

## Creating an Agent Mailbox

Agent mailboxes are managed by AI and process email automatically.

### From the Dashboard

1. Go to **Mailboxes** in the sidebar
2. Click **Create Mailbox**
3. Select **Agent** as the type
4. Enter the email address (e.g., `support`)
5. Select the domain
6. Enter a display name (e.g., "Support Team")
7. Click **Create**

### Configure the Agent

After creating the mailbox, configure the agent:

1. Click on the mailbox
2. Go to the **Agent** tab
3. Select the AI model (e.g., Claude, GPT-4)
4. Define the agent's behavior and capabilities
5. Set up escalation rules

See [Create an Agent](/docs/agents/create-agent) for detailed agent configuration.

## Via API

You can also create mailboxes programmatically:

```bash
curl -X POST https://api.osprey.sh/api/mailboxes \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "support",
    "domain": "yourcompany.com",
    "displayName": "Support Team",
    "type": "agent"
  }'
```

## Mailbox Settings

After creating a mailbox, configure these settings:

### General

- **Display Name**: Shown in the "From" field
- **Signature**: Appended to outgoing emails
- **Timezone**: For scheduling and timestamps

### Access

- **Forwarding**: Forward copies to another address
- **Aliases**: Alternative addresses that deliver to this mailbox
- **IMAP Access**: Enable/disable IMAP for this mailbox

### Agent Settings (Agent mailboxes only)

- **Model**: Which AI model powers the agent
- **System Prompt**: Instructions for the agent
- **Capabilities**: What the agent can do
- **Escalation**: When to involve humans

## Limits

| Plan | Mailboxes |
|------|-----------|
| Free | 5 |
| Pro | 50 |
| Enterprise | Unlimited |

> **Warning:** Deleting a mailbox is permanent. All emails in that mailbox will be lost.

## Next Steps

- [Manage mailboxes](/docs/mailboxes/manage-mailboxes) — Edit, disable, or delete mailboxes
- [Create an agent](/docs/agents/create-agent) — Configure AI for agent mailboxes

---

# Manage Mailboxes

> Edit, disable, and delete mailboxes in your organization

Learn how to manage existing mailboxes in your Osprey organization.

## Viewing Mailboxes

Go to **Mailboxes** in the sidebar to see all mailboxes in your organization:

- **Active**: Mailboxes currently receiving and sending email
- **Paused**: Agent mailboxes that are temporarily disabled
- **All**: Complete list including disabled mailboxes

## Editing a Mailbox

1. Click on any mailbox to open its settings
2. Make your changes
3. Click **Save**

### Editable Settings

| Setting | Description |
|---------|-------------|
| Display Name | Name shown in sent emails |
| Signature | Text appended to outgoing messages |
| Forwarding | Copy incoming mail to another address |
| Auto-reply | Vacation or out-of-office messages |

> **Note:** The email address itself cannot be changed. To use a different address, create a new mailbox.

## Pausing an Agent Mailbox

Temporarily stop an agent from processing emails:

1. Go to the mailbox settings
2. Click **Pause Agent**
3. The agent stops processing; emails queue up
4. Click **Resume** when ready

Paused agents:
- Still receive email (stored in inbox)
- Don't send automatic replies
- Don't trigger any actions
- Can be manually managed by humans

## Forwarding

Set up email forwarding to copy incoming messages to another address:

1. Open mailbox settings
2. Go to **Forwarding**
3. Enter the destination email address
4. Choose whether to keep a copy in Osprey
5. Click **Save**

### Forwarding Options

- **Keep copy**: Store in Osprey and forward
- **Forward only**: Don't store in Osprey (forward-only)
- **Conditional**: Forward based on rules (e.g., only certain senders)

## Aliases

Add alternative addresses that deliver to the same mailbox:

1. Open mailbox settings
2. Go to **Aliases**
3. Click **Add Alias**
4. Enter the alias (e.g., `info` for `info@yourcompany.com`)
5. Click **Save**

Common alias patterns:
- `support` → `help`, `contact`
- `sales` → `info`, `hello`
- `john.smith` → `jsmith`, `john`

## Auto-Reply

Set up automatic responses for vacations or out-of-office:

1. Open mailbox settings
2. Go to **Auto-Reply**
3. Enable auto-reply
4. Set start and end dates
5. Write your message
6. Click **Save**

> **Warning:** Auto-replies only send once per sender during the active period to avoid reply loops.

## Disabling a Mailbox

Disable a mailbox to stop all email activity:

1. Open mailbox settings
2. Click **Disable Mailbox**
3. Confirm the action

Disabled mailboxes:
- Reject incoming email (bounces back to sender)
- Cannot send email
- Preserve all existing emails
- Can be re-enabled anytime

## Deleting a Mailbox

> **Warning:** Deleting a mailbox is permanent and cannot be undone. All emails will be lost.

To delete a mailbox:

1. Open mailbox settings
2. Click **Delete Mailbox**
3. Type the email address to confirm
4. Click **Delete Forever**

Before deleting, consider:
- Exporting important emails
- Forwarding to another mailbox
- Disabling instead of deleting

## Bulk Operations

Select multiple mailboxes to perform bulk actions:

1. Check the boxes next to mailboxes
2. Click **Actions**
3. Choose an action:
   - **Disable Selected**
   - **Enable Selected**
   - **Export Selected**

## Audit Log

View the activity history for any mailbox:

1. Open mailbox settings
2. Go to **Activity**
3. See all actions: sent, received, agent actions, settings changes

Filter by:
- Date range
- Action type
- User who made changes

## Next Steps

- [Set up agents](/docs/agents) to automate mailbox handling
- [Configure DNS](/docs/domains/dns-setup) for email delivery

---

# AI Agents

> Automate email handling with AI-powered agents

Agents are AI-powered email handlers that automatically process incoming messages, draft responses, and take actions on behalf of your team.

## What is an Agent?

An agent is an AI that manages an email address. When email arrives at an agent's mailbox, the AI:

1. Reads and understands the message
2. Decides how to handle it based on your configuration
3. Takes action: reply, forward, categorize, or escalate

Agents can handle everything from simple auto-responses to complex multi-step workflows.

## Why Use Agents?

### Handle Volume

Agents can process hundreds of emails instantly, ensuring no message waits for human attention.

### Consistent Quality

Every response follows your guidelines. No variation in tone, no forgotten details, no delays.

### 24/7 Availability

Agents work around the clock. Customers get immediate responses regardless of timezone.

### Focus Human Effort

Agents handle routine inquiries, freeing your team for complex, high-value conversations.

## Agent Capabilities

Agents can:

| Capability | Example |
|------------|---------|
| **Reply** | Answer FAQs, acknowledge receipts |
| **Categorize** | Tag and organize incoming email |
| **Forward** | Route to the right team member |
| **Escalate** | Flag urgent issues for humans |
| **Extract** | Pull data from emails (invoices, orders) |
| **Create** | Generate tickets, tasks, records |
| **Research** | Look up information before responding |

## Agent Architecture

```
Incoming Email → Agent → [Understand] → [Decide] → [Act]
                                              ↓
                                    - Reply
                                    - Forward  
                                    - Escalate
                                    - Extract data
                                    - Create record
```

## Getting Started

1. [Create an agent](/docs/agents/create-agent) attached to a mailbox
2. Define what the agent can do
3. Set escalation rules for edge cases
4. Test with sample emails
5. Go live

## Example Use Cases

### Customer Support

An agent at `support@` answers common questions, troubleshoots issues, and creates tickets in your helpdesk for complex problems.

### Invoice Processing

An agent at `invoices@` extracts data from incoming invoices, validates amounts, and creates records in your accounting system.

### Lead Qualification

An agent at `sales@` responds to inquiries, qualifies leads based on criteria, and schedules meetings for promising prospects.

### HR Inquiries

An agent at `hr@` answers policy questions, routes requests to appropriate team members, and handles benefits inquiries.

## Human-Agent Collaboration

Agents aren't meant to replace humans — they work alongside your team:

- **Drafts for Review**: Agent drafts responses; humans approve before sending
- **Escalation**: Agent handles routine tasks; complex issues go to humans
- **Supervised Learning**: Humans correct agent mistakes; agent improves over time
- **Takeover**: Humans can jump in and handle any conversation directly

## Next Steps

- [Create an agent](/docs/agents/create-agent) for your first mailbox
- Learn about [agent capabilities](/docs/agents/capabilities) in detail

---

# Create an Agent

> Set up an AI agent to handle email automatically

This guide walks you through creating and configuring an AI agent to handle email for a mailbox.

## Prerequisites

Before creating an agent, you need:

- A mailbox with type "Agent" (see [Create a Mailbox](/docs/mailboxes/create-mailbox))
- Admin access to your organization

## Step 1: Open Agent Settings

1. Go to **Mailboxes** in the sidebar
2. Click on your agent mailbox
3. Go to the **Agent** tab

## Step 2: Choose an AI Model

Select the AI model that powers your agent:

| Model | Best For |
|-------|----------|
| **Claude Sonnet** | General purpose, fast, cost-effective |
| **Claude Opus** | Complex reasoning, nuanced responses |
| **GPT-4o** | Versatile, good at following instructions |
| **GPT-4o Mini** | Simple tasks, high volume, low cost |

> **Note:** Start with Claude Sonnet for most use cases. It balances capability and cost well.

## Step 3: Write Instructions

Define how your agent should behave. This is the most important step.

### System Prompt

Write clear instructions for your agent:

```
You are a customer support agent for Acme Corp.

Your job is to:
- Answer questions about our products
- Help with order status inquiries
- Troubleshoot common issues
- Create support tickets for complex problems

Tone: Friendly, professional, helpful
Response length: Keep responses concise (2-3 paragraphs max)

If you're unsure about something, say so and offer to connect
the customer with a human team member.
```

### Tips for Good Instructions

1. **Be specific**: "Answer billing questions" is better than "help customers"
2. **Define tone**: How formal or casual should responses be?
3. **Set boundaries**: What should the agent NOT do?
4. **Handle uncertainty**: What happens when the agent doesn't know?

## Step 4: Configure Capabilities

Enable the actions your agent can take:

### Core Capabilities

- **Send Replies**: Respond to incoming emails
- **Draft for Review**: Create drafts for human approval
- **Forward**: Route emails to team members
- **Categorize**: Apply labels and tags

### Advanced Capabilities

- **Create Records**: Add entries to connected systems
- **Schedule Meetings**: Book calendar appointments
- **Process Attachments**: Extract data from files
- **Research**: Look up information before responding

> **Warning:** Start with fewer capabilities and add more as you gain confidence in the agent's behavior.

## Step 5: Set Escalation Rules

Define when the agent should involve humans:

### Automatic Escalation

- **Confidence Threshold**: Escalate when agent is uncertain
- **Sentiment Detection**: Escalate angry or upset customers
- **Keywords**: Escalate emails containing specific words
- **Sender Rules**: Always escalate from VIP customers

### Escalation Actions

| Action | Description |
|--------|-------------|
| **Pause & Notify** | Stop processing, alert human |
| **Draft & Wait** | Create draft, wait for approval |
| **Forward** | Send to specific team member |
| **Tag & Continue** | Mark for review, send response |

Example escalation rules:

```
- If customer mentions "cancel" or "refund" → Forward to billing team
- If sentiment is negative → Draft for review, notify support lead
- If confidence < 70% → Draft for review
- If sender is @enterprise-customer.com → Always draft for review
```

## Step 6: Add Knowledge

Give your agent information to reference:

### Knowledge Base

Upload documents your agent can reference:
- Product documentation
- FAQ documents
- Policy guides
- Pricing information

### Connected Data

Link to live data sources:
- Customer records (CRM)
- Order history
- Account information

## Step 7: Test Your Agent

Before going live, test with sample emails:

1. Click **Test Agent**
2. Enter a sample email
3. See how the agent responds
4. Adjust instructions as needed

### Test Scenarios

- Common questions (should handle well)
- Edge cases (should escalate appropriately)
- Out-of-scope requests (should decline politely)
- Angry customer (should escalate or respond carefully)

## Step 8: Go Live

When you're confident in the agent's behavior:

1. Review all settings
2. Click **Activate Agent**
3. Monitor the first few interactions closely
4. Adjust as needed

## Example Configurations

### Support Agent

```
Model: Claude Sonnet
Capabilities: Reply, Categorize, Create Tickets
Escalation: Negative sentiment, mentions "manager"

Instructions:
You handle customer support for a SaaS product.
Answer technical questions, help with account issues,
and create tickets for bugs. Be helpful and patient.
```

### Invoice Agent

```
Model: GPT-4o Mini
Capabilities: Extract Data, Create Records
Escalation: Unreadable attachments, missing info

Instructions:
Extract invoice data from incoming emails.
Pull: vendor name, amount, date, invoice number.
Create records in the accounting system.
Flag anything unusual for human review.
```

## Next Steps

- Learn about [agent capabilities](/docs/agents/capabilities) in detail
- Set up [integrations](/docs/api) to connect agents with other systems

---

# Agent Capabilities

> Detailed reference for what AI agents can do

This reference covers all capabilities available to Osprey AI agents.

## Communication Capabilities

### Send Replies

Agents can compose and send email responses automatically.

**Use cases:**
- Answering FAQs
- Acknowledging receipt of messages
- Providing order status updates
- Responding to inquiries

**Configuration:**
```
Enabled: true
Require approval: false
Max responses per thread: 5
```

> **Note:** Enable "Require approval" for sensitive communications where a human should review before sending.

### Draft for Review

Agents create response drafts that humans review before sending.

**Use cases:**
- Sensitive customer communications
- Complex technical responses
- High-value sales conversations
- Anything requiring human judgment

**Workflow:**
1. Email arrives
2. Agent drafts response
3. Human receives notification
4. Human edits (optional) and approves
5. Email sends

### Forward

Agents route emails to appropriate team members.

**Use cases:**
- Routing to specialized teams
- Escalating to managers
- Distributing among team members

**Routing options:**
- **Specific person**: Always forward to same person
- **Round-robin**: Distribute evenly across team
- **Rules-based**: Forward based on content, sender, etc.

## Organization Capabilities

### Categorize

Agents apply labels, tags, and folders to organize email.

**Use cases:**
- Sorting by topic (billing, technical, sales)
- Priority classification (urgent, normal, low)
- Status tracking (needs response, waiting, resolved)

**Configuration:**
```
Categories:
  - billing
  - technical
  - sales
  - general

Auto-archive: after 30 days inactive
```

### Summarize

Agents generate summaries of email threads.

**Use cases:**
- Executive briefings
- Catching up on long threads
- Creating conversation digests

**Summary types:**
- Thread summary (entire conversation)
- Daily digest (all emails from period)
- Topic summary (emails on specific subject)

## Data Capabilities

### Extract Data

Agents pull structured data from email content and attachments.

**Use cases:**
- Invoice processing
- Order extraction
- Contact information capture
- Appointment details

**Extractable fields:**
- Names, emails, phone numbers
- Dates, times, amounts
- Product names, quantities
- Custom fields you define

**Example extraction:**
```
Email: "Please process invoice #1234 for $5,000 from Acme Corp, due March 15"

Extracted:
{
  "invoice_number": "1234",
  "amount": 5000,
  "currency": "USD",
  "vendor": "Acme Corp",
  "due_date": "2024-03-15"
}
```

### Process Attachments

Agents read and extract data from attached files.

**Supported formats:**
- PDF (invoices, contracts, documents)
- Images (receipts, screenshots)
- Spreadsheets (CSV, Excel)
- Documents (Word, text files)

> **Warning:** Attachment processing may increase response time. Consider this for high-volume mailboxes.

## Integration Capabilities

### Create Records

Agents create entries in connected systems.

**Supported integrations:**
- CRM (Salesforce, HubSpot)
- Helpdesk (Zendesk, Freshdesk)
- Project management (Linear, Jira)
- Accounting (QuickBooks, Xero)
- Custom webhooks

**Example:**
```
When: Email from new sender
Action: Create contact in HubSpot
Fields:
  - email: sender email
  - name: extracted from signature
  - source: "Email inquiry"
```

### Update Records

Agents update existing records in connected systems.

**Use cases:**
- Update ticket status
- Add notes to customer record
- Change order status
- Log communication history

### Schedule Meetings

Agents book calendar appointments.

**Requirements:**
- Connected calendar (Google, Outlook)
- Defined availability windows
- Meeting types configured

**Workflow:**
1. Someone requests a meeting via email
2. Agent checks your availability
3. Agent proposes times
4. Recipient confirms
5. Calendar event created

## Research Capabilities

### Knowledge Base Search

Agents search your uploaded documentation to answer questions.

**How it works:**
1. Agent receives question
2. Searches knowledge base for relevant info
3. Synthesizes answer from documentation
4. Includes source references

**Best practices:**
- Keep documentation up to date
- Use clear headings and structure
- Include common questions and answers

### Web Search

Agents search the web for current information.

**Use cases:**
- Checking current prices
- Looking up company information
- Finding recent news
- Verifying facts

> **Note:** Web search is rate-limited to prevent abuse. For high-volume needs, consider uploading reference data instead.

### CRM Lookup

Agents query customer records for context.

**Available data:**
- Customer history
- Past purchases
- Previous conversations
- Account status
- Custom fields

## Security & Compliance

### Capability Limits

Set boundaries on what agents can do:

| Limit | Description |
|-------|-------------|
| **Rate limits** | Max actions per hour/day |
| **Approval thresholds** | Require approval above certain values |
| **Sender restrictions** | Only process from certain domains |
| **Content filters** | Block certain topics or keywords |

### Audit Trail

All agent actions are logged:

- What action was taken
- What email triggered it
- What data was used
- When it happened
- Confidence score

Access audit logs in **Settings > Agent Activity**.

## Combining Capabilities

Agents can use multiple capabilities in sequence:

**Example: Invoice Processing Agent**
```
1. Process Attachment (extract PDF data)
2. Extract Data (pull invoice fields)
3. CRM Lookup (verify vendor exists)
4. Create Record (add to accounting system)
5. Send Reply (confirm receipt)
6. Categorize (mark as processed)
```

**Example: Support Agent**
```
1. Categorize (identify topic)
2. Knowledge Base Search (find answer)
3. CRM Lookup (get customer context)
4. Draft Reply (compose response)
5. [Human reviews and sends]
```

## Next Steps

- [Create an agent](/docs/agents/create-agent) with these capabilities
- Learn about the [API](/docs/api) for programmatic control

---

# Team Management

> Add team members, manage roles, and control access to your organization

Manage who has access to your Osprey organization and what they can do.

## Users in Osprey

In Osprey, there are two types of users:

| Type | Description |
|------|-------------|
| **Humans** | Team members who sign in and use the app |
| **Agents** | AI-powered users that handle email automatically |

Both types can have mailboxes and send/receive email. The difference is how they're managed and how they access the system.

## Roles

Every user has a role that determines their permissions:

| Role | Capabilities |
|------|-------------|
| **Admin** | Full access: manage domains, users, billing, settings |
| **Member** | Access their mailbox, send/receive email, view shared inboxes |

### Admin Capabilities

- Add and remove team members
- Manage domains and DNS
- Create and configure agents
- Access billing and subscription settings
- View all mailboxes and activity
- Manage integrations (Cloudflare, etc.)

### Member Capabilities

- Access assigned mailboxes
- Send and receive email
- View shared inbox (if granted access)
- Update their own profile and preferences

## Organization Structure

Each Osprey organization represents one company or team:

```
Organization (your-company.com)
├── Admins
│   └── rob@your-company.com (human)
├── Members  
│   ├── sarah@your-company.com (human)
│   └── mike@your-company.com (human)
└── Agents
    ├── support@your-company.com (agent)
    └── invoices@your-company.com (agent)
```

## Getting Started

- [Add team members](/docs/team/add-members) to your organization
- [Manage roles and permissions](/docs/team/roles)

---

# Add Team Members

> Invite people to join your Osprey organization

Invite team members to your Osprey organization so they can access their mailboxes and collaborate.

## Inviting a Team Member

1. Go to **Settings > Team**
2. Click **Invite Member**
3. Enter their email address (their personal email, not the company mailbox)
4. Select their role: **Admin** or **Member**
5. Click **Send Invite**

The invitee receives an email with a link to join your organization.

> **Note:** Team members sign in with their personal email (via Clerk authentication) and then access their company mailbox.

## What Happens Next

1. **Invitee receives email** with a join link
2. **They create an account** (or sign in if they already have one)
3. **They're added to your organization** with the assigned role
4. **You assign them a mailbox** (or they get one automatically)

## Assigning a Mailbox

After someone joins, assign them a company mailbox:

1. Go to **Mailboxes**
2. Click **Create Mailbox**
3. Select **Human** as the type
4. Enter the email address (e.g., `sarah`)
5. Select the domain
6. Under **Assign to**, select the team member
7. Click **Create**

Or assign an existing mailbox:

1. Go to **Mailboxes**
2. Click on the mailbox
3. Go to **Settings > Assigned User**
4. Select the team member
5. Click **Save**

## Bulk Invites

Invite multiple people at once:

1. Go to **Settings > Team**
2. Click **Bulk Invite**
3. Enter email addresses (one per line or comma-separated)
4. Select the default role
5. Click **Send Invites**

## Pending Invitations

View and manage pending invites:

1. Go to **Settings > Team**
2. Click the **Pending** tab
3. See all outstanding invitations
4. **Resend** or **Revoke** as needed

Invitations expire after 7 days. Resend to generate a new link.

## Invite Limits

| Plan | Team Members |
|------|--------------|
| Free | 3 |
| Pro | 25 |
| Enterprise | Unlimited |

> **Warning:** Invite limits include both humans and agents. Agents count as team members.

## Next Steps

- [Manage roles and permissions](/docs/team/roles)
- [Create mailboxes](/docs/mailboxes/create-mailbox) for your team

---

# Roles & Permissions

> Understand and manage user roles in your organization

Control what team members can do in your Osprey organization.

## Available Roles

### Admin

Full access to everything in the organization.

**Permissions:**
- Manage team members (invite, remove, change roles)
- Manage domains (add, verify, delete)
- Manage all mailboxes (create, edit, delete)
- Configure agents
- Access billing and subscription
- Manage integrations
- View all activity and audit logs
- Access organization settings

### Member

Standard access for day-to-day email use.

**Permissions:**
- Access assigned mailboxes
- Send and receive email
- View shared inboxes (if granted)
- Update personal profile and preferences
- View their own activity

**Cannot:**
- Manage other team members
- Add or remove domains
- Access billing
- Change organization settings

## Changing Roles

To change a team member's role:

1. Go to **Settings > Team**
2. Find the team member
3. Click the role dropdown
4. Select the new role
5. Confirm the change

> **Warning:** You cannot demote yourself from Admin if you're the only Admin. Promote another member first.

## Permission Details

### Mailbox Access

| Action | Admin | Member |
|--------|-------|--------|
| View own mailbox | Yes | Yes |
| Send from own mailbox | Yes | Yes |
| View all mailboxes | Yes | No |
| Create mailboxes | Yes | No |
| Delete mailboxes | Yes | No |
| Assign mailboxes to users | Yes | No |

### Domain Management

| Action | Admin | Member |
|--------|-------|--------|
| View domains | Yes | Yes |
| Add domains | Yes | No |
| Verify DNS | Yes | No |
| Delete domains | Yes | No |

### Agent Management

| Action | Admin | Member |
|--------|-------|--------|
| View agent activity | Yes | Limited* |
| Create agents | Yes | No |
| Configure agents | Yes | No |
| Pause/resume agents | Yes | No |

*Members can view activity for agents they interact with.

### Team Management

| Action | Admin | Member |
|--------|-------|--------|
| View team members | Yes | Yes |
| Invite members | Yes | No |
| Remove members | Yes | No |
| Change roles | Yes | No |

### Billing & Settings

| Action | Admin | Member |
|--------|-------|--------|
| View subscription | Yes | No |
| Change plan | Yes | No |
| Update payment | Yes | No |
| Organization settings | Yes | No |

## Shared Mailbox Access

Members can be granted access to shared mailboxes (like `support@` or `sales@`):

1. Go to **Mailboxes**
2. Click on the shared mailbox
3. Go to **Settings > Access**
4. Add team members who should have access
5. Click **Save**

Members with shared access can:
- View emails in the shared mailbox
- Reply from the shared address
- See activity from other team members

## Best Practices

### Limit Admin Access

Only grant Admin role to people who need it:
- IT administrators
- Team leads who manage the email system
- Billing contacts

### Use Shared Mailboxes

Instead of giving everyone Admin access:
- Create shared mailboxes for teams
- Grant Member access to specific shared mailboxes
- Keep individual mailboxes private

### Review Access Regularly

Periodically review team access:
- Remove inactive users
- Downgrade roles when responsibilities change
- Revoke shared mailbox access when no longer needed

## Removing Team Members

To remove someone from your organization:

1. Go to **Settings > Team**
2. Find the team member
3. Click **Remove**
4. Choose what to do with their mailbox:
   - **Keep mailbox** (reassign to someone else)
   - **Disable mailbox** (stop receiving, keep history)
   - **Delete mailbox** (permanent, removes all email)
5. Confirm removal

> **Note:** Removed users can be re-invited later. Their data is retained based on your choice above.

---

# API Reference

> Integrate Osprey with your applications using our REST API

The Osprey API lets you programmatically manage mailboxes, send emails, and control AI agents.

## Base URL

All API requests use this base URL:

```
https://api.osprey.sh/api
```

## OpenAPI Specification

Our API is fully documented with OpenAPI 3.0. You can:

- **Browse interactively**: [API Reference](/api/reference)
- **Download spec**: [OpenAPI JSON](/api/doc)
- **Import to Postman**: Use the OpenAPI JSON URL

## Quick Start

### 1. Get an API Key

1. Go to **Settings > API Keys**
2. Click **Create API Key**
3. Name your key and set permissions
4. Copy the key (shown only once)

### 2. Make Your First Request

```bash
curl https://api.osprey.sh/api/me \
  -H "Authorization: Bearer your_api_key"
```

Response:
```json
{
  "id": "user_abc123",
  "email": "you@company.com",
  "organizationId": "org_xyz789"
}
```

## Authentication

All requests require authentication via Bearer token:

```
Authorization: Bearer your_api_key
```

See [Authentication](/docs/api/authentication) for details on API keys and scopes.

## Endpoints Overview

| Resource | Description |
|----------|-------------|
| [`/api/me`](/api/reference#tag/me) | Current user info |
| [`/api/domains`](/api/reference#tag/domains) | Domain management |
| [`/api/mailboxes`](/api/reference#tag/mailboxes) | Mailbox CRUD |
| [`/api/emails`](/api/reference#tag/emails) | Send and read emails |
| [`/api/users`](/api/reference#tag/users) | User management |

## Common Patterns

### Pagination

List endpoints support pagination:

```bash
GET /api/mailboxes?limit=20&offset=40
```

Response includes pagination info:
```json
{
  "data": [...],
  "total": 150,
  "limit": 20,
  "offset": 40
}
```

### Filtering

Filter results with query parameters:

```bash
GET /api/mailboxes?domain=company.com&type=agent
```

### Error Handling

Errors return appropriate HTTP status codes:

| Code | Meaning |
|------|---------|
| 400 | Bad request (invalid parameters) |
| 401 | Unauthorized (invalid/missing API key) |
| 403 | Forbidden (insufficient permissions) |
| 404 | Not found |
| 429 | Rate limited |
| 500 | Server error |

Error response format:
```json
{
  "error": {
    "code": "INVALID_DOMAIN",
    "message": "Domain not found in your organization"
  }
}
```

## Rate Limits

API requests are rate limited per API key:

| Plan | Requests/minute |
|------|-----------------|
| Free | 60 |
| Pro | 300 |
| Enterprise | 1000 |

Rate limit headers are included in responses:
```
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1699574400
```

## SDKs

Official SDKs coming soon:

- TypeScript/JavaScript
- Python
- Go

For now, use any HTTP client with our REST API.

## Webhooks

Receive real-time notifications when events occur:

- Email received
- Email sent
- Agent action taken
- Mailbox created/updated

Configure webhooks in **Settings > Webhooks**.

## Next Steps

- [Authentication](/docs/api/authentication) — API keys and scopes
- [Endpoints Reference](/docs/api/endpoints) — Detailed endpoint documentation
- [Interactive API Reference](/api/reference) — Try requests in your browser

---

# Authentication

> Authenticate with the Osprey API using API keys

All Osprey API requests require authentication. This guide covers how to create and use API keys.

## API Keys

API keys are the primary way to authenticate with the Osprey API.

### Creating an API Key

1. Go to **Settings > API Keys**
2. Click **Create API Key**
3. Enter a name (e.g., "Production Server", "CI/CD Pipeline")
4. Select the scopes (permissions) for this key
5. Click **Create**
6. Copy the key immediately — it won't be shown again

> **Warning:** API keys are shown only once when created. Store them securely. If you lose a key, revoke it and create a new one.

### Using API Keys

Include your API key in the `Authorization` header:

```bash
curl https://api.osprey.sh/api/mailboxes \
  -H "Authorization: Bearer osp_live_abc123..."
```

### Key Prefixes

API keys have prefixes indicating their type:

| Prefix | Type | Use |
|--------|------|-----|
| `osp_live_` | Production | Live API requests |
| `osp_test_` | Test | Testing and development |

Test keys only access test data and don't affect production.

## Scopes

Scopes control what an API key can access. Follow the principle of least privilege — only grant scopes that are needed.

### Available Scopes

| Scope | Description |
|-------|-------------|
| `read:mailboxes` | List and view mailboxes |
| `write:mailboxes` | Create, update, delete mailboxes |
| `read:emails` | Read email content |
| `write:emails` | Send emails |
| `read:domains` | List and view domains |
| `write:domains` | Manage domains |
| `read:users` | List and view users |
| `write:users` | Manage users |
| `admin` | Full access (includes all scopes) |

### Scope Examples

**Read-only integration:**
```
read:mailboxes, read:emails
```

**Email sending service:**
```
read:mailboxes, write:emails
```

**Full management:**
```
admin
```

## Security Best Practices

### Store Keys Securely

- Use environment variables, not source code
- Use secret management services (AWS Secrets Manager, HashiCorp Vault)
- Never commit keys to version control

```bash
# Good: Environment variable

const apiKey = "osp_live_abc123..." // DON'T DO THIS
```

### Use Separate Keys

Create separate keys for different environments and services:

| Key Name | Environment | Scopes |
|----------|-------------|--------|
| Production Backend | Production | write:emails, read:mailboxes |
| Staging Backend | Staging | admin |
| Analytics Service | Production | read:emails (read-only) |
| CI/CD Pipeline | CI | read:mailboxes |

### Rotate Keys Regularly

- Rotate production keys periodically (e.g., every 90 days)
- Immediately rotate if a key may have been compromised
- Use key expiration dates for temporary access

### Monitor Usage

Review API key usage in **Settings > API Keys**:

- Last used timestamp
- Request count
- Error rate
- IP addresses

## Revoking Keys

To revoke an API key:

1. Go to **Settings > API Keys**
2. Find the key to revoke
3. Click **Revoke**
4. Confirm the action

Revoked keys immediately stop working. Any requests using that key will receive a 401 error.

## Organization Keys vs User Keys

| Type | Created By | Access |
|------|-----------|--------|
| **Organization Keys** | Admins | All org resources |
| **User Keys** | Individual users | Only that user's resources |

For most integrations, use organization keys. User keys are useful for per-user integrations where each user connects their own account.

## Error Responses

### Invalid Key

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked"
  }
}
```
HTTP Status: 401

### Missing Key

```json
{
  "error": {
    "code": "MISSING_AUTH",
    "message": "Authorization header is required"
  }
}
```
HTTP Status: 401

### Insufficient Scope

```json
{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This action requires the 'write:emails' scope"
  }
}
```
HTTP Status: 403

## OAuth (Coming Soon)

OAuth 2.0 support is planned for apps that need to access Osprey on behalf of users. This will enable:

- User authorization flows
- Refresh tokens
- Granular consent

## Next Steps

- [API Endpoints](/docs/api/endpoints) — See all available endpoints
- [Interactive Reference](/api/reference) — Test API calls in your browser

---

# Endpoints Reference

> Complete reference for all Osprey API endpoints

This page documents all Osprey API endpoints. For an interactive experience, use the [API Reference](/api/reference).

## Base URL

```
https://api.osprey.sh/api
```

---

## Me

Get information about the authenticated user.

### Get Current User

```
GET /api/me
```

**Response:**
```json
{
  "id": "user_abc123",
  "email": "you@company.com",
  "displayName": "Your Name",
  "organizationId": "org_xyz789",
  "role": "admin",
  "type": "human"
}
```

---

## Domains

Manage email domains for your organization.

### List Domains

```
GET /api/domains
```

**Response:**
```json
{
  "data": [
    {
      "id": "dom_abc123",
      "domain": "company.com",
      "status": "verified",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}
```

### Add Domain

```
POST /api/domains
```

**Request:**
```json
{
  "domain": "newdomain.com"
}
```

**Response:**
```json
{
  "id": "dom_xyz789",
  "domain": "newdomain.com",
  "status": "pending",
  "verificationRecords": [
    {
      "type": "TXT",
      "host": "_osprey",
      "value": "osprey-verify=abc123"
    }
  ]
}
```

### Get Domain

```
GET /api/domains/:id
```

### Verify Domain

```
POST /api/domains/:id/verify
```

Checks DNS records and updates domain status.

### Delete Domain

```
DELETE /api/domains/:id
```

> **Warning:** Deleting a domain also removes all associated mailboxes and emails.

---

## Mailboxes

Manage email addresses (for humans and agents).

### List Mailboxes

```
GET /api/mailboxes
```

**Query Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `domain` | string | Filter by domain |
| `type` | string | Filter by type: `human` or `agent` |
| `limit` | number | Results per page (default: 20) |
| `offset` | number | Pagination offset |

**Response:**
```json
{
  "data": [
    {
      "id": "mbx_abc123",
      "email": "support@company.com",
      "displayName": "Support Team",
      "type": "agent",
      "status": "active"
    }
  ],
  "total": 15,
  "limit": 20,
  "offset": 0
}
```

### Create Mailbox

```
POST /api/mailboxes
```

**Request:**
```json
{
  "email": "support",
  "domain": "company.com",
  "displayName": "Support Team",
  "type": "agent"
}
```

### Get Mailbox

```
GET /api/mailboxes/:id
```

### Update Mailbox

```
PATCH /api/mailboxes/:id
```

**Request:**
```json
{
  "displayName": "Customer Support",
  "signature": "Best regards,\nThe Support Team"
}
```

### Delete Mailbox

```
DELETE /api/mailboxes/:id
```

---

## Emails

Send and retrieve emails.

### List Emails

```
GET /api/emails
```

**Query Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `mailbox` | string | Filter by mailbox ID |
| `folder` | string | Filter by folder: `inbox`, `sent`, `drafts` |
| `since` | string | ISO date, emails after this time |
| `limit` | number | Results per page |

### Get Email

```
GET /api/emails/:id
```

**Response:**
```json
{
  "id": "eml_abc123",
  "mailboxId": "mbx_xyz789",
  "from": {
    "email": "sender@example.com",
    "name": "Sender Name"
  },
  "to": [
    {
      "email": "you@company.com",
      "name": "Your Name"
    }
  ],
  "subject": "Hello!",
  "body": {
    "text": "Plain text content",
    "html": "<p>HTML content</p>"
  },
  "receivedAt": "2024-01-15T10:30:00Z"
}
```

### Send Email

```
POST /api/emails
```

**Request:**
```json
{
  "from": "support@company.com",
  "to": ["customer@example.com"],
  "subject": "Re: Your inquiry",
  "body": {
    "text": "Thank you for reaching out...",
    "html": "<p>Thank you for reaching out...</p>"
  },
  "replyTo": "eml_abc123"
}
```

**Response:**
```json
{
  "id": "eml_xyz789",
  "status": "sent"
}
```

### Create Draft

```
POST /api/emails/drafts
```

Same request format as Send Email, but creates a draft instead of sending.

### Delete Email

```
DELETE /api/emails/:id
```

Moves to trash (or permanently deletes if already in trash).

---

## Users

Manage users (humans and agents) in your organization.

### List Users

```
GET /api/users
```

**Query Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `type` | string | Filter by type: `human` or `agent` |
| `role` | string | Filter by role: `admin` or `member` |

### Get User

```
GET /api/users/:id
```

### Update User

```
PATCH /api/users/:id
```

**Request:**
```json
{
  "displayName": "New Name",
  "role": "admin"
}
```

### Delete User

```
DELETE /api/users/:id
```

---

## Webhooks

Configure webhook endpoints to receive real-time events.

### List Webhooks

```
GET /api/webhooks
```

### Create Webhook

```
POST /api/webhooks
```

**Request:**
```json
{
  "url": "https://yourapp.com/webhooks/osprey",
  "events": ["email.received", "email.sent"],
  "secret": "your_webhook_secret"
}
```

### Delete Webhook

```
DELETE /api/webhooks/:id
```

---

## Webhook Events

Events your webhook can receive:

| Event | Description |
|-------|-------------|
| `email.received` | New email received in any mailbox |
| `email.sent` | Email sent from any mailbox |
| `agent.action` | Agent took an action |
| `mailbox.created` | New mailbox created |
| `domain.verified` | Domain verification completed |

**Event Payload:**
```json
{
  "event": "email.received",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "emailId": "eml_abc123",
    "mailboxId": "mbx_xyz789",
    "from": "sender@example.com",
    "subject": "Hello!"
  }
}
```

---

## Interactive Reference

For the full interactive API reference with request/response examples and the ability to try requests directly, visit:

[API Reference →](/api/reference)

---