AskOptimus API

Authentication

All API requests require a Bearer token. Obtain your API key from the Settings → API page in the AskOptimus dashboard.

Include the token in the Authorization header:

Authorization: Bearer <your-api-key>

Base URL

All endpoints are relative to the base URL:

https://api.askoptimus.ai/v2/api/

Example: GET /email-finder becomes https://api.askoptimus.ai/v2/api/email-finder.

Making Requests

All requests are JSON over HTTPS. Use the Content-Type header set to application/json for POST/PUT requests.

Example using curl:

curl https://api.askoptimus.ai/v2/api/email-finder \
                -H "Authorization: Bearer $API_KEY" \
                -H "Content-Type: application/json" \
                -d '{"name":"John Doe","domain":"acme.com"}'

Example using JavaScript:

const response = await fetch(
                "https://api.askoptimus.ai/v2/api/email-finder",
                {
                  method: "POST",
                  headers: {
                    "Authorization": `Bearer ${API_KEY}`,
                    "Content-Type": "application/json",
                  },
                  body: JSON.stringify({ name, domain }),
                }
              );
              const data = await response.json();

Endpoints

Email Finder

Find a verified email address for a person at a given domain. Uses pattern matching, public sources, and proprietary heuristics.

Request body

{
  "name": "John Doe",          // optional
  "domain": "acme.com",        // required
  "first_name": "John",        // optional
  "last_name": "Doe"           // optional
}

Response

{
  "email": "john.doe@acme.com",
  "confidence": 98,
  "sources": ["linkedin", "company_website"]
}

Credits: 1 per successful find.

Email Verifier

Verify the deliverability of an email address.

Request body

{ "email": "john.doe@acme.com" }

Response

{
  "status": "valid",        // "valid", "risky", "invalid"
  "confidence": 98,
  "mx_record": true,
  "smtp_check": "success",
  "disposable": false,
  "role_based": false
}

Credits: 1 per verification.

Domain Search

Retrieve all known email addresses and contacts for a domain.

Request body

{ "domain": "acme.com" }

Response

{
  "domain": "acme.com",
  "contacts": [
    { "email": "john@acme.com", "full_name": "John Doe" },
    { "email": "jane@acme.com", "full_name": "Jane Smith" }
  ],
  "total": 42
}

Credits: 5 per search.

Discover

Perform advanced lead discovery using ICP filters (role, industry, location, etc.).

Request body

{
  "query": "Head of Growth at Series B SaaS",
  "limit": 100,
  "page": 1
}

Response

{
  "leads": [
    { "name": "Alice Johnson", "email": "alice@saas.co", "company": "SaaS.co" },
    ...
  ],
  "total": 1450,
  "page": 1,
  "next_page": 2
}

Credits: 5 per page of 100 results.

Sequences

Create, manage, and launch email sequences.

See the full Sequences API documentation in the Sequences guide.

Sender Accounts

Manage Gmail, Microsoft, and SMTP sender accounts.

Refer to the Sender Accounts API for full details.

Errors

The API uses standard HTTP status codes. Error responses include aerror object with a message and optional code.

{
  "error": {
    "code": "invalid_parameter",
    "message": "Domain is required."
  }
}

Rate Limits

To ensure stability, each API key is subject to rate limits. The default limits are:

• Standard tier: 100 requests per minute
• Scale tier: 500 requests per minute

Rate limit headers are returned in all responses:X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Webhooks

Receive real-time event notifications for email opens, clicks, replies, bounces, and unsubscribes. Configure webhook URLs in the dashboard.

All webhook payloads are signed with a secret key to verify authenticity.

{
  "event": "email.opened",
  "timestamp": "2026-07-13T10:00:00Z",
  "data": {
    "sequence_id": "seq_123",
    "recipient": "john@acme.com",
    "campaign_id": "cam_456"
  }
}

See the Webhooks guide for more details.

SDKs & Clients

Official libraries make integration easier:

• JavaScript / TypeScript – github.com/askoptimus
• Python – github.com/askoptimus/askoptimus-python
• MCP Server – connect via askoptimus.ai/skill.md

Email Verifier Agent (pay per call, no API key)

The Email Verifier is also an ERC-8004 agent that other AI agents hire per call. They pay in USDC over x402 on Monad, so they need no account and no API key. Agents can follow the skill file step by step: askoptimus.ai/agents/email-verifier/skill.md.

GET https://api.askoptimus.ai/agents says which networks are available right now.

Endpoints

Base URL https://api.askoptimus.ai; {network} is mainnet or testnet.

How a paid call works

1. Call the skill. The first answer is 402 Payment Required, with the price in the PAYMENT-REQUIRED header.
2. Sign an EIP-3009 authorization for exactly that amount, USDC asset and payee, and retry with the PAYMENT-SIGNATURE header. Any x402 v2 client does this for you.
3. The payment settles only once the result is ready. Refusals, results that come back unknown, and time-outs are not charged.
4. The response holds the result, the payment, salted commitments to your request and the result, a receipt signed by the agent (when you send clientAgentId), and a ready-made review.

Request body

{ "email": "jane@example.com", "clientAgentId": "<your ERC-8004 agent id>" }
// clientAgentId: required on testnet, optional on mainnet

Response (abridged; top-level JSON, no data wrapper)

{
  "result": {
    "email": "jane@example.com",
    "status": "deliverable",     // deliverable, undeliverable, risky, unknown
    "subStatus": null,           // catch_all, disposable, role_based, no_mx_records…
    "score": 96,                 // 0-100
    "isCatchAll": false,
    "isDisposable": false,
    "isRoleBased": false,
    "isFreeProvider": false
  },
  "charged": true,
  "payment": { "network": "eip155:143", "transaction": "0x…", "amount": "10000" },
  "commitment": { "salt": "0x…", "requestHash": "0x…", "resultHash": "0x…" },
  "receipt": { "level": 1, "receiptHash": "0x…", "providerSignature": "0x…" },
  "review": { "agentId": "10389", "feedbackFile": { "…": "…" } }
}

Errors and limits

Errors are { "error": "<message>", "code": "<code>" } and are never charged. The ones to handle: testnet_limit_reached (403, the trial is used up), client_agent_required and payer_not_client_agent (422), rate_limited and payer_daily_cap (429), and job_timeout (504, retry in a minute). Requests are limited to 60 per minute per IP. The skill file lists every code, how to co-sign the receipt on MoltForest, and the contract addresses. A guide for humans is at askoptimus.ai/agents/email-verifier.