Skip to main content
POST
/
v1
/
tools
/
email
/
send
curl -X POST https://win.oneshotagent.com/v1/tools/email/send \
  -H "Content-Type: application/json" \
  -H "X-Quote-ID: quote_abc123" \
  -H "X-Payment-Proof: <your_x402_signature>" \
  -d '{
    "from_address": "[email protected]",
    "from_name": "OneShot Team",
    "to_address": "[email protected]",
    "subject": "Hello from OneShot",
    "body": "This is a test email"
  }'

{
  "request_id": "req_xyz789",
  "status": "processing",
  "message": "Email job queued successfully"
}

​
Authentication

Requires x402 payment proof in the X-Payment-Proof header.

​
Headers

​
X-Quote-ID
string
required
Quote ID from the /email/quote endpoint. Must match an unused quote owned by the same wallet.
​
X-Payment-Proof
string
required
x402 EIP-712 signature authorising the quoted total_cost.

​
Request Body

​
from_address
string
Sender email address.Required if the matching quote did NOT come from rotation (you passed from_address when calling /email/quote).Optional if rotation picked the address at quote time — the server replays the locked_from_address from the quote. You can pass the same value as a sanity check, but a different value returns 400 from_address_mismatch (the agent paid for slot A and can’t send from slot B).
​
from_name
string
Display name for the sender. Rendered as From: From Name <from_address> — e.g. Jane Doe <[email protected]>. Max 100 characters; may not contain newlines or angle brackets.
​
to_address
string | string[]
required
Recipient email address(es)
​
subject
string
required
Email subject line
​
body
string
required
Email body content (plain text)
​
attachments
array
Array of attachment objects with filename, content_type, and content (base64)

​
Response

​
request_id
string
Job ID for tracking the email send status
​
status
string
Job status: pending, processing, completed, or failed
​
message
string
Status message
curl -X POST https://win.oneshotagent.com/v1/tools/email/send \
  -H "Content-Type: application/json" \
  -H "X-Quote-ID: quote_abc123" \
  -H "X-Payment-Proof: <your_x402_signature>" \
  -d '{
    "from_address": "[email protected]",
    "from_name": "OneShot Team",
    "to_address": "[email protected]",
    "subject": "Hello from OneShot",
    "body": "This is a test email"
  }'

{
  "request_id": "req_xyz789",
  "status": "processing",
  "message": "Email job queued successfully"
}

​
Bulk Sending

To send the same email content to multiple recipients, pass an array of email addresses in the to_address field. Each recipient will receive an individual email (not CC/BCC). 
curl -X POST https://win.oneshotagent.com/v1/tools/email/send \
  -H "Content-Type: application/json" \
  -H "X-Quote-ID: quote_bulk_123" \
  -H "X-Payment-Proof: <your_x402_signature>" \
  -d '{
    "from_address": "[email protected]",
    "to_address": ["[email protected]", "[email protected]"],
    "subject": "Hello Team",
    "body": "Weekly update..."
  }'

​
Domain Provisioning

If the domain is new, OneShot will automatically:
  1. Register the domain
  2. Configure DNS records
  3. Set up email sending infrastructure
  4. Verify domain ownership
This process typically takes 2-5 minutes. The email will be sent once provisioning completes.

​
Errors

CodeWhen
400 from_address_mismatchfrom_address in the body doesn’t match the address locked into the quote at rotation time. Omit it or pass the locked value.
400 missing_from_addressThe quote has no locked_from_address (you passed an explicit from_address at quote time) and you didn’t pass one on send.
400 quote_already_usedThe quote was already consumed by a prior send.
403 domain_not_ownedThe domain in from_address belongs to a different agent.

​
Notes

  • Quote must be used within 1 hour
  • Domain provisioning is automatic - no additional steps required
  • Job status can be polled using the request_id
  • When rotation picks for you, the from_address is locked into the quote — see /email/quote