Buckets API reference

Create, read, archive and delete buckets.

Requests go to https://api.revdoku.com. Every path starts with /v1, for example https://api.revdoku.com/v1/buckets. Send Authorization: Bearer $REVDOKU_API_KEY from your server. Tables use JSON names; where TypeScript differs, a field shows json_name / typescriptName. Python uses the JSON names.

All operations · API guide · Errors · OpenAPI

• List buckets: GET /v1/buckets
• Create a bucket: POST /v1/buckets
• Read a bucket: GET /v1/buckets/{bucket_id}
• Update a bucket title, description or metadata: PATCH /v1/buckets/{bucket_id}
• Permanently delete an archived bucket: DELETE /v1/buckets/{bucket_id}
• Archive a bucket: POST /v1/buckets/{bucket_id}/archive
• Unarchive a bucket: POST /v1/buckets/{bucket_id}/unarchive
• Lock a bucket or some of its files: POST /v1/buckets/{bucket_id}/lock
• Remove your lock: POST /v1/buckets/{bucket_id}/unlock

List buckets

GET /v1/buckets

Lists active buckets by default, newest first. Counts and pages cover only buckets this credential can access. Reads no email content.

Parameters

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.listBuckets();
for (const bucket of data.buckets) {
  console.log(bucket.id, bucket.title, bucket.email?.address);
}

Python

from revdoku import Revdoku

client = Revdoku()
response = client.list_buckets()
for bucket in response.data.buckets:
    print(bucket.id, bucket.title, bucket.email.address if bucket.email else None)

cURL

curl "https://api.revdoku.com/v1/buckets" \
  -H "Authorization: Bearer $REVDOKU_API_KEY"

Response 200

{
  "success": true,
  "data": {
    "buckets": [
      {
        "id": "bkt_example",
        "account_id": "acct_example",
        "title": "acme-orders",
        "description": null,
        "metadata": {},
        "metadata_version": "44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
        "email": {
          "address": "acme-orders@revdokumail.com",
          "message_count": 1,
          "unread_count": 1,
          "last_received_at": "2026-10-11T12:05:00.000000Z",
          "receiving_enabled": true,
          "sending_enabled": true
        },
        "archived": false,
        "archived_at": null,
        "lock": {"locked": false},
        "storage_bytes": 51840,
        "files_count": 3,
        "version_id": "bktrv_example",
        "version_number": 0,
        "created_at": "2026-10-11T12:00:00.000000Z",
        "updated_at": "2026-10-11T12:05:00.000000Z",
        "dashboard_url": "https://app.revdoku.com/buckets/view?account_id=acct_example&id=bkt_example",
        "archive": {"allowed": true},
        "unarchive": {"allowed": false, "blocked_reason": "not_archived"},
        "delete": {
          "allowed": false,
          "blocked_reason": "not_archived",
          "required_action": "archive_first",
          "confirmation": "delete bkt_example"
        }
      }
    ],
    "counts": {"active": 1, "archived": 0, "total": 1},
    "pagination": {"limit": 50, "has_more": false, "next_cursor": null}
  }
}

Errors

Guide: Buckets

Create a bucket

POST /v1/buckets

Waits until the address can receive email. On revdokumail.com, email.username is the bucket’s name, with no suffix: lowercase letters, digits and single hyphens, 3 to 63 characters, also the name of its site. A name that another bucket uses as an address or a site address, or that another account used, returns EMAIL_ALREADY_EXISTS; your account can use its own earlier names again. Without email.username the address takes the title’s name when it is free, else two readable words. A custom domain takes the exact name. If confirmation does not finish, EMAIL_NOT_READY returns the created bucket_id in error.details: read that bucket instead of creating another. The title defaults to email.username; a title that another active bucket uses returns 409 BUCKET_TITLE_TAKEN. Never retry a creation automatically.

Request body: TypeScript createBucketRequest: CreateBucketRequest, Python create_bucket_request=CreateBucketRequest(...).

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
// Never retry automatically after an uncertain result. List buckets first.
const { data } = await client.createBucket({ username: 'support', title: 'Support' });
console.log(data.bucket.id, data.bucket.email?.address);

Python

from revdoku import Revdoku

client = Revdoku()
# Never retry automatically after an uncertain result. List buckets first.
response = client.create_bucket(username="support", title="Support")
bucket = response.data.bucket
print(bucket.id, bucket.email.address if bucket.email else None)

cURL

curl -X POST "https://api.revdoku.com/v1/buckets" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "bucket": {"title": "Acme docs", "email": {"username": "acme-docs"}}
}'

Response 201

{
  "success": true,
  "data": {
    "bucket": {
      "id": "bkt_example",
      "account_id": "acct_example",
      "title": "acme-orders",
      "description": null,
      "metadata": {},
      "metadata_version": "44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
      "email": {
        "address": "acme-orders@revdokumail.com",
        "message_count": 0,
        "unread_count": 0,
        "last_received_at": null,
        "receiving_enabled": true,
        "sending_enabled": true
      },
      "archived": false,
      "archived_at": null,
      "lock": {"locked": false},
      "storage_bytes": 0,
      "files_count": 0,
      "version_id": "bktrv_example",
      "version_number": 0,
      "created_at": "2026-10-11T12:00:00.000000Z",
      "updated_at": "2026-10-11T12:00:00.000000Z",
      "dashboard_url": "https://app.revdoku.com/buckets/view?account_id=acct_example&id=bkt_example",
      "archive": {"allowed": true},
      "unarchive": {"allowed": false, "blocked_reason": "not_archived"},
      "delete": {
        "allowed": false,
        "blocked_reason": "not_archived",
        "required_action": "archive_first",
        "confirmation": "delete bkt_example"
      }
    }
  }
}

Errors

Error codes named above: BUCKET_TITLE_TAKEN, EMAIL_ALREADY_EXISTS, EMAIL_NOT_READY.

Guide: Create a bucket

Read a bucket

GET /v1/buckets/{bucket_id}

Reading never changes the bucket. Read address settings, emails and files through their own endpoints.

Parameters

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.getBucket({ bucketId: 'bkt_example' });
console.log(data.bucket.title, data.bucket.email?.address);

Python

from revdoku import Revdoku

client = Revdoku()
response = client.get_bucket("bkt_example")
bucket = response.data.bucket
print(bucket.title, bucket.email.address if bucket.email else None)

cURL

curl "https://api.revdoku.com/v1/buckets/bkt_example" \
  -H "Authorization: Bearer $REVDOKU_API_KEY"

Response 200

{
  "success": true,
  "data": {
    "bucket": {
      "id": "bkt_example",
      "account_id": "acct_example",
      "title": "acme-orders",
      "description": null,
      "metadata": {},
      "metadata_version": "44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
      "email": {
        "address": "acme-orders@revdokumail.com",
        "message_count": 1,
        "unread_count": 1,
        "last_received_at": "2026-10-11T12:05:00.000000Z",
        "receiving_enabled": true,
        "sending_enabled": true
      },
      "archived": false,
      "archived_at": null,
      "lock": {"locked": false},
      "storage_bytes": 51840,
      "files_count": 3,
      "version_id": "bktrv_example",
      "version_number": 0,
      "created_at": "2026-10-11T12:00:00.000000Z",
      "updated_at": "2026-10-11T12:05:00.000000Z",
      "dashboard_url": "https://app.revdoku.com/buckets/view?account_id=acct_example&id=bkt_example",
      "archive": {"allowed": true},
      "unarchive": {"allowed": false, "blocked_reason": "not_archived"},
      "delete": {
        "allowed": false,
        "blocked_reason": "not_archived",
        "required_action": "archive_first",
        "confirmation": "delete bkt_example"
      }
    }
  }
}

Errors

Guide: Buckets

Update a bucket title, description or metadata

PATCH /v1/buckets/{bucket_id}

metadata must be a JSON object. It replaces the stored object; {} clears it. Send expected_metadata_version from your last read; a stale value changes nothing and returns BUCKET_METADATA_CONFLICT. Titles are unique among active buckets; a used title returns 409 BUCKET_TITLE_TAKEN.

Parameters

Request body: TypeScript updateBucketRequest: UpdateBucketRequest, Python update_bucket_request=UpdateBucketRequest(...).

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.api.updateBucket({
  bucketId: 'bkt_example',
  updateBucketRequest: { bucket: { title: 'Support' } },
});
console.log(data);

Python

from revdoku import Revdoku, BucketUpdate, UpdateBucketRequest

client = Revdoku()
response = client.api.update_bucket(
    "bkt_example",
    UpdateBucketRequest(bucket=BucketUpdate(title="Support")),
)
print(response.data)

cURL

curl -X PATCH "https://api.revdoku.com/v1/buckets/bkt_example" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bucket": {"title": "Support"}}'

Response 200

Errors

Error codes named above: BUCKET_METADATA_CONFLICT, BUCKET_TITLE_TAKEN.

Guide: Update a bucket

Permanently delete an archived bucket

DELETE /v1/buckets/{bucket_id}

Archive the bucket first. Send delete.confirmation from the bucket read after the user confirms. Large buckets finish deleting in the background.

Parameters

Request body: TypeScript deleteBucketRequest: DeleteBucketRequest, Python delete_bucket_request=DeleteBucketRequest(...).

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.api.deleteBucket({
  bucketId: 'bkt_example',
  deleteBucketRequest: { confirmation: 'CONFIRMATION_FROM_BUCKET_READ' },
});
console.log(data);

Python

from revdoku import Revdoku, DeleteBucketRequest

client = Revdoku()
response = client.api.delete_bucket(
    "bkt_example",
    DeleteBucketRequest(confirmation="CONFIRMATION_FROM_BUCKET_READ"),
)
print(response.data)

cURL

curl -X DELETE "https://api.revdoku.com/v1/buckets/bkt_example" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirmation": "CONFIRMATION_FROM_BUCKET_READ"}'

Response 200

Errors

Guide: Delete a bucket

Archive a bucket

POST /v1/buckets/{bucket_id}/archive

Archived buckets keep their files and emails and become read-only.

Parameters

Request body: TypeScript actionRequest: ActionRequest, Python action_request=ActionRequest(...).

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.api.archiveBucket({
  bucketId: 'bkt_example',
  actionRequest: {},
});
console.log(data);

Python

from revdoku import Revdoku, ActionRequest

client = Revdoku()
response = client.api.archive_bucket("bkt_example", ActionRequest())
print(response.data)

cURL

curl -X POST "https://api.revdoku.com/v1/buckets/bkt_example/archive" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

Errors

Guide: Buckets

Unarchive a bucket

POST /v1/buckets/{bucket_id}/unarchive

Requires bucket-admin permission.

The bucket becomes writable again. If another active bucket has the same title, the title gets a number suffix. A bucket that is not archived returns BUCKET_NOT_ARCHIVED.

Parameters

Request body: TypeScript actionRequest: ActionRequest, Python action_request=ActionRequest(...).

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.api.unarchiveBucket({
  bucketId: 'bkt_example',
  actionRequest: {},
});
console.log(data);

Python

from revdoku import Revdoku, ActionRequest

client = Revdoku()
response = client.api.unarchive_bucket("bkt_example", ActionRequest())
print(response.data)

cURL

curl -X POST "https://api.revdoku.com/v1/buckets/bkt_example/unarchive" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

Errors

Error codes named above: BUCKET_NOT_ARCHIVED.

Guide: Buckets

Lock a bucket or some of its files

POST /v1/buckets/{bucket_id}/lock

Tells other people and agents to wait while you edit. Without paths it locks the whole bucket and requires bucket-admin permission; with paths it locks those files and requires write permission. Others get 423 BUCKET_LOCKED or FILE_LOCKED until you unlock or the lock expires. A lock of someone else also returns 423. Locks never block incoming email. A batch upload (upload_sessions) locks the bucket by itself until it finishes. The MCP tool bucket_lock has the same contract.

Parameters

Request body: TypeScript lockRequest: LockRequest, Python lock_request=LockRequest(...).

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.api.lockBucket({
  bucketId: 'bkt_example',
  lockRequest: { message: 'example' },
});
console.log(data);

Python

from revdoku import Revdoku, LockRequest

client = Revdoku()
response = client.api.lock_bucket(
    "bkt_example",
    LockRequest(message="example"),
)
print(response.data)

cURL

curl -X POST "https://api.revdoku.com/v1/buckets/bkt_example/lock" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "example"}'

Response 200

Errors

Error codes named above: BUCKET_LOCKED, FILE_LOCKED.

Guide: Buckets

Remove your lock

POST /v1/buckets/{bucket_id}/unlock

Removes your lock of the whole bucket (bucket-admin permission) or of the listed files (write permission). A lock of someone else, a running batch upload or a deletion returns 423 BUCKET_LOCKED or FILE_LOCKED. Unlocking an unlocked bucket returns its lock state.

Parameters

Request body: TypeScript unlockRequest: UnlockRequest, Python unlock_request=UnlockRequest(...).

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.api.unlockBucket({
  bucketId: 'bkt_example',
  unlockRequest: {},
});
console.log(data);

Python

from revdoku import Revdoku, UnlockRequest

client = Revdoku()
response = client.api.unlock_bucket("bkt_example", UnlockRequest())
print(response.data)

cURL

curl -X POST "https://api.revdoku.com/v1/buckets/bkt_example/unlock" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

Errors

Error codes named above: BUCKET_LOCKED, FILE_LOCKED.

Guide: Buckets