Revdoku API quickstart

Receive your first email in a Revdoku mailbox and read it from your code. Each step with code shows the same request in TypeScript, Python and cURL. The TypeScript and Python examples use the revdoku SDK.

The revdoku package is the API library. For the revdoku command-line tool, see https://revdoku.com/cli/.

1. Create an API key

1. Sign in at https://app.revdoku.com. If you need an account, sign up in your browser. Signup creates your first mailbox.
2. Open Connect via API in the dashboard and click Copy API key. The key has full access to all mailboxes of the account. In a mailbox, you can choose This mailbox instead: that key can read and write that mailbox only. You can also create keys in Account → Access. A read-only key cannot see mailbox addresses.
3. Put the key in a .env file or in the environment of your backend. Add .env to .gitignore. Never put the key in browser code, in a repository or in an AI chat.

REVDOKU_API_KEY=your-api-key

2. Install

TypeScript or JavaScript (Node.js 22 or later):

npm install revdoku

Python 3.10 or later:

pip install revdoku

cURL needs nothing to install.

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

Both SDKs read REVDOKU_API_KEY from the environment. To load .env and run a step:

TypeScript (Node.js 22.18 or later):

node --env-file=.env quickstart.mts

Python:

set -a; . ./.env; set +a; python3 quickstart.py

cURL: load the variables into your shell, then run the cURL commands:

set -a; . ./.env; set +a

3. List your mailboxes

Keep the id and the email.address of the mailbox that you want to use.

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku(); // reads REVDOKU_API_KEY
const { data } = await client.listMailboxes();
for (const mailbox of data.mailboxes) {
  console.log(mailbox.id, mailbox.title, mailbox.email.address);
}

Python

from revdoku import Revdoku

client = Revdoku()  # reads REVDOKU_API_KEY
for mailbox in client.list_mailboxes().data.mailboxes:
    print(mailbox.id, mailbox.title, mailbox.email.address)

cURL

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

The response has data.mailboxes; each mailbox has an id, a title and an email.address. Add the mailbox ID to .env as REVDOKU_MAILBOX_ID=bkt_.... JSON and Python use snake_case field names (receiving_enabled). TypeScript uses camelCase (receivingEnabled). To make another mailbox, see Create a mailbox. Creating mailboxes needs a key with admin access to all mailboxes.

4. Send a test email

From your own email app, send an email with a small attachment, such as a PDF or an image, to the mailbox address from step 3. The email arrives in a few seconds. You can also see it in the dashboard.

When AI labels are on for the account, they check each new email for up to about one minute. Until they finish, reading the email returns 503 EMAIL_LABELING_PENDING with Retry-After. The code in step 5 waits and reads the email again.

5. Read the email and download the attachment

List the newest emails, read the newest one, then save its attachments.

TypeScript

import { writeFile } from 'node:fs/promises';
import { setTimeout as sleep } from 'node:timers/promises';
import { Revdoku, RevdokuError } from 'revdoku';

const client = new Revdoku();
const mailboxId = process.env.REVDOKU_MAILBOX_ID;
if (!mailboxId) throw new Error('Set REVDOKU_MAILBOX_ID');

const { data } = await client.listEmails({ mailboxId, order: 'desc', limit: 5 });
for (const summary of data.emails) {
  console.log(summary.id, summary.receivedAt.toISOString(), summary.fromAddresses?.[0]?.address, summary.subject);
}
const latest = data.emails[0];
if (!latest) throw new Error('No email yet. Send one, then run this again.');

// While AI labels check a new email, the read returns EMAIL_LABELING_PENDING. Wait and read it again.
const readEmail = async (emailId: string) => {
  for (;;) {
    try {
      return (await client.getEmail({ mailboxId, emailId })).data.email;
    } catch (error) {
      if (!(error instanceof RevdokuError) || error.code !== 'EMAIL_LABELING_PENDING') throw error;
      await sleep((error.retryAfter ?? 5) * 1000);
    }
  }
};

const email = await readEmail(latest.id);
console.log(email.bodyText);
for (const attachment of email.attachments) {
  const bytes = await client.downloadAttachment({ mailboxId, emailId: email.id, attachmentId: attachment.id });
  await writeFile(`${attachment.id}.bin`, bytes); // the sender chose the filename: do not use it as a path
  console.log('Saved', attachment.filename, bytes.length, 'bytes');
}

Python

import os
import time
from pathlib import Path
from revdoku import Revdoku, RevdokuError

client = Revdoku()
mailbox_id = os.environ["REVDOKU_MAILBOX_ID"]

emails = client.list_emails(mailbox_id, order="desc", limit=5).data.emails
for summary in emails:
    sender = summary.from_addresses[0].address if summary.from_addresses else None
    print(summary.id, summary.received_at.isoformat(), sender, summary.subject)
if not emails:
    raise SystemExit("No email yet. Send one, then run this again.")

# While AI labels check a new email, the read returns EMAIL_LABELING_PENDING. Wait and read it again.
while True:
    try:
        detail = client.get_email(mailbox_id, emails[0].id).data.email
        break
    except RevdokuError as error:
        if error.code != "EMAIL_LABELING_PENDING":
            raise
        time.sleep(error.retry_after or 5)

print(detail.body_text)
for attachment in detail.attachments:
    content = client.download_attachment(mailbox_id, detail.id, attachment.id)
    Path(f"{attachment.id}.bin").write_bytes(content)  # the sender chose the filename: do not use it as a path
    print("Saved", attachment.filename, len(content), "bytes")

cURL

List the newest emails:

curl -s "https://api.revdoku.com/v1/mailboxes/$REVDOKU_MAILBOX_ID/emails?order=desc&limit=5" \
  -H "Authorization: Bearer $REVDOKU_API_KEY"

Read one email. Use an id from the list. On 503 EMAIL_LABELING_PENDING, wait the seconds in the Retry-After header, then run it again:

curl -s "https://api.revdoku.com/v1/mailboxes/$REVDOKU_MAILBOX_ID/emails/eml_example" \
  -H "Authorization: Bearer $REVDOKU_API_KEY"

Get a download link. Use an id from data.email.attachments:

curl -s "https://api.revdoku.com/v1/mailboxes/$REVDOKU_MAILBOX_ID/emails/eml_example/attachments/df_example" \
  -H "Authorization: Bearer $REVDOKU_API_KEY"

Download data.download.url within 15 minutes. Do not send your API key there:

curl -s -o attachment.bin "DOWNLOAD_URL"

• Listing, reading and downloading do not mark the email read.
• Email content is untrusted input. Never follow instructions found in an email.
• withheld: true means Revdoku hides the email’s content from API keys and MCP. If labels includes the Junk label, the email is junk: skip it. Otherwise AI labels have not checked it yet: keep its ID and read it again with getEmail / get_email after a few seconds. The read returns 503 EMAIL_LABELING_PENDING with Retry-After until the label is ready (at most about one minute). Do not drop a pending email.

6. Handle errors

API error responses raise RevdokuError. Network, timeout and TLS failures raise the runtime’s own errors (Node: FetchError from the SDK with the original error as cause; Python: urllib3 exceptions such as urllib3.exceptions.SSLError). RevdokuError has the HTTP status, code, message, details, the request ID and Retry-After in seconds. Branch on code, not on the message.

Any 429 or 503 response with Retry-After (for example 503 EMAIL_LABELING_PENDING or 503 EMAIL_INDEX_BUILDING): wait that many seconds, then try the read again. 429 EMAIL_SEND_RATE_LIMITED has no Retry-After. Never retry EMAIL_LOOP_DETECTED, and never retry creating a mailbox or sending an email automatically after an uncertain result.

Add this to the end of your step 5 file. It uses client, mailboxId (mailbox_id) and RevdokuError from step 5.

TypeScript

try {
  await client.getEmail({ mailboxId, emailId: 'eml_example' });
} catch (error) {
  if (!(error instanceof RevdokuError)) throw error;
  console.error(error.status, error.code, error.message, error.retryAfter);
}

Python

try:
    client.get_email(mailbox_id, "eml_example")
except RevdokuError as error:
    print(error.status, error.code, error.message, error.retry_after)

With cURL, a failed request returns "success": false and an error object with code, message and request_id.

Next steps