# Croft API

> Email infrastructure API for AI agents

## Authentication

All endpoints except /health require an API key:
```
Authorization: Bearer croft_xxxxxxxxx
```

## Quick Start

1. Create an inbox: POST /v1/inboxes
2. Send email: POST /v1/inboxes/{id}/messages
3. Receive email: Create a webhook for "message.received" events

## Endpoints

### Inboxes
- POST /v1/inboxes - Create inbox
- GET /v1/inboxes - List inboxes
- GET /v1/inboxes/{id} - Get inbox
- PATCH /v1/inboxes/{id} - Update inbox
- DELETE /v1/inboxes/{id} - Delete inbox

### Messages
- POST /v1/inboxes/{id}/messages - Send message
- GET /v1/inboxes/{id}/messages - List messages (filter by threadId)
- GET /v1/inboxes/{id}/messages/{msgId} - Get message
- POST /v1/inboxes/{id}/messages/{msgId}/reply - Reply to message

### Webhooks
- POST /v1/webhooks - Create webhook
- GET /v1/webhooks - List webhooks
- GET /v1/webhooks/{id} - Get webhook
- PATCH /v1/webhooks/{id} - Update webhook
- DELETE /v1/webhooks/{id} - Delete webhook

### API Keys
- POST /v1/api-keys - Create API key
- GET /v1/api-keys - List API keys
- DELETE /v1/api-keys/{id} - Delete API key

### Domains (Custom Email Domains)
- POST /v1/domains - Register domain (returns DNS records to configure)
- GET /v1/domains - List domains
- GET /v1/domains/{id} - Get domain with DNS records
- DELETE /v1/domains/{id} - Delete domain (fails if inboxes exist)
- POST /v1/domains/{id}/verify - Check/refresh verification status

## Custom Domains Workflow

1. POST /v1/domains with your domain name
2. Configure DNS records returned (TXT for verification, 3 CNAMEs for DKIM, MX for inbound)
3. Wait for DNS propagation (usually minutes, can take up to 72 hours)
4. POST /v1/domains/{id}/verify to check status
5. Once verified, create inboxes with domainId parameter

## Async Processing

All email operations are processed asynchronously via background queues:

- **Sending emails**: Returns immediately with status "queued". Message status updates to "sent" or "failed" after processing.
- **Receiving emails**: Inbound endpoints return 202 Accepted. Processing happens in background.
- **Webhooks**: Delivered asynchronously with automatic retries.

### Message Statuses
- queued - Message accepted, pending send
- sent - Successfully sent via email provider
- delivered - Confirmed delivered to recipient
- failed - Send failed after retries
- bounced - Recipient server rejected

## Webhook Events

- message.received - Inbound email arrived (includes full thread history)
- message.sent - Outbound email sent successfully
- message.delivered - Email confirmed delivered
- message.bounced - Email bounced
- message.complained - Recipient marked as spam
- message.rejected - Email rejected
- domain.verified - Custom domain DNS verified

## ID Prefixes

- org_ - Organization
- ak_ - API Key
- ibx_ - Inbox
- thr_ - Thread
- msg_ - Message
- att_ - Attachment
- whk_ - Webhook
- dom_ - Domain

## Pricing

| Plan | Price | Inboxes | Emails/mo | Features |
|------|-------|---------|-----------|----------|
| Free | $0 | 3 | 500 | Send + Receive |
| Pro | $19 | 10 | 10,000 | Custom domains, Priority support |
| Scale | $99 | Unlimited | 100,000 | Custom domains, Dedicated support |

Paid plans include soft limits with overage pricing at $1 per 1,000 emails over the monthly limit.

## Limits

- Max email size: 25 MB
- Max attachment size: 10 MB
- Max attachments per email: 20
- Rate limit: 100 requests/minute

## More Info

- Interactive docs: /docs
- OpenAPI spec: /openapi.json
- Structured context: /v1/context