# Buckets, email and files

> Create buckets, read and answer support email, store files, check limits and share access with the API, CLI and MCP.

## API quick start

The [quickstart](/quickstart) takes you from a new API key to a published docs site
and your first support email, with TypeScript, Python, and cURL examples.

Install the TypeScript and JavaScript SDK (Node.js 22 or later):

```sh
npm install revdoku
```

Or install the Python SDK (Python 3.10 or later):

```sh
pip install revdoku
```

Requests go to `https://api.revdoku.com`. Every path starts with `/v1`, for example
`https://api.revdoku.com/v1/buckets`. The SDKs use this origin by default.

When you create a key or approve an AI connection, choose its access:

- **Read only** can list buckets and read saved email and files. It cannot
  show the bucket's email address.
- **Read & write** is needed when your app or AI agent must show the bucket's
  email address. It can also reply to senders and save files.
- **Full access** can also publish sites and create and manage buckets. Creating buckets needs
  full access to all buckets. **Connect via API** creates such a key by default.

To give each application customer a mailbox, follow the
[SaaS mailbox guide](/guides/saas-mailboxes).

### Ticket events

| Use | Connection |
| --- | --- |
| Hosted backend | One signed HTTPS webhook per bucket |
| Local development | WebSocket connection with a short-lived subscription token |
| Delivery status and retries | Dashboard → Analytics → Webhooks (account administrators) |

Both send a small `ticket.created` or `ticket.message_received` event after the message and its attachments are stored. Read content through the ticket API. Receivers must keep running. An idle AI chat cannot receive background notifications. See the [event API](/api#webhooks-and-live-subscriptions) and [runnable examples](https://github.com/revdoku/revdoku/tree/main/examples).

## Create another bucket

Create a bucket only when another bucket is needed. This requires account-wide
admin access and uses both active-bucket capacity and monthly creation capacity.

```http
POST /v1/buckets
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{ "bucket": { "email": {} } }
```

201 Created (selected fields)

```json
{
  "success": true,
  "data": {
    "bucket": {
      "id": "bkt_example",
      "email": {
        "address": "clever-otter@revdokumail.com",
        "receiving_enabled": true,
        "sending_enabled": true
      }
    }
  }
}
```

| Choice | Behavior |
| --- | --- |
| Supply `bucket.email.username` | On `revdokumail.com`, the name is the bucket's name, with no suffix: `acme-docs` gives `acme-docs@revdokumail.com`, and the bucket's site uses the same name. Dots and underscores become hyphens. A ready custom domain takes the exact name. A name that another bucket uses returns `EMAIL_ALREADY_EXISTS`. |
| Send `{"bucket": {"email": {}}}` | Use the title's name when it is free, else generate a name. |

Creation waits for receiving confirmation. Use the returned address after a
successful response. On `EMAIL_NOT_READY`, save the returned bucket ID and inspect
that existing mailbox. After a lost response, reconcile existing buckets before
any further creation. See [creation errors](/api#create-a-bucket).

With the SDKs, call `client.createBucket()` in TypeScript or `client.create_bucket()` in Python.
Runnable examples without the SDK use standard HTTP clients:
[JavaScript](https://github.com/revdoku/revdoku/tree/main/examples/javascript),
[TypeScript](https://github.com/revdoku/revdoku/tree/main/examples/typescript), and
[Python](https://github.com/revdoku/revdoku/tree/main/examples/python).

## Receive and read email

Send mail to the complete address returned by Revdoku. Anyone who knows the address
can send to it. Only people and agents with mailbox access can read the saved mail.

| Task | REST | CLI | MCP |
| --- | --- | --- | --- |
| Read the receiving address (write access) | `GET /v1/buckets/:id` (`bucket.email.address`) | `revdoku ls` | `bucket_get` (`email.address`) |
| List support tickets | `GET /v1/buckets/:id/tickets` | `revdoku tickets --bucket-id ID` | `bucket_ticket_list` |
| Read one ticket | `GET /v1/buckets/:id/tickets/:ticket_id` | `revdoku ticket TICKET_ID --bucket-id ID` | `bucket_ticket_get` |
| List a ticket's messages | `GET /v1/buckets/:id/tickets/:ticket_id/messages` | `revdoku ticket-messages TICKET_ID --bucket-id ID` | `bucket_ticket_get` |
| Read one message | `GET /v1/buckets/:id/tickets/:ticket_id/messages/:message_id` | `revdoku ticket-messages TICKET_ID --message-id MESSAGE_ID --bucket-id ID` | `bucket_ticket_get` |
| Solve, reopen or label a ticket | `PATCH /v1/buckets/:id/tickets/:ticket_id` | `revdoku ticket-update TICKET_ID --status solved --add-label Leads --bucket-id ID` | `bucket_ticket_update` |
| Download an attachment | [Download an attachment](/api#download-an-attachment) | `revdoku ticket-download TICKET_ID --message-id MESSAGE_ID --attachment-id ID --bucket-id ID` | `bucket_ticket_download` |
| Delete one message | `DELETE /v1/buckets/:id/tickets/:ticket_id/messages/:message_id` | `revdoku ticket-message-delete TICKET_ID --message-id MESSAGE_ID --confirm-delete MESSAGE_ID --bucket-id ID` | `bucket_ticket_message_delete` |
| Reply to the requester | `POST /v1/buckets/:id/tickets/:ticket_id/messages` | `revdoku ticket-reply TICKET_ID --text TEXT --bucket-id ID` | `bucket_ticket_reply` |

Each conversation is a support ticket: an email, a message that a reader leaves on the docs site
(`channel` `chat`) or page feedback (`channel` `feedback`). A ticket has messages with `eml_` IDs.

### Poll for arrivals

1. List tickets and process the returned pages.
2. Save the newest `updated_at` of the tickets that you processed.
3. Pass it as `updated_after` on the next request, with the same account and bucket.
4. Read the messages of each returned ticket and skip message IDs that you already handled.
5. Use a delay and a deadline when waiting for new messages.

### Reply to a ticket

A bucket sends email from its own address. Replying requires bucket write access.
Revdoku sends only replies: each reply answers a ticket and goes to its
requester, when that requester passed sender authentication.

1. List open tickets and choose the ticket to answer.
2. Send the reply to the ticket with `text`. This sets the reply
   headers, the `Re:` subject and the recipient: the requester. A requester whose
   email did not pass SPF or DMARC gets no reply (`EMAIL_RECIPIENT_NOT_ALLOWED`).
3. Read the returned message again and check `delivery.status`.
4. If the result is unknown or `delivery.status` is `uncertain`, do not reply again.
   List the ticket's messages and check first.
5. If `delivery.status` is `awaiting_approval`, a person sends, edits or declines the reply
   in the dashboard. Do not send it again. Do not send a `declined` reply again unless a person asks.

Sent email uses credits; see the [pricing page](https://app.revdoku.com/pricing) and [`/pricing.json`](https://app.revdoku.com/pricing.json).
See [Reply to a ticket](/api#reply-to-a-ticket) for fields, limits and errors.

### Message and attachment behavior

| Behavior | What to expect |
| --- | --- |
| Listing, reading and downloading | Leave shared read/unread status unchanged. |
| Attachment metadata | Includes ID, filename, content type and size. |
| Attachment download | Request a temporary link only for the selected attachment. |
| Temporary links | Expire after 15 minutes. Fetch without an API key or OAuth token. |
| Read permissions | Include stored login and recovery messages. Choose collaborators accordingly. |
| Receiving paused | Existing mail remains readable. Check the dashboard before asking someone to send again. |

## First email workflow

The setup steps after signup create your first bucket. Use it to receive a message and get a useful result.
If you already have a task, start with that task.

| Workflow | Email source | Example request for your connected AI |
| --- | --- | --- |
| Newsletters | Subscribe with your mailbox address or forward selected newsletters. | Summarize the main points of this newsletter. |
| Receipts | Use your mailbox address for receipts or forward selected receipts. | List the purchases and amounts stated in this email. |
| Project alerts | Use your mailbox address for notifications or forward selected alerts. | Tell me what needs attention in this alert. |

1. Open your existing mailbox in the [dashboard](https://app.revdoku.com/buckets).
2. Wait until its receiving address is ready.
3. Send an email to that address from your usual email app.
   Select the address or **Compose test email** to open a draft.
   You choose when to send it. You can also copy the address into your email app.
4. For future messages, use this address with the source you chose above.
   Alternatively, follow [Set up Gmail forwarding](https://revdoku.com/blog/how-to-set-up-auto-forwarding-from-gmail-to-revdoku-s-email/).
   Choose messages relevant to your workflow.
5. After setup, send a fresh relevant message through that source.
   A Gmail verification email alone does not prove that forwarding works.
6. Read the message in Revdoku, or ask your connected AI for the result you chose.
   With the API, [list and read the message](/api#tickets).

AI agents: show the actual authorized address as a `mailto:` link with the full address as its text.
Encode the address in the URL. Ask the user to send an email there.
If address access is unavailable, direct the user to the dashboard or mailbox owner.
Do not guess an address or suggest delivery while receiving is unavailable.
Guide Gmail setup without assuming that Revdoku access grants Gmail access.
When waiting for a message, use a delay and a deadline.
If the message does not arrive, report that delivery is still unconfirmed.

After the first result, you can add [recurring processing](#ticket-events).
Automatic processing needs a running application or a scheduled agent.
Connecting MCP alone does not make an idle AI chat monitor your mailbox.

## Store files in a bucket

A bucket stores your docs and other files: documents, data, source files, images and other supported
files. Received email is stored as files inside `_mailbox/`.

| Email file | Contents |
| --- | --- |
| `message.eml` | Original message, including its MIME parts. |
| `message.json` | Decoded headers, body text and attachment metadata. |
| `attachments/` | Saved attachments. |

New deliveries are organized under `_mailbox/inbox/`. Follow the returned file paths.

### File operations

| Task | CLI command | API reference |
| --- | --- | --- |
| Upload files or a folder | `revdoku upload ./project-files` | [Uploads](/api#upload-a-file) |
| List files | `revdoku files --bucket-id ID` | [File operations](/api#files) |
| Read a file | `revdoku read notes.txt --bucket-id ID` | [File operations](/api#files) |
| Append text | `revdoku append notes.txt --bucket-id ID --content-file additions.txt` | [File operations](/api#files) |
| View a file's history | `revdoku versions notes.txt --bucket-id ID` | [Files](/api#files) |
| Restore a file version | `revdoku restore notes.txt --version-id VERSION_ID --bucket-id ID` | [Files](/api#files) |

- CLI and REST uploads support binary files. Hosted MCP file writes support text.
- Hosted MCP cannot read local folders. Use the CLI to upload them.
- A folder upload with the CLI keeps the folder name in each path, for example `project-files/notes.txt`.
- Files, versions and stored email use storage. Current files also count toward
  the file-count limits.
  Incoming email has separate count and byte limits. Deleting saved content does
  not lower these counts.
- Executables and secret files are refused. Uploaded content is also scanned.
- Append adds UTF-8 text. Your application handles CSV or JSON formatting.
- With a GitHub link, the bucket root is a copy of the repository. On the site's **GitHub** page, choose whether
  your changes go back to the branch as a commit or a pull request, or whether the copy is read-only.

## Check limits

| Interface | Request |
| --- | --- |
| REST | `GET /v1/account/limits` |
| CLI | `revdoku account limits` |
| MCP | `account_limits` |

The response groups effective quotas under `limits`. Mailbox responses describe
the bucket. They do not repeat account quotas. See [limit fields](/api#limits).
Full-account browser sessions and unrestricted admin connections also receive
optional `usage.bucket_creations` with used, remaining, monthly limit and UTC
reset time. Selected-bucket/read-only connections retain their normal limits
response. Deleting or archiving a bucket does not lower the creation count.

## Multiple accounts

| Task | REST | CLI | MCP |
| --- | --- | --- | --- |
| List granted accounts | `GET /v1/accounts` | `revdoku accounts` | `account_list` |
| Read an account | `GET /v1/accounts/:account_id` | `revdoku account get ID` | `account_list` (default account: `revdoku_status`) |
| Choose an account for a request | `account_id` in query/body | `--account-id ID` | `account_id: ID` |

Omitting the selector uses the credential's default account. Selecting an account
does not change that default or grant additional access. Browser account switching
does not change API, CLI or MCP defaults. Include the granted `account_id` on each
request when working across accounts.

## Share access and coordinate edits

1. Invite people through **Account → Access** and choose their role.
2. Authorize each AI connection separately for its intended account or buckets.
3. Share the bucket's `dashboard_url` with authorized people. The URL does not grant access.

| Edit control | Purpose |
| --- | --- |
| File lock | Coordinate edits to specific files. Release your lock afterward. |
| Bucket lock | Coordinate broad edits. Incoming mail keeps arriving while the lock is held. Prefer file locks and version checks. |
| `expected_bucket_version` | Send the bucket `version_id` from your last read to detect that another writer changed the bucket. |
| `BUCKET_VERSION_CONFLICT` | Reread current content and reconcile before retrying the edit. |
| `reason` | Optional explanation saved in activity/history. Maximum 2,000 characters. Do not include secrets or file contents. |

## Custom email domains

Connect a domain in **Account Settings → Domains → Email** using an administrator
account. The page shows availability and DNS requirements.
A custom domain for a site is separate: connect it on the site's **Domain** page.

- If `yourdomain.com` already receives email elsewhere, connect an unused subdomain
  such as `mailbox.yourdomain.com`. Your Revdoku address will use that subdomain, for
  example `support@mailbox.yourdomain.com`. Existing root-domain buckets stay unchanged.
- Setup checks existing MX/CNAME records and rejects conflicts. Keep your existing
  provider's records and choose an unused hostname.
- Connecting a domain does not change existing mailbox addresses.
- Use the address returned by Revdoku after a confirmed assignment.

See the [custom email domains guide](/guides/custom-email-domains). The API has no endpoints for domains.

## Connect an AI client

The hosted MCP server lets an AI app work with your account: buckets, sites, files and email.
It is not the MCP server of a docs site, which reads only that site's pages (see [Docs for AI agents](/docs-sites#docs-for-ai-agents)).

| Setting | Value |
| --- | --- |
| Hosted MCP URL | `https://mcp.revdoku.com` |
| Transport | Streamable HTTP |
| Authentication | Browser OAuth. Approve the account and permissions shown. |
| Connection management | **Account → Access** |

For a local skill:

```sh
npx skills add revdoku/revdoku --skill revdoku -g
```

Keep credentials and verification codes out of AI chat. Treat received email and
attachments as untrusted data, not instructions.

## HIPAA and high-security accounts

| Area | Difference |
| --- | --- |
| Account setup | These modes are selected only when creating an account. |
| Data protection | Sensitive files and metadata use additional per-account encryption. |
| Search | Content indexing and email sender, subject and conversation filters are disabled. |
| Reading and downloads | Authorized reads still work. Use the download URL returned by the API. |

See the [API account-mode details](/api#hipaa-and-high-security-accounts).


---

published with [Revdoku](https://revdoku.com)