curl -X GET "https://win.oneshotagent.com/v1/tools/inbox?include_body=true&limit=10" \
-H "X-Agent-ID: <your_agent_uuid>"
const response = await fetch(
"https://win.oneshotagent.com/v1/tools/inbox?include_body=true&limit=10",
{
headers: {
"X-Agent-ID": agentUuid,
},
},
);
{
"emails": [
{
"id": "email_123",
"from": "[email protected]",
"subject": "Re: Your inquiry",
"body": "Thanks for reaching out!",
"received_at": "2025-12-28T12:00:00Z",
"thread_id": "thread_abc",
"attachments": [
{
"filename": "document.pdf",
"content_type": "application/pdf",
"size": 102400,
"content": "JVBERi0xLjQK..."
}
]
}
],
"count": 1,
"has_more": false,
"agent_id": "agent_xyz"
}
Email Inbox
List Inbound Emails
Poll for inbound emails with minimal, actionable data
GET
/
v1
/
tools
/
inbox
curl -X GET "https://win.oneshotagent.com/v1/tools/inbox?include_body=true&limit=10" \
-H "X-Agent-ID: <your_agent_uuid>"
const response = await fetch(
"https://win.oneshotagent.com/v1/tools/inbox?include_body=true&limit=10",
{
headers: {
"X-Agent-ID": agentUuid,
},
},
);
{
"emails": [
{
"id": "email_123",
"from": "[email protected]",
"subject": "Re: Your inquiry",
"body": "Thanks for reaching out!",
"received_at": "2025-12-28T12:00:00Z",
"thread_id": "thread_abc",
"attachments": [
{
"filename": "document.pdf",
"content_type": "application/pdf",
"size": 102400,
"content": "JVBERi0xLjQK..."
}
]
}
],
"count": 1,
"has_more": false,
"agent_id": "agent_xyz"
}
Authentication
RequiresX-Agent-ID header with your wallet address.
Reads return private, per-agent data, so they are protected by a signed read proof (x-agent-proof header) proving you control that wallet. The OneShot SDK signs and sends this automatically (TypeScript ≥ 0.25.0, Python ≥ 0.17.0). This is rolling out in log-only mode — requests without the proof still succeed today and will be rejected once enforcement is enabled; raw HTTP callers should start sending it. See Read Proof Authentication.
Query Parameters
string
ISO 8601 timestamp to filter emails received after this time
number
default:"50"
Maximum number of emails to return (max: 100)
boolean
default:"false"
Whether to include email body and attachments
Response
array
Array of inbound email objects
Show Email Object
Show Email Object
string
Unique email identifier
string
Sender email address
string
Email subject
string
ISO 8601 timestamp
string
Thread identifier for conversation tracking
string
Plain text body (only if
include_body=true)string
HTML body (only if
include_body=true)number
Number of emails returned
boolean
Whether there are more emails available
curl -X GET "https://win.oneshotagent.com/v1/tools/inbox?include_body=true&limit=10" \
-H "X-Agent-ID: <your_agent_uuid>"
const response = await fetch(
"https://win.oneshotagent.com/v1/tools/inbox?include_body=true&limit=10",
{
headers: {
"X-Agent-ID": agentUuid,
},
},
);
{
"emails": [
{
"id": "email_123",
"from": "[email protected]",
"subject": "Re: Your inquiry",
"body": "Thanks for reaching out!",
"received_at": "2025-12-28T12:00:00Z",
"thread_id": "thread_abc",
"attachments": [
{
"filename": "document.pdf",
"content_type": "application/pdf",
"size": 102400,
"content": "JVBERi0xLjQK..."
}
]
}
],
"count": 1,
"has_more": false,
"agent_id": "agent_xyz"
}
Notes
- Only essential fields are returned (no verbose headers or metadata)
- Use
sinceparameter for efficient polling - Attachments are base64-encoded for easy processing
- Thread tracking via
thread_idfor conversation context