# AgentWarm > Email warmup infrastructure for AI agents. You connect accounts, we build > sender reputation so your emails land in inboxes, not spam. Base URL: https://app.agentwarm.com Auth: `Authorization: Bearer aw_YOUR_API_KEY` --- ## If you are an AI agent, start here **Step 1.** Get oriented (no auth required): GET /api/agent/capabilities This returns a machine-readable manifest of everything you can do, organized by intent. It includes workflows, error formats, and rate limit info. **Step 2.** See what's happening (requires auth): GET /api/agent/status This returns your complete system state in one call: all domains, all accounts, warmup progress, issues, and what to do next. Use this as your dashboard. Call it at the start of every session. **Step 3.** Do the thing. See the decision tree below. --- ## What do you want to do? I want to... | |-- warm up an email account I already have | |-- Gmail or Outlook? | | `-> OAuth flow: GET /api/auth/gmail/authorize (or outlook) | | then: POST /api/warmup/start/:accountId | `-- IMAP/SMTP (any provider)? | `-> POST /api/accounts {email, provider:"imap_smtp", credentials:{...}} | then: POST /api/warmup/start/:accountId | |-- set up a new domain from scratch | `-> POST /api/domains/onboard (automated pipeline, returns jobId) | then: GET /api/domains/onboard/:jobId/stream (SSE progress) | or step-by-step: import -> configure-dns -> generate-dkim -> verify-dns | |-- redirect warmup domain to company domain (deliverability boost) | `-> POST /api/domains/:id/redirect {target: "https://algomo.com"} | GET /api/domains/:id/redirect-check (verify 301 working) | Works with any DNS provider (Cloudflare, Route 53) | |-- check warmup progress | `-> GET /api/analytics/accounts/:id/progress | GET /api/analytics/accounts/:id/deliverability | |-- diagnose a problem | `-> GET /api/agent/status (check issues + nextActions arrays) | POST /api/accounts/:id/test-connection | GET /api/agent/domains/:id/burn-status | GET /api/agent/burn-report (all domains) | |-- search for and buy new domains | `-> POST /api/agent/domains/search {keyword, tlds?, maxResults?} | POST /api/agent/domains/recommend {keyword, count?} | POST /api/domains/purchase {domain} | |-- autonomous domain lifecycle (capacity + provisioning) | `-> GET /api/agent/capacity (server util, pool health, diversity) | POST /api/agent/plan {targetAccounts?, keyword?} (generate plan) | POST /api/agent/provision {plan, dryRun?} (execute or dry-run) | |-- resurrect a burned domain | `-> GET /api/agent/domains/:id/burn-status (check signals) | POST /api/agent/domains/:id/resurrect (fresh DKIM + gradual re-ramp) | |-- link accounts to CRM (Salesforce, HubSpot, etc.) | `-> POST /api/accounts/:id/crm-links {crmPersonId?, crmAccountId?, crmSource?} | GET /api/accounts/:id/crm-links (list links) | DELETE /api/accounts/:id/crm-links/:linkId | GET /api/accounts?crmPersonId=X (find accounts by CRM person) | GET /api/accounts?crmAccountId=Y (find accounts by CRM account) | GET /api/analytics/crm/person/:personId (aggregated metrics) | GET /api/analytics/crm/account/:accountId (aggregated metrics) | |-- manage at scale (batch operations) | `-> POST /api/accounts/batch (up to 50) | POST /api/warmup/batch/start (up to 100) | POST /api/warmup/batch/pause (up to 100) | |-- connect a Google Workspace or Microsoft 365 org | `-> POST /api/workspace-admin/connect/google-workspace | POST /api/workspace-admin/tenants/:id/users (create users) | POST /api/workspace-admin/tenants/:id/users/batch (up to 50) | |-- get notified when things happen | `-> POST /api/webhooks {url, events:["warmup.email_bounced",...]} | GET /api/webhooks/events/types (20 event types) | |-- receive real-time inbox events via provider push (Gmail / Outlook) | `-> Gmail: POST /api/provider-push/gmail (Google Pub/Sub webhook) | Outlook: POST /api/provider-push/outlook (Graph change notifications) | Outlook lifecycle: POST /api/provider-push/outlook/lifecycle | Push delivers ~6s latency vs 60s polling. Automatic registration | for Gmail OAuth accounts when GMAIL_PUSH_ENABLED=true. | `-- something else `-> Read the full reference: /llms-full.txt Or browse interactively: /api/docs --- ## Core example: Connect an IMAP account and start warmup POST /api/accounts Authorization: Bearer aw_xxxxx Content-Type: application/json { "email": "hello@example.com", "displayName": "Hello", "provider": "imap_smtp", "credentials": { "imapHost": "mail.example.com", "imapPort": 993, "smtpHost": "mail.example.com", "smtpPort": 465, "username": "hello@example.com", "password": "app-password-here" } } -> 201 { "id": "acc-uuid", "email": "hello@example.com", "status": "active", ... } POST /api/warmup/start/acc-uuid -> 200 { "accountId": "acc-uuid", "phase": "ramp_up", "initialDailyLimit": 2 } Warmup starts at 2 emails/day and ramps to 40 over 45 days. Each account gets a `reputationScore` (0–100) = 50 base + inbox placement (×20) + opens (×15) + replies (×15) − bounces (×30) − spam (×40). See full formula and phase details in /llms-full.txt#warmup-mechanics. Monitor with: GET /api/analytics/accounts/acc-uuid/progress -> 200 { "phase": "ramp_up", "dayNumber": 5, "progressPercent": 11, "dailyMetrics": [...] } --- ## How errors work Every error includes a machine-readable code and a suggested next action: { "error": "Account not found", "code": "ACCOUNT_NOT_FOUND", "statusCode": 404, "action": "verify_account_id" } Branch on `code`, not `statusCode`. The `action` field tells you what to try. Full error code list: /llms-full.txt#error-codes ## How responses help you navigate Every successful response includes `_actions` — hypermedia links to what you can do next, based on the current resource state: { "id": "acc-uuid", "status": "active", "_actions": [ { "rel": "start_warmup", "method": "POST", "href": "/api/warmup/start/acc-uuid" }, { "rel": "test_connection", "method": "POST", "href": "/api/accounts/acc-uuid/test-connection" } ]} Follow `_actions` instead of hardcoding URL patterns. ## Rate limits and idempotency - 100 requests/minute per API key. Check `X-RateLimit-Remaining` header. - For POST/PUT/PATCH, include `Idempotency-Key: ` to safely retry. --- ## Full reference - /llms-full.txt Complete API reference with request/response examples - /api/openapi.json OpenAPI 3.1 spec (machine-readable) - /api/docs Interactive Swagger UI - /api/agent/capabilities Machine-readable intent manifest