Mercury Agent setup guide

Mercury Agent is a free, open-source outreach agent built by Altamar. It finds businesses that match your customer, looks for a real reason to write to each one, writes short cold emails, sends them from your own inboxes and drafts your replies. Its AI work runs through Claude Code, so it counts against the Claude Pro or Max plan you already pay for instead of a per-token bill. Nothing is sent until you approve it.

This guide takes you from nothing to your first approved email. Plan on about 30 minutes, most of it spent on the mailbox. The full documentation lives in the Mercury repository.

#Before you start

You need four things:

• Python 3.11 or newer. On a Mac the built-in python3 is often 3.9. If so, install a newer one with Homebrew.
• Claude Code, logged in to a Pro or Max plan. Install it, then run claude login once.
• A mailbox on a separate domain. Buy a second domain (for example getyourcompany.com next to yourcompany.com) and put a Google Workspace inbox on it, about $7 a month. If cold email ever hurts that domain’s reputation, your real email is untouched.
• An email verification key. Reoon gives 600 free checks a month. Without a verifier, Mercury can’t confirm addresses, and it never sends to an address it hasn’t confirmed.

The lazy way: once Mercury is cloned (step 1), run claude inside its folder and say “set up Mercury for me”. Claude Code reads the instructions bundled with the project and walks you through the rest of this guide.

#1. Install

01git clone https://github.com/altamar-dev/MERCURY-AGENT.git mercury-agent02cd mercury-agent03python3 -m venv .venv04source .venv/bin/activate05pip install -e .

This installs the mercury command. Run source .venv/bin/activate again in every new terminal window.

#2. Connect your mailbox

01cp .env.example .env

Open .env and fill in two things: a mail provider and your verifier key (REOON_API_KEY). Each line in the file says where to get its value.

Gmail or Google Workspace (recommended):

1. In Google Cloud Console, create a project and turn on the Gmail API.
2. Set up the OAuth consent screen (internal or testing), then create an OAuth client of type “Desktop app”.
3. Paste its client ID and secret into .env as GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET.
4. Log in once in the browser, then test the connection:

01mercury gmail auth02mercury gmail test

Any other inbox: fill in SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD and IMAP_HOST, then run mercury mail test.

#3. Teach it what you sell

01mercury train https://your-company.com

Mercury reads your website and writes its settings to mercury.local.yaml. Open that file and fix three things before going further. These are the ones that trip most people up:

01persona:02  name: "Your Name"                        # the trainer writes "Mercury"03  email: "you@getyourcompany.com"          # your sending mailbox04 05channels:06  email:07    provider: "gmail"                      # the trainer writes "instantly"; use gmail or smtp08    require_approval: true                 # leave this on09 10compliance:11  postal_address: "123 Main St, City, ST 00000"   # nothing sends until this is set

The postal address goes in the footer of every email, next to an opt-out line, as cold email law requires. Mercury holds the whole outbox until it’s filled in.

#4. Choose what Mercury looks for, then find businesses

Mercury proposes the facts it can collect about each business: reviews, job posts, the owner’s name, whether they run ads, and more. It collects only the ones you confirm. Start with everything that costs nothing:

01mercury signals --confirm free02mercury discover --estimate03mercury discover

--estimate shows what a search would cost without running it. The default source, OpenStreetMap, is free and needs no account. It’s thin for businesses without a storefront, so mercury discover --providers lists paid sources and their prices if you need more. Every paid run stops at a hard spend cap.

#5. Open the dashboard and approve your first emails

01mercury dashboard

Open http://127.0.0.1:5555. Then start Mercury in a second terminal (activate the venv there too):

01mercury run

Every 15 minutes it checks addresses, writes a three-email sequence for each confirmed contact and stages them in the Outbox. Nothing leaves until you approve it. In the Outbox, press J and K to move between drafts, fix any word in place, and press A to approve. Read the first ten closely. If they miss, tell Mercury what to change and it rewrites the draft.

#Week one: go slow

• Five emails a day. New inboxes start at 5 a day and add 5 a week. Don’t raise it. Sending too much from a new inbox is the fastest way into spam.
• Check your email settings. The Mailboxes tab checks your domain’s SPF, DKIM and DMARC records. Fix anything marked red before you send.
• Watch bounces. Over 3% bounces holds an inbox at yesterday’s volume, and over 5% pauses it until you resume it. If that happens, stop and look at your list before you send more.
• Answer the replies. Mercury sorts replies and drafts an answer for each one, but you approve it, the same as the first email. Anyone who asks to stop never hears from you again.
• Emergency stop: mercury sending pause stops all outgoing mail immediately.

Following cold email law (CAN-SPAM in the US, GDPR in Europe) is your responsibility as the sender. Mercury adds the footer and honors opt-outs, but you choose who to write to.

#If something goes wrong

• Nothing sends: check compliance.postal_address and channels.email.provider in mercury.local.yaml, then confirm the emails are approved in the Outbox.
• Every address says “guess”: add a verifier key to .env. Guessed addresses are never sent.
• mercury: command not found: activate the venv with source .venv/bin/activate.
• Discovery refuses to run: confirm at least one signal with mercury signals --confirm free.

Stuck on something else? Reply to the Instagram message that sent you this guide, or open an issue on GitHub.