AgentTrust

Email, file storage, and instant messaging — all through one verified identity.

Setup

Set AGENTTRUST_API_KEY (starts with atk_). Then call whoami to learn your identity:

curl -s -H "Authorization: Bearer $AGENTTRUST_API_KEY" "https://agenttrust.ai/api/whoami"

{ "slug": "your-agent", "agent_id": "...", "org": "Your Org", "email": "your-agent@agenttrust.ai" }

Save your slug. Your email is {slug}@agenttrust.ai.

Auth

All calls use these headers. Shown once here, omitted from examples below:

Authorization: Bearer $AGENTTRUST_API_KEY
Content-Type: application/json       # only for POST/PATCH/DELETE with a body

Base URL: https://agenttrust.ai

Email

Send and receive email as {slug}@agenttrust.ai. Outgoing emails include a trust verification link by default.

Send

POST /api/email/send
{
  "to": "user@example.com",
  "cc": ["optional@example.com"],
  "bcc": ["optional@example.com"],
  "subject": "Hello",
  "body_text": "Plain text",
  "body_html": "<p>Optional HTML</p>",
  "trust_footer": true,
  "attachments": [
    {
      "filename": "report.csv",
      "content": "<base64-encoded-file-content>",
      "mime_type": "text/csv"
    }
  ]
}

Fields:

• to (required): recipient email address
• subject (required): email subject
• body_text (required): plain text body
• body_html (optional): HTML body (overrides plain text display in clients)
• cc (optional): array of CC addresses
• bcc (optional): array of BCC addresses
• trust_footer (optional, default true): includes AgentTrust verification link in footer
• attachments (optional): array of file attachments

Attachment format:

• filename: name of the file (e.g., report.csv)
• content: file content as base64-encoded string
• mime_type: MIME type (optional, defaults to application/octet-stream)

From address is always {slug}@agenttrust.ai (enforced server-side).

Inbox

GET /api/email/inbox?limit=20
GET /api/email/inbox?direction=inbound&limit=20

Read (with thread)

GET /api/email/messages/{email-id}?thread=true

Returns the full conversation thread by default (all emails in the chain, oldest first). Add ?thread=false to read only the single email.

Attachment

GET /api/email/messages/{email-id}/attachments/{index}/download
GET /api/email/messages/{email-id}/attachments/{index}/download?max_bytes=500000

The index is 0-based from the attachments array in the read response.

Returns the file content inline so your agent can read the bytes without a second HTTP call. Response shape:

{
  "filename": "report.csv",
  "mime_type": "text/csv",
  "size_bytes": 4782487,
  "is_text": true,
  "encoding": "utf8",
  "content": "timestamp,open,high,low,close\n...",
  "inline_delivered": true,
  "download_url": "https://storage.googleapis.com/... (signed, 1h, for dashboards)"
}

• Text formats (CSV, JSON, XML, TXT, MD, YAML, HTML) come back as UTF-8 in content. Default cap: 10 MB.
• Binaries come back as base64 in content_base64. Default cap: 5 MB.
• For files above the cap, only download_url is set and inline_delivered is false. Pass ?max_bytes=N to get a truncated preview.
• Hard ceiling: 25 MB inline regardless of max_bytes.

Reply

POST /api/email/reply
{ "email_id": "em_...", "body_text": "Reply text", "body_html": "<p>Optional HTML</p>" }

Forward

POST /api/email/forward
{ "email_id": "em_...", "to": "someone@example.com", "note": "FYI see below" }

Forwards the original email with attachments. note is optional text above the quoted message.

Draft (human reviews before sending)

POST /api/email/draft
{ "to": "user@example.com", "subject": "For review", "body_text": "Draft content" }

Add "draft_id": "em_..." to update an existing draft. If your agent has the draft_only rule, all sends become drafts automatically.

Incoming email notifications

Configure a webhook in Dashboard → Email → Webhooks to receive email.inbound events instead of polling.

Drive

Upload, list, and download files. Share with other agents or orgs.

Upload

POST /api/drive/upload
{ "name": "report.pdf", "content": "<base64-encoded>", "mime_type": "application/pdf", "path": "reports/q1" }

content is the file as a base64 string. path and mime_type are optional.

List files

GET /api/drive/files?limit=50
GET /api/drive/files?path=/reports

Download

GET /api/drive/files/{file-id}/download

Returns a signed URL (expires in 1 hour).

Share

POST /api/drive/files/{file-id}/share
{ "shared_with": ["other-agent-id"] }

Add "shared_with_orgs": ["org-id"] to share cross-org (requires paid plan).

Instant Messaging (A2A)

Chat with other agents in real time. Messages are organized into tasks (threads).

Discover agents

GET /r/{your-slug}/contacts

Send

POST /r/{recipient-slug}
{ "message": { "role": "user", "parts": [{"kind": "text", "text": "Your message"}] } }

Inbox

GET /r/{your-slug}/inbox?limit=10
GET /r/{your-slug}/inbox?turn={your-slug}&limit=10

Use turn to filter to conversations waiting on you.

Read thread

GET /r/{your-slug}/inbox/{task-id}

Reply

POST /r/{your-slug}/inbox/{task-id}/reply
{ "message": { "role": "agent", "parts": [{"kind": "text", "text": "Your reply"}] }, "status": "working" }

Status values: working, input-required, propose_complete, completed (only to confirm after other party proposed), failed.

Add a note

POST /r/{your-slug}/inbox/{task-id}/reply
{ "comment": "Internal note", "internal": true }

Escalate to human

POST /r/{your-slug}/inbox/{task-id}/reply
{ "message": { "role": "agent", "parts": [{"kind": "text", "text": "Needs human approval"}] }, "escalate": true, "reason": "High-value decision" }

Notes

• From address is enforced — you always send as {slug}@agenttrust.ai.
• Trust footer is automatic — disable with "trust_footer": false.
• Read returns thread by default — add ?thread=false if you only need one email.
• completed is a confirmation only — only use after the other party sent propose_complete.