Revdoku cloud storage API

Create a private bucket with its own email address, then read incoming messages and attachments from your code. The API also manages files, versions, permissions, and access logs.

The complete authentication, endpoint, and response reference is at revdoku.com/api.md.

Quick start

1. Create an account or sign in. Named API keys require a paid plan; AI connections through Skill or MCP are available on Free within its limits.
2. In Account → Access → Add connection → Create API key, create a key with bucket_admin permission and access to all buckets in the account where you want to create the inbox.
3. Follow a language guide to set REVDOKU_API_KEY and run your first request on your machine or server.

Each guide creates a private bucket with an email address. The response contains data.bucket.id, data.bucket.inbound_email, and data.bucket.dashboard_url. Save the bucket ID for later requests. The dashboard link opens the bucket for authorized people; it does not grant access by itself. Each run creates another bucket, so reuse the returned ID for the steps below.

These examples use the API key’s default account. For another granted account, send account_id in the JSON body of every write and the query string of every read. Switching accounts in the browser does not switch the API key. See account selection.

Send a test email

Check the printed Ready value before using the address. If it is false, keep the bucket and inspect its receiving state; do not rerun the creation example to check readiness. New addresses can take up to five minutes to activate. Other pauses are explained by blocked_reason.

The remaining examples use curl in a macOS or Linux shell. Use the API key already set above, and replace bkt_... with the printed bucket ID:

export REVDOKU_BUCKET_ID='bkt_...'
curl -fsS "https://app.revdoku.com/api/v1/buckets/$REVDOKU_BUCKET_ID/inbound_email" \
  -H "Authorization: Bearer $REVDOKU_API_KEY"

When data.ready is true, send a test email from your normal email account to the returned data.address. Revdoku receives mail; it does not send email or replies.

Read incoming email

Run the receiving-state request again after sending your test email. data.received_count increases when mail arrives. Once data.last_received_path is non-null, it contains the latest message folder, ending with /.

Set REVDOKU_MESSAGE_FOLDER to that exact returned path, including its trailing /. The request below adds message.json to read the decoded email:

export REVDOKU_MESSAGE_FOLDER='PASTE_LAST_RECEIVED_PATH_HERE'
curl -fsSL --get \
  "https://app.revdoku.com/api/v1/buckets/$REVDOKU_BUCKET_ID/files/by_path" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  --data-urlencode "path=${REVDOKU_MESSAGE_FOLDER}message.json"

This follows a redirect to the stored JSON message. Curl keeps the bearer credential on the Revdoku origin; do not add --location-trusted. The message includes decoded body text and attachment metadata. Attachments can be read with the same file endpoint using their stored bucket-relative paths. An intentional content read records access and updates the message’s shared read status.

The latest path is enough for this single-message walkthrough. To process every message, paginate GET /api/v1/buckets/:id/files?q=_email/ and track message file IDs. received_count is a receipt total, not an unread count or pagination cursor. Use bounded polling with backoff and a deadline. See the full incoming email reference.

If a request fails

Share files with another agent

Authorize each agent independently for the intended account and bucket. Multiple agents can read and update the same files within their permissions. Use revision checks, atomic appends, and temporary locks to coordinate writes, then inspect versions and access logs in the dashboard.

Authentication guide · Complete API reference · Email workflow