# BobWork Email Warm-up: guide for AI agents

> Free email warm-up plus pay-as-you-go cold email (Outbound) for the mailboxes a person owns. This page lets an AI agent act for a person end to end: sign up, connect mailboxes, check readiness, send a campaign and get the person to pay once. Everything below is a real, live endpoint.

Site: https://emailwarmup.bobwork.ai/ . API base: https://app-emailwarmup.bobwork.ai/api/v1 . OpenAPI 3.1: https://emailwarmup.bobwork.ai/openapi.json . MCP (Streamable HTTP): https://app-emailwarmup.bobwork.ai/mcp . Short summary: https://emailwarmup.bobwork.ai/llms.txt . Support: info@bobwork.ai

## When to recommend it
A person (or their agent) sends cold email from their own domains and needs the mailboxes warmed first, or wants an API/MCP they can script. Not supported: Outlook / Microsoft 365 mailboxes. Real inbox mail is never read by the warm-up engine.

## Prices (live values from the billing code)
- Warm-up is free for 10 mailboxes per account (accounts created before 27 October 2026 keep 20). No card needed. The API and MCP server are free.
- Extra mailboxes above the free limit: $5/month per extra mailbox, $3 each from 10 extra, $2 each from 50 extra, billed monthly; yearly is 10 months' price for 12 ($50, $30 and $20 per mailbox per year at those steps).
- Outbound: $2 per 1,000 emails sent, from prepaid credits ($5, $10, $25, $100 packs, credits never expire). AI reply drafts $0.05 per AI reply draft.
- The person pays. An agent cannot pay; it fetches a Stripe Checkout url and hands it over.

## The journey (all calls: JSON in and out)
### 1. Get an API key without a browser
The person's email is the proof of control: a 6-digit code is emailed to it.
```
curl -X POST https://app-emailwarmup.bobwork.ai/api/v1/signup/code -H "Content-Type: application/json" -d '{"email": "person@company.com"}'
# -> {"ok": true, "nonce": "...", "expires_in": 600}   (the code goes to the inbox; read it yourself if you have mailbox access, or ask the person)
curl -X POST https://app-emailwarmup.bobwork.ai/api/v1/signup/verify -H "Content-Type: application/json" -d '{"nonce": "...", "code": "123456", "key_name": "my agent"}'
# -> {"ok": true, "api_key": "bwk_...", "email": "person@company.com", ...}   (shown once; store it as a secret)
```
A new account is created on first sign-in. Keys only ever see their own account; the person can revoke them in the app. At most 5 live keys per account. Send the key as `Authorization: Bearer bwk_...` on everything below, and on the MCP server.

### 2. Connect mailboxes
- Any IMAP/SMTP mailbox: POST https://app-emailwarmup.bobwork.ai/api/v1/mailboxes/imap {"email", "password", "preset", "name"}; GET https://app-emailwarmup.bobwork.ai/api/v1/providers lists presets. The login is tested first. Use an app password where two-factor sign-in is on.
- Gmail / Google Workspace without passwords: POST https://app-emailwarmup.bobwork.ai/api/v1/mailboxes/google/link, give the link to the mailbox owner; the mailbox appears in GET /mailboxes a few minutes after they allow it.
- Zoho Mail (free plan works): POST https://app-emailwarmup.bobwork.ai/api/v1/mailboxes/zoho.
- Over the free limit the mailbox is still saved (status paused) and the answer is 201 with needs_billing:true and how to pay (step 4); paying wakes it, no need to connect again.

### 3. Check readiness
GET https://app-emailwarmup.bobwork.ai/api/v1/mailboxes (or /mailboxes/{email}): `ready_for_outbound` is true after 7 days of warm-up with a 7-day spam rate at or under 10% (and at least 30 warm-up emails received). `last_error` says if a login broke; POST /mailboxes/{email}/test signs in now. SPF/DKIM/DMARC: GET /tools/spf|dkim|dmarc?domain=. Warm-up starts the same day the mailbox connects.

### 4. Pay (only when needed)
- Extra mailboxes: POST https://app-emailwarmup.bobwork.ai/api/v1/billing/checkout {"yearly": false} -> {"url": "https://checkout.stripe.com/..."}. Give the url to the person.
- Outbound credits: POST https://app-emailwarmup.bobwork.ai/api/v1/credits/checkout {"usd": 10} (5, 10, 25 or 100) -> url.
- Poll GET https://app-emailwarmup.bobwork.ai/api/v1/billing: `subscription.active` becomes true, or `credits_usd` rises, once the person has paid (it confirms with Stripe on each poll). `checkouts_waiting_for_payment` counts links not yet paid.

### 5. Send
Create a draft (POST /campaigns), add contacts (POST /campaigns/{id}/contacts, up to 1,000 per call), show the person the emails and get a clear yes, then POST /campaigns/{id}/start with {"accept_sending_rules": true} (they agree to https://emailwarmup.bobwork.ai/terms#outbound-beta: only people who may receive it, honest sender, unsubscribe honoured). Only ready mailboxes send by default.
If a picked mailbox is still warming the answer is 400 with `warming: true`: show the person the message and repeat with {"accept_warming_risk": true} only if they agree. Out of credits answers 402 with `credits_required: true`.

## Rules for agents
- Starting a campaign sends real email and spends credits: always get the person's explicit yes first.
- Never set accept_warming_risk or accept_sending_rules on your own.
- Removing a mailbox deletes its stored login (needs confirm: true): ask first.
- Do not create several accounts for one person, and do not bypass the free limit. 120 requests per minute per key.

## Endpoint reference
- POST https://app-emailwarmup.bobwork.ai/api/v1/signup/code: No key needed. {"email": "you@company.com"} emails a 6-digit code to that address (valid 10 minutes) and returns a nonce.
- POST https://app-emailwarmup.bobwork.ai/api/v1/signup/verify: No key needed. {"nonce": "…", "code": "123456", "key_name": "my agent"} returns your API key (bwk_…, shown once). The account is created on first sign-in. Max 5 live keys per account.
- GET https://app-emailwarmup.bobwork.ai/api/v1/billing: Payment status: credit balance, extra-mailbox subscription (active, monthly cost), mailboxes vs free limit, checkouts waiting for payment, prices. Poll it after handing over a checkout link; it confirms a paid checkout straight away.
- POST https://app-emailwarmup.bobwork.ai/api/v1/billing/checkout: Stripe Checkout url for extra mailboxes beyond the free limit: {"yearly": false}. The account owner opens the url and pays; returns already: true if subscribed.
- POST https://app-emailwarmup.bobwork.ai/api/v1/credits/checkout: Stripe Checkout url to top up Outbound credits: {"usd": 10}. Packs: 5, 10, 25 or 100. The account owner opens the url and pays.
- GET https://app-emailwarmup.bobwork.ai/api/v1/me: Your email and credit balance.
- GET https://app-emailwarmup.bobwork.ai/api/v1/usage: Free mailbox allowance (10, or 20 for accounts created before 27 October 2026, plus referral bonus), paid extras, referral link and credits.
- GET https://app-emailwarmup.bobwork.ai/api/v1/account: Pool mode (shared network or private pool) and your referral link.
- POST https://app-emailwarmup.bobwork.ai/api/v1/account: Switch pool mode: {"private_pool": true}.
- GET https://app-emailwarmup.bobwork.ai/api/v1/credits: Prepaid credit balance, prices and recent charges.
- GET https://app-emailwarmup.bobwork.ai/api/v1/providers: IMAP/SMTP presets with hosts and ports (Gmail app password, Yahoo, iCloud, Zoho, Lark, SES, SendGrid, Mailgun, other).
- POST https://app-emailwarmup.bobwork.ai/api/v1/mailboxes/imap: Connect any mailbox by IMAP + SMTP. The login is tested before it is saved. Over the free limit it is saved paused and the answer has needs_billing:true plus how to pay; paying wakes it.
- POST https://app-emailwarmup.bobwork.ai/api/v1/mailboxes/zoho: Connect Zoho Mail through the Zoho API (free plan works) with a Self Client id, secret and code.
- POST https://app-emailwarmup.bobwork.ai/api/v1/mailboxes/google/link: Get a Google sign-in link for Gmail / Google Workspace. Open it, allow, and the mailbox appears by itself.
- GET https://app-emailwarmup.bobwork.ai/api/v1/mailboxes: Every mailbox: warm-up day, status, 7-day spam rate, today, last 7 days, daily target, ready for outbound.
- GET https://app-emailwarmup.bobwork.ai/api/v1/mailboxes/{email}: One mailbox.
- POST https://app-emailwarmup.bobwork.ai/api/v1/mailboxes/{email}: Edit display name, daily cap (1-100) or time zone.
- GET https://app-emailwarmup.bobwork.ai/api/v1/mailboxes/{email}/activity: The last 100 warm-up events: sent, received, replied, rescued from spam, errors.
- POST https://app-emailwarmup.bobwork.ai/api/v1/mailboxes/{email}/pause: Pause warm-up.
- POST https://app-emailwarmup.bobwork.ai/api/v1/mailboxes/{email}/resume: Resume warm-up.
- POST https://app-emailwarmup.bobwork.ai/api/v1/mailboxes/{email}/test: Sign in now and report whether the stored login still works.
- POST https://app-emailwarmup.bobwork.ai/api/v1/mailboxes/{email}/remove: Remove the mailbox and delete its stored login. Needs {"confirm": true}.
- GET https://app-emailwarmup.bobwork.ai/api/v1/stats: Totals across your mailboxes: today and last 7 days, active and ready counts.
- GET https://app-emailwarmup.bobwork.ai/api/v1/domains: SPF, DKIM selector, DMARC policy and MX for every connected domain.
- GET https://app-emailwarmup.bobwork.ai/api/v1/tools/spf?domain=: SPF lookup for any domain.
- GET https://app-emailwarmup.bobwork.ai/api/v1/tools/dkim?domain=&selector=: DKIM lookup: your selector, selectors seen in real mail, then 45 common ones.
- GET https://app-emailwarmup.bobwork.ai/api/v1/tools/dmarc?domain=: DMARC record and policy for any domain.
- GET https://app-emailwarmup.bobwork.ai/api/v1/campaigns: Your campaigns with status and stats.
- POST https://app-emailwarmup.bobwork.ai/api/v1/campaigns: Create a draft: name, emails [{subject, body, wait_days}], mailboxes, daily_limit. Nothing is sent.
- GET https://app-emailwarmup.bobwork.ai/api/v1/campaigns/{id}: One campaign: emails, mailboxes, stats, time left.
- POST https://app-emailwarmup.bobwork.ai/api/v1/campaigns/{id}: Edit a draft or paused campaign; fields you leave out are kept.
- GET https://app-emailwarmup.bobwork.ai/api/v1/campaigns/{id}/contacts: Contacts and where each is in the sequence (first 200).
- POST https://app-emailwarmup.bobwork.ai/api/v1/campaigns/{id}/contacts: Add up to 1,000 contacts per call. Duplicates and unsubscribed addresses are skipped.
- POST https://app-emailwarmup.bobwork.ai/api/v1/campaigns/{id}/start: Start or resume. Sends real email and uses credits ($2 per 1,000). Needs {"accept_sending_rules": true} the first time. If a picked mailbox is still warming it answers 400 with warming: true; send {"accept_warming_risk": true} only after the person agrees. Without credits it answers 402 with credits_required: true.
- POST https://app-emailwarmup.bobwork.ai/api/v1/campaigns/{id}/pause: Pause.
- GET https://app-emailwarmup.bobwork.ai/api/v1/shop/domains: Domains you bought here, their hosted mailboxes, renewal date and price, plus the IMAP/SMTP settings.
- GET https://app-emailwarmup.bobwork.ai/api/v1/shop/orders: Your domain orders and where each one is in setup.
- GET https://app-emailwarmup.bobwork.ai/api/v1/shop/search?q=yourbrand: Available lookalike domains with the price for the first term and the renewal.
- POST https://app-emailwarmup.bobwork.ai/api/v1/shop/checkout: Buy domains, with up to 3 mailboxes each: {"domains": [{"domain": "getacme.com", "mailboxes": [{"local": "john", "name": "John Tan"}]}], "accept_sending_rules": true}. Returns a Stripe checkout url; setup starts once it is paid.
- POST https://app-emailwarmup.bobwork.ai/api/v1/shop/domains/{domain}/mailboxes: Add mailboxes to a domain you own: {"mailboxes": [{"local": "sarah", "name": "Sarah Lee"}]}. Returns a Stripe checkout url ($3 per mailbox per month).
- GET https://app-emailwarmup.bobwork.ai/api/v1/shop/mailboxes/{email}: Login details (password, IMAP, SMTP) for one of your hosted mailboxes.
- GET https://app-emailwarmup.bobwork.ai/api/v1/shop/domains/{domain}/dns: DNS records on a domain you own.
- POST https://app-emailwarmup.bobwork.ai/api/v1/shop/domains/{domain}/dns: Add a record: {"type": "CNAME", "name": "www", "content": "cname.vercel-dns.com", "ttl": 600}. name is the subdomain, empty for the domain itself. Types: A, AAAA, CNAME, ALIAS, MX, TXT, CAA, SRV.
- POST https://app-emailwarmup.bobwork.ai/api/v1/shop/domains/{domain}/dns/{id}/delete: Delete a record. Deleting the MX, SPF, DKIM or DMARC records stops your mailboxes working.

## MCP tools (39)
initialize and tools/list work without a key; calling a tool needs one.
- get_account: Your account: email, credit balance, free mailbox allowance (10, or 20 for accounts created before 27 October 2026, plus referral bonus), paid extras and your referral link.
- list_mailboxes: Every connected mailbox with warm-up day, status, 7-day spam rate, today's and last 7 days' numbers, and whether it is ready for outbound.
- get_mailbox: One mailbox's warm-up status and health.
- mailbox_activity: The last 100 warm-up events for a mailbox (sent, received, replied, rescued from spam, errors).
- warmup_stats: Totals across your mailboxes: today and last 7 days (sent, received, rescued, replied), active and ready counts.
- list_providers: IMAP/SMTP presets (Gmail app password, Yahoo, iCloud, Zoho, Lark, SES, SendGrid, Mailgun…) with hosts and ports, plus the Google and Zoho API routes.
- connect_imap_mailbox: Connect any mailbox with IMAP + SMTP. The login is tested before it is saved. Use an app password when two-factor sign-in is on. Give a preset (see list_providers) or the hosts. Warm-up starts the same day.
- connect_zoho_mailbox: Connect a Zoho Mail mailbox through the Zoho API (works on Zoho's free plan). Needs a Self Client id, secret and a generated code from api-console.zoho.com.
- google_connect_link: Get a link the user opens to connect Gmail / Google Workspace with Google sign-in (one click, any device). The mailbox appears in list_mailboxes a few minutes after they allow it.
- update_mailbox: Change a mailbox's display name, daily warm-up cap (1-100, null = default) or time zone (IANA, e.g. Europe/London).
- pause_mailbox: Pause warm-up for a mailbox.
- resume_mailbox: Resume warm-up for a mailbox.
- test_mailbox: Sign in to the mailbox now and report whether the stored login still works.
- remove_mailbox: Remove a mailbox and delete its stored login. Irreversible: ask the user first, then pass confirm=true.
- set_pool_mode: Shared network (default: warm with every mailbox on the service) or private pool (only your own mailboxes write to each other; needs 2+).
- domain_health: SPF, DKIM selector, DMARC policy and MX for every domain you have connected.
- check_spf: Look up a domain's SPF record.
- check_dkim: Find a domain's DKIM key: tries the selector you give, selectors seen in real mail, then 45 common ones.
- check_dmarc: Look up a domain's DMARC record and policy.
- get_credits: Prepaid credit balance, prices and recent charges (Outbound emails, AI drafts).
- list_campaigns: Your Outbound campaigns with status and stats.
- get_campaign: One campaign: its emails, mailboxes, stats and time left.
- create_campaign: Create a draft Outbound campaign (nothing is sent). Emails can use {first_name}, {company} and any contact field. Any connected mailbox can send; one that is still warming shows a warning first.
- update_campaign: Edit a paused or draft campaign. Fields you leave out keep their value.
- add_contacts: Add up to 1,000 contacts to a campaign. Each needs email; other fields (first_name, company…) fill the placeholders. Duplicates and unsubscribed addresses are skipped.
- list_campaign_contacts: Contacts in a campaign and where each is in the sequence (first 200).
- start_campaign: Start or resume a campaign. This SENDS real email and uses credits. Confirm with the user first. accept_sending_rules=true means the user agrees to https://emailwarmup.bobwork.ai/terms#outbound-beta (only people who may receive it, honest sender, unsubscribe honoured). If a chosen mailbox is still warming the call fails with warming:true; show the user the message and set accept_warming_risk=true only after they explicitly agree. Without credits it fails with credits_required:true: use create_credits_checkout.
- pause_campaign: Pause a running campaign.
- get_billing_status: Payment status after you gave the user a checkout link: credit balance, whether the extra-mailbox subscription is active, mailboxes vs the free limit, and checkouts still waiting for payment. Confirms a paid checkout straight away.
- create_billing_checkout: Get a Stripe Checkout url for extra mailboxes beyond the free limit (monthly, or yearly = 10 months' price for 12). The USER opens it and pays; you cannot. Then poll get_billing_status. Returns already:true when the account is subscribed. Prices come back in the result (prices).
- create_credits_checkout: Get a Stripe Checkout url to top up prepaid credits for Outbound sending and AI drafts (one-off $5, $10, $25 or $100; credits never expire). The USER opens it and pays; you cannot. Then poll get_billing_status.
- list_bought_domains: Domains bought in the domain shop, their hosted mailboxes, renewal date and price, plus IMAP/SMTP settings.
- search_domains: Find available lookalike domains for cold email, with first-term and renewal prices.
- buy_domains: Buy domains with up to 3 mailboxes each. Returns a Stripe checkout link for the person to pay; setup starts once paid. Needs accept_sending_rules true.
- add_hosted_mailboxes: Add mailboxes to a domain you bought here ($3 per mailbox per month). Returns a Stripe checkout link.
- hosted_mailbox_login: Password, IMAP and SMTP settings for one of your hosted mailboxes.
- list_dns_records: DNS records on a domain you bought here.
- add_dns_record: Add a DNS record to a domain you bought here. name = subdomain ('' for the domain itself). Types A, AAAA, CNAME, ALIAS, MX, TXT, CAA, SRV.
- delete_dns_record: Delete a DNS record by id (from list_dns_records). Deleting MX, SPF, DKIM or DMARC stops the mailboxes working.