Majordomo Documentation

Majordomo is a fully autonomous AI email agent. It connects to your mailbox, reads incoming emails, decides whether to reply or escalate, and sends replies — all without a human in the loop.

→ Create your account and get started

Getting Started

From zero to an autonomous email agent in under five minutes.

1. Create an account

   Sign up at /app/#register. You'll receive a welcome email and 10 free replies to try the platform immediately. No credit card required.
2. Create an agent mailbox

   Click Create Agent on the dashboard. Choose a handle (e.g. support) and your agent email will be support@agents.usemajordomo.com. Alternatively, connect your own mailbox via IMAP/SMTP.
3. Write your persona

   Describe who your agent is, what it knows, and how it should behave. This is the system prompt the LLM receives. Example: "You are Alex, the customer support agent for Acme Corp. Reply concisely to customer enquiries about orders, refunds, and shipping. Never discuss competitor products."
4. Set escalation triggers (optional)

   Enter plain-language conditions for emails that should be forwarded to you rather than auto-replied. Example: "Legal threats or compliance requests", "Refund requests over $500".
5. Test your persona

   Use the Test my persona button to generate 5 sample customer emails and see exactly how your agent would reply — before any real email arrives.
6. Send emails to your agent

   Forward your inbox, publish the agent address, or start routing emails to it. The agent polls for new mail and replies automatically.

Hosted Mailbox

The simplest way to get started. Majordomo creates a dedicated mailbox for your agent at <botname>@agents.usemajordomo.com. No external email provider required.

Requirements

• Botname must be alphanumeric and may contain dashes (e.g. support, alex-agent).
• The address will be <botname>@agents.usemajordomo.com.
• You set a password at creation time; it is encrypted at rest.

Capabilities exclusive to hosted mailboxes

• Reply content retrieval — the dashboard can fetch and display the actual body of sent replies from the IMAP Sent folder.

→ Create a hosted mailbox in the dashboard

External Mailbox (IMAP / SMTP)

Connect any existing email account to Majordomo using standard IMAP and SMTP credentials. Works with Gmail (App Password), Outlook, Fastmail, Zoho, Proton Bridge, and most other providers.

Required fields

DNS Auto-Discovery

When you enter an email address in the wizard, Majordomo queries DNS SRV records for _imap._tcp.<domain> and _submission._tcp.<domain> (RFC 6186) to pre-fill IMAP and SMTP settings automatically. You can override any field manually.

→ Connect your external mailbox in the dashboard

Batch Import (CSV)

Agencies and power users can create multiple agent mailboxes at once by uploading a CSV file. The dashboard wizard includes a batch mode (click Advanced then select Batch CSV).

CSV format

Two row types are supported and can be mixed in the same file:

Hosted mailbox row

agent_name,password
support,S3cretPass!
sales,AnotherP4ss

External IMAP/SMTP row

email,username,password,imap_host,imap_port,smtp_host,smtp_port
alex@acme.com,alex@acme.com,apppassword,imap.acme.com,993,smtp.acme.com,465

• Maximum 100 rows per upload.
• Rows are processed sequentially; a progress bar shows completion.
• Failures on individual rows do not stop the batch — errors are shown inline per row.

→ Import mailboxes via CSV in the dashboard (Create Agent → Advanced)

Mailbox Status Lifecycle

→ View and manage your mailboxes in the dashboard

Persona & Tone

The persona is the most important configuration for your agent. It is passed to the LLM as a system message and defines the agent's entire behavior.

What to include in a persona

• Identity — Name, role, company. "You are Maya, customer success lead at Bright Software."
• Knowledge — What the agent knows: product details, FAQ answers, pricing, policies.
• Tone — How the agent communicates: formal, warm, brief, technical.
• Constraints — What the agent should NOT do: mention competitors, commit to timelines, discuss internal systems.
• Special instructions — When to ask for more information, how to handle attachments, language preferences.

Example persona

You are Alex, the customer support agent for Acme Corp.

Your job is to answer questions about orders, shipping, returns, and our product
catalog. Keep replies short and professional — no more than 3 paragraphs.

Company policies:
- Returns accepted within 30 days of delivery, unused items only.
- Standard shipping takes 3–5 business days. Express available at checkout.
- Refunds are processed within 7 business days.

Never discuss competitor products. If a customer reports a billing dispute over
$500, respond with "I'm escalating this to our billing team" and output NO_ACTION.

Tone field

The Tone field is a short descriptor (e.g. formal, warm and concise, technical) that is appended to the persona prompt. You can achieve the same by including tone instructions in the persona text itself.

Rules field

An additional plain-text rules field that is appended after the persona. Use it for quick operational constraints without rewriting the full persona.

Token limit

Persona text is limited to 2,000 tokens (measured with the cl100k_base tokenizer). The API will reject updates that exceed this limit. If you need a longer context, use the Document Context feature to inject reference material dynamically.

Persona history

Every time you update a mailbox's persona, the previous version is committed to a git repository on the server (WORKING_DIR/persona_history/<email>/). This provides a full audit trail of persona changes over time.

→ Set your persona in the dashboard

Escalation Triggers

Escalation triggers are plain-language conditions that tell the agent when to alert you instead of (or in addition to) replying autonomously. The LLM semantically evaluates each incoming email against your defined triggers — no keyword matching required.

What happens on escalation

1. Email is flagged

   The original email is marked \Flagged $Important in your IMAP inbox so it visually stands out.
2. Tentative reply is generated

   The LLM generates a draft reply showing what the agent would have said — for your reference.
3. Notification email sent to you

   You receive an email at your account address with subject [Majordomo] Escalation: <original subject> containing: sender, original message, and the tentative reply.
4. No reply sent to the original sender

   The agent takes no further action. You decide how to respond.

Example triggers

• Legal threats, lawsuits, or compliance requests
• Refund requests over $500
• Media inquiries or press questions
• Angry or abusive language from the sender
• Requests for custom contract terms or enterprise pricing

Configuring triggers

Enter one trigger per line in the wizard, or a comma-separated list in the mailbox config view. You can add, edit, or remove triggers at any time — changes take effect on the next polling cycle.

→ Configure escalation triggers in the dashboard

Draft Mode

By default the agent sends replies automatically (Auto-reply mode). Switching to Draft mode makes the agent save its replies to your IMAP Drafts folder instead of sending them. You review and send each draft manually.

→ Toggle draft mode in the dashboard

NO_ACTION / DISCARD Signal

You can instruct the agent to deliberately do nothing for certain email types. If the LLM outputs the literal string NO_ACTION (or its synonym DISCARD) as its reply, the agent records a no_action log entry and sends nothing. The email is not marked as read, escalated, or replied to.

When to use it

• Newsletter and digest emails you can't avoid receiving.
• Internal automated notifications you want the agent to skip.
• Conditional logic: handle only English emails, skip all others.
• High-value escalation fallback: when in doubt, output NO_ACTION instead of a wrong reply.

How to configure it

Add instructions to your persona. For example:

If the email is a newsletter, automated digest, marketing email, or social
notification, output exactly: NO_ACTION

→ Add NO_ACTION instructions to your persona in the dashboard

Reply-to-All

Majordomo always performs a reply-to-all when sending autonomous replies. This means the agent preserves the full recipient context of the original email thread rather than replying only to the sender.

How it works

When the agent processes an incoming email it inspects the To and CC headers of that email. The outgoing reply is addressed as follows:

• To — the original sender (From address of the incoming email).
• CC — every address that appeared in the original To or CC headers, excluding the agent's own mailbox address (to avoid self-loop) and the original sender (already in To).

All CC recipients are also included in the SMTP envelope so they actually receive the message.

Example

Original email received by the agent:

From:    alice@example.com
To:      support@agents.usemajordomo.com, bob@example.com
CC:      carol@example.com

Agent reply headers:

From:    support@agents.usemajordomo.com
To:      alice@example.com
CC:      bob@example.com, carol@example.com

Document Context (RAG)

The Document Context feature allows the agent to dynamically fetch and inject relevant documentation into its replies. It is a lightweight Retrieval-Augmented Generation (RAG) system that works over HTTP.

Document context is configured per mailbox — each mailbox can have its own document list, or none at all. Configuration is set in the Agent Rules section of the mailbox settings in the dashboard, or via the API.

How it works

1. Define documents for your mailbox

   In your mailbox settings (Agent Rules tab), provide either an inline JSON array of document objects or a URL that serves such an array. Each document has a name, description, and url.
2. LLM selects relevant documents

   For each incoming email, the LLM is first asked to select which document names are relevant based on the email's subject and body.
3. Documents fetched and injected

   The agent fetches the URLs of selected documents via HTTP (User-Agent: Majordomo-Agent/1.0) and injects the content into the reply prompt as a reference section.
4. Reply generated with context

   The LLM generates a reply using both the persona and the fetched document content.

Configuration formats

There are two ways to configure documents for a mailbox:

Option A — Inline JSON array

Paste a JSON array of document objects directly into the Document Context (RAG) field:

[
  {
    "name": "shipping_policy",
    "description": "Shipping times, costs, and carrier information",
    "url": "https://acme.com/policies/shipping.txt"
  },
  {
    "name": "return_policy",
    "description": "Return and refund process",
    "url": "https://acme.com/policies/returns.txt"
  }
]

Option B — Manifest URL

Enter a single HTTPS URL that returns a JSON array in the same format as above. The agent fetches this URL at runtime whenever a document is needed:

https://acme.com/majordomo-docs.json

The URL must respond with a JSON array. This is useful when you want to manage your document catalog centrally and have multiple mailboxes or agents pick it up automatically.

Field reference

→ Configure document context in your mailbox settings

PDF Attachments

When an incoming email contains PDF attachments, the agent automatically extracts their text content and makes it available to the LLM alongside the email body. This allows the agent to reason about and respond to documents sent by customers — invoices, contracts, reports, etc. — without any extra configuration.

How it works

1. The agent walks the MIME tree of each incoming message looking for application/pdf parts or parts whose filename ends in .pdf.
2. Text is extracted with PyMuPDF (fitz). Only the embedded text layer is read; scanned PDFs without OCR will not yield useful content.
3. Each attachment is appended to the email body under a clearly labelled separator:

--- Attachment: report.pdf ---
(extracted text content of the PDF)

Truncation

To keep prompts within a reasonable size, each PDF is truncated to approximately 20 pages of text (~80,000 characters). If a PDF is cut short, a notice is appended:

[PDF TRUNCATED — showing first ~20 pages]

Limitations

• Scanned PDFs — image-only PDFs without an embedded text layer yield no content. The agent will still reply, but based only on the email body text.
• Encrypted PDFs — password-protected files cannot be extracted. The attachment is silently skipped and the error is recorded in the agent log.
• Large files — very large PDFs are truncated at the 20-page limit. For best results, send focused, concise documents.

Poll Interval

The agent polls each mailbox for new (UNSEEN) emails on a configurable schedule.

→ Set your poll interval in the dashboard

Activity Log

The activity log records every action the agent takes — replies sent, emails escalated, messages skipped, and errors encountered. Email content is never stored; only metadata is logged.

Log entry fields

Action types

Viewing reply content

For hosted @agents.usemajordomo.com mailboxes, the dashboard can retrieve and display the full body of any replied entry by fetching it from the IMAP Sent folder. Click the View action on an activity row to open the reply content.

Pagination

The activity log is paginated. The default page size is 20 entries. Use the API directly for programmatic access with custom page sizes.

→ View your activity log in the dashboard

Stats & Metrics

The dashboard displays three summary metrics for each mailbox:

→ View your stats in the dashboard

Test My Persona

The Test my persona feature lets you preview your agent's behavior before real emails arrive. The system generates 5 realistic sample customer emails based on your persona and shows the agent's replies side by side.

How it works

• Click Test my persona in the mailbox config view.
• The server uses your current persona to generate 5 diverse sample customer emails, then generates a reply for each.
• Results are displayed as an expandable email/reply pair grid.
• Previous test runs are saved in your browser's localStorage for comparison.
• Each test run is logged as a tested_persona action and consumes one reply credit.

→ Test your persona in the dashboard

Plans & Pricing

Agency pricing example

An agency managing 20 client inboxes pays $9.99/mailbox/month = $199.80/month. Each mailbox is fully independent with its own persona, rules, activity log, and billing quota.

→ Upgrade your plan in the dashboard

Quota & Credits

Reply credits are deducted from your account each time the agent sends a reply, saves a draft, or runs a persona test.

How quota is calculated

Your remaining credits are calculated as:
free_credits (10) + purchased_credits + subscription_credits − total_replies_sent

What happens when quota runs out

1. If you have an active subscription, credits are renewed at the next billing date.
2. If you have no subscription, all your mailboxes are set to pending_billing status.
3. You receive a notification email prompting you to purchase more credits.
4. Mailboxes resume automatically once credits are purchased or subscription is reactivated.

→ View your quota and billing in the dashboard

One-Time Credit Packs

Need more replies without committing to a subscription? Purchase a one-time credit pack. Credits are added immediately to your account after payment and never expire.

• Available for purchase from the Settings → Billing view.
• Works alongside a subscription — subscription and purchased credits are pooled together.
• Payment is processed via Stripe. Majordomo never stores payment card details.
• Stripe checkout sessions are idempotent — accidental double-clicks or network retries will not result in double-charging.

→ Purchase a credit pack in Settings → Billing

Privacy by Design

Majordomo is built with email privacy as a first-class concern, not an afterthought.

What is stored

• Account data — Email address, hashed password (bcrypt), Stripe customer ID, subscription status.
• Mailbox config — IMAP/SMTP connection details (password Fernet-encrypted), persona, rules, escalation triggers.
• Activity log metadata — Action type, recipient address, timestamp, reason. No email content.

GDPR & Right to Erasure

Majordomo supports the GDPR Right to Erasure (Article 17). You can permanently delete your account and all associated data at any time.

How to delete your account

1. Go to Settings in the dashboard.
2. Scroll to the Danger Zone section.
3. Click Delete My Account.
4. Confirm the action in the dialog.

This action permanently deletes: your user account, all mailbox configurations, all activity logs, and all associated Stripe data references. The deletion is irreversible.

Data Processing Agreement

For business customers requiring a formal DPA, contact us at contact@agents.usemajordomo.com.

Credential Security

Email passwords

IMAP/SMTP passwords and app tokens are encrypted at rest using Fernet symmetric encryption (AES-128-CBC + HMAC-SHA256) from the Python cryptography library. The encryption key is stored in the server environment and never in the database.

Account passwords

User account passwords are hashed with bcrypt before storage. Plain-text passwords are never persisted or logged.

Session tokens

Authentication uses JWT tokens (HS256, 7-day TTL) stored in the browser's localStorage. Tokens are validated on every protected API request.

What we never log

• Email body content.
• IMAP/SMTP credentials (plain text).
• API keys or OAuth tokens.
• JWT tokens or session secrets.

Unsubscribe

If you receive an unwanted email from a Majordomo agent and wish to opt out, you can unsubscribe at any time. Unsubscribed addresses are added to a global suppression list; Majordomo agents will not send further emails to addresses on this list.

• Visit /unsubscribe.html and submit your email address.
• Or use the unsubscribe link included in the footer of every agent-sent email.

Authentication

All API endpoints except those listed below require a Bearer JWT token in the Authorization header.

Authorization: Bearer <your_jwt_token>

Public endpoints (no token required)

• POST /api/v1/auth/register
• POST /api/v1/auth/login
• GET /api/v1/pricing
• GET /api/v1/email-autoconfig
• GET /api/health
• POST /api/v1/billing/webhook (Stripe; validated by signature)
• POST /api/v1/unsubscribe

Register

// Request
{
  "email":         "you@example.com",
  "password":      "YourSecurePassword",
  "referral_data": { "utm_source": "twitter" }  // optional
}

// Response 200
{
  "id": "uuid",
  "email": "you@example.com",
  "created_at": "2025-01-01T12:00:00Z"
}

Login

// Request
{ "email": "you@example.com", "password": "YourSecurePassword" }

// Response 200
{
  "user": { "id": "...", "email": "..." },
  "token": "eyJhbGc..."
}

Current user

Returns the authenticated user's profile, including subscription status and remaining reply credits.

Delete account

Permanently deletes the user account, all mailboxes, and all activity logs. Irreversible.

Mailboxes API

Update mailbox config

{
  "persona":              "You are Maya...",
  "tone":                 "warm and concise",
  "rules":                "Always sign off with your name.",
  "escalation_triggers":  ["Legal threats", "Refunds over $500"],
  "draft_mode":           0,
  "poll_interval_in_minutes": 60
}

Activity API

Activity list query params

Activity list response

{
  "items": [
    {
      "id":        "uuid",
      "action":    "replied",
      "recipient": "customer@example.com",
      "reason":    "Product availability question",
      "timestamp": "2025-03-20T14:22:00Z"
    }
  ],
  "total": 142,
  "page":  1,
  "size":  20,
  "pages": 8
}

Billing API

Create checkout session

// Subscription
{ "checkout_type": "subscription" }

// One-time credit pack
{ "checkout_type": "one_time" }

// Response
{ "url": "https://checkout.stripe.com/..." }

Utility Endpoints

Email autoconfig

// Response (example: Gmail)
{
  "imap_host": "imap.gmail.com",
  "imap_port": 993,
  "smtp_host": "smtp.gmail.com",
  "smtp_port": 465
}

Self-Hosting Overview

Majordomo is fully self-hostable for teams with strict data residency or security requirements. The entire stack — API, agent process, and frontend — can run on your own infrastructure.

Components

Minimal startup

# 1. Start the API
uvicorn __init__:app --host 0.0.0.0 --port 8000

# 2. Start the agent (separate process)
python agent.py --config config.py

Live reload

The agent process watches agent.py for changes on disk and automatically restarts itself via os.execve when the file is modified. No process manager required for development.

Config Reference

Backend environment variables

Agent config.py variables