Get Email Quote

curl -X POST https://win.oneshotagent.com/v1/tools/email/quote \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{
    "from_address": "[email protected]",
    "to_address": "[email protected]",
    "subject": "Hello",
    "body": "Test email"
  }'

curl -X POST https://win.oneshotagent.com/v1/tools/email/quote \
  -H "X-Agent-ID: <wallet>" -H "Content-Type: application/json" \
  -d '{
    "to_address": ["[email protected]"],
    "subject": "hi", "body": "..."
  }'
# →  { "from_address": "[email protected]", "rotation": true, "quote_id": "...", ... }

const response = await fetch(
  "https://win.oneshotagent.com/v1/tools/email/quote",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "payment-signature": paymentProof,
    },
    body: JSON.stringify({
      from_address: "[email protected]",
      to_address: "[email protected]",
      subject: "Hello",
      body: "Test email",
    }),
  },
);

{
  "domain": "yourdomain.com",
  "is_new": true,
  "available": true,
  "registration_fee": 10.0,
  "service_fee": 0.01,
  "mailbox_provisioning_fee": 0,
  "total_cost": 10.01,
  "currency": "USD",
  "quote_id": "quote_abc123",
  "status": "unprovisioned"
}

POST

tools

quote

curl -X POST https://win.oneshotagent.com/v1/tools/email/quote \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{
    "from_address": "[email protected]",
    "to_address": "[email protected]",
    "subject": "Hello",
    "body": "Test email"
  }'

curl -X POST https://win.oneshotagent.com/v1/tools/email/quote \
  -H "X-Agent-ID: <wallet>" -H "Content-Type: application/json" \
  -d '{
    "to_address": ["[email protected]"],
    "subject": "hi", "body": "..."
  }'
# →  { "from_address": "[email protected]", "rotation": true, "quote_id": "...", ... }

const response = await fetch(
  "https://win.oneshotagent.com/v1/tools/email/quote",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "payment-signature": paymentProof,
    },
    body: JSON.stringify({
      from_address: "[email protected]",
      to_address: "[email protected]",
      subject: "Hello",
      body: "Test email",
    }),
  },
);

{
  "domain": "yourdomain.com",
  "is_new": true,
  "available": true,
  "registration_fee": 10.0,
  "service_fee": 0.01,
  "mailbox_provisioning_fee": 0,
  "total_cost": 10.01,
  "currency": "USD",
  "quote_id": "quote_abc123",
  "status": "unprovisioned"
}

Prices an email: total_cost covers domain registration, sending and any one-time mailbox fee. It locks the sender address and mailbox mode for /email/send and is valid for 1 hour.

Authentication

X-Agent-ID header with your wallet address.

Request body

string

Omit it and rotation picks a domain and locks the address into the quote; a different address on /email/send returns 400 from_address_mismatch. Pass it to pin a mailbox you own: only ownership is checked; warmup score and daily_send_limit become a warning. Reputation and limits are per domain, shared by all its mailboxes.

string | string[]

required

One or more recipients; service_fee scales with the count.

string

required

Subject

string

required

Plain text

string

relay (header-only send, fee 0; the default for a domain set up for the first time) or mailbox (a mailbox per address; adds the one-time mailbox_provisioning_fee). Locked into the quote; omit it on /email/send. Applies only to a domain not yet provisioned; a provisioned domain keeps its own mode.

Response

string

Domain of from_address

boolean

New domain needing registration

boolean

Available to register

number

Registration cost (USD); 0 for a domain you own.

number

Sending cost (USD)

number

One-time fee (USD) for the first send from an address not yet active on /email/domains (default_from included; provisioning and failed addresses pay it again until active). Always 0 on a relay domain. A send whose quote lacked this fee returns 402 mailbox_provisioning_required: re-quote with the exact from_address.

number

Registration + service + mailbox provisioning fees

string

Quote ID for the send request

string

verified, provisioning, unprovisioned, or blocked

string

When you omitted it: the address rotation picked, locked into the quote.

boolean

true when rotation picked the address.

string

pinned_domain_warming (pinned domain still warming) or pinned_over_limit (over today’s daily_send_limit). Advisory; the send proceeds.

string

no_sending_domain (HTTP 400): no from_address and no eligible domain; no shared fallback sender exists. reason is empty (no domain owned) or exhausted (all warming or over cap). Register one with from_domain, or pin one you own.

curl -X POST https://win.oneshotagent.com/v1/tools/email/quote \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{
    "from_address": "[email protected]",
    "to_address": "[email protected]",
    "subject": "Hello",
    "body": "Test email"
  }'

curl -X POST https://win.oneshotagent.com/v1/tools/email/quote \
  -H "X-Agent-ID: <wallet>" -H "Content-Type: application/json" \
  -d '{
    "to_address": ["[email protected]"],
    "subject": "hi", "body": "..."
  }'
# →  { "from_address": "[email protected]", "rotation": true, "quote_id": "...", ... }

const response = await fetch(
  "https://win.oneshotagent.com/v1/tools/email/quote",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "payment-signature": paymentProof,
    },
    body: JSON.stringify({
      from_address: "[email protected]",
      to_address: "[email protected]",
      subject: "Hello",
      body: "Test email",
    }),
  },
);

{
  "domain": "yourdomain.com",
  "is_new": true,
  "available": true,
  "registration_fee": 10.0,
  "service_fee": 0.01,
  "mailbox_provisioning_fee": 0,
  "total_cost": 10.01,
  "currency": "USD",
  "quote_id": "quote_abc123",
  "status": "unprovisioned"
}

Domain rotation

Omit from_address and the server picks your least recently used eligible domain and sends from its default_from. Eligible: you own it, pool_status is active (a warming domain is paused until its score reaches 75), provisioning_status is verified, warmup_score is 60 or higher, or unmeasured, and daily_sent_count plus the recipient count fits under daily_send_limit today (UTC). A rotation quote counts its recipients toward daily_sent_count at quote time; a rejected quote gives them back, an unsent one holds them until the UTC day rolls over. GET /email/domains lists your pool; pause and resume control rotation.

Overview

Compute

Data

Monitoring

Research & Enrich

Messaging

Web & Browser

Build

Commerce

Account & billing

Other

Get Email Quote

Authentication

Request body

Response

Domain rotation

​Authentication

​Request body

​Response

​Domain rotation

Authentication

Request body

Response

Domain rotation