Agent email API quickstart: create an inbox, send, and reply

Before you start

Access is invite-only. An operator provisions your account and supplies its initial account key. There is no public self-service signup or published SDK package yet. The interactive API reference and OpenAPI specification are public.

The examples below use cURL and placeholders. Replace the keys and UUIDs with your own values. Keep account keys in your server environment, never in a public client or prompt shared with an agent.

export SCARGO_BASE_URL='https://mail.scargo.ai'
export SCARGO_ACCOUNT_KEY='YOUR_ACCOUNT_KEY'

1. Create an agent mailbox

Use the account key to request a mailbox. The optional local_part must be available and contain 3–48 lowercase letters, digits, or internal hyphens. Omitting it requests a generated local part.

curl --fail-with-body "$SCARGO_BASE_URL/v1/mailboxes" \
  -H "Authorization: Bearer $SCARGO_ACCOUNT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Procurement agent","local_part":"procurement-demo"}'

A successful response is 201 with mailbox.id, mailbox.address, and api_key.secret. Save the returned agent secret securely: it is shown only when issued. Mailbox creation is not idempotent; if a response is lost, list your mailboxes before retrying with the same address.

export SCARGO_MAILBOX_ID='RETURNED_MAILBOX_UUID'
export SCARGO_AGENT_KEY='RETURNED_AGENT_KEY'

2. Verify the agent’s permissions

curl --fail-with-body "$SCARGO_BASE_URL/v1/me" \
  -H "Authorization: Bearer $SCARGO_AGENT_KEY"

The response includes the key’s role, mailbox_id, scopes, and mail_enabled. A mailbox key can operate only within its assigned mailbox and scopes. Account keys can create or revoke keys and pause mailboxes; do not hand account keys to an agent.

To issue a read-only key for an existing mailbox, call POST /v1/keys with your account key and a body containing name, mailbox_id, and "scopes":["read"]. The console also exposes key management.

3. Send an email when delivery is enabled

First persist a unique idempotency key for this business action in your application. Reuse that same key and identical payload when retrying a send whose response was lost. Generate a new key for a different message.

export SCARGO_SEND_KEY='YOUR_PERSISTED_ACTION_ID'
curl --fail-with-body "$SCARGO_BASE_URL/v1/mailboxes/$SCARGO_MAILBOX_ID/messages" \
  -H "Authorization: Bearer $SCARGO_AGENT_KEY" \
  -H "Idempotency-Key: $SCARGO_SEND_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"to":["recipient@example.com"],"subject":"Quote request","text":"Please confirm availability for the items in our request."}'

Use an authorized test recipient in place of the example address. The sender comes from the scoped mailbox; callers cannot supply an arbitrary From address. The current send schema supports text, optional HTML, and up to 10 recipients. It does not accept outbound attachments.

202 means durably queued, not delivered. Inspect the message and subsequent events for outcomes. Do not tell a user the email arrived solely because the send endpoint accepted it.

4. Receive messages through durable event polling

curl --fail-with-body "$SCARGO_BASE_URL/v1/events?after=0&limit=50" \
  -H "Authorization: Bearer $SCARGO_AGENT_KEY"

curl --fail-with-body "$SCARGO_BASE_URL/v1/mailboxes/$SCARGO_MAILBOX_ID/messages?limit=50" \
  -H "Authorization: Bearer $SCARGO_AGENT_KEY"

The events response contains data and next_cursor. Process each event idempotently and persist the cursor after the corresponding application work commits. Use it as after on the next request. Continue through full pages, then poll with a delay and back off on errors. Crashes before saving a cursor can replay events.

The message list returns next_cursor for older messages; pass that cursor as the URL-encoded before parameter. Fetch a single message with GET /v1/mailboxes/{mailboxId}/messages/{messageId}.

Provider webhooks feed Scargo’s ingestion pipeline. The current customer API uses polling; it does not let you register a push webhook endpoint. Your application is responsible for scheduling the agent and maintaining conversation or task state.

5. Reply in the conversation

Set the ID of a received message, persist a new idempotency key for the reply, and submit the approved response.

export SCARGO_MESSAGE_ID='RECEIVED_MESSAGE_UUID'
export SCARGO_REPLY_KEY='YOUR_PERSISTED_REPLY_ACTION_ID'
curl --fail-with-body "$SCARGO_BASE_URL/v1/mailboxes/$SCARGO_MAILBOX_ID/messages/$SCARGO_MESSAGE_ID/reply" \
  -H "Authorization: Bearer $SCARGO_AGENT_KEY" \
  -H "Idempotency-Key: $SCARGO_REPLY_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"text":"Thank you. Could you confirm the delivery date?"}'

Scargo derives the reply recipient and email threading headers from the original message. The reply is queued asynchronously under the same delivery rules as a new send.

Handle errors and limits explicitly

Current deployment defaults are 20 mailboxes per account, 100 outbound recipients per UTC day per account, a shared global daily cap of 100 recipients, and 120 requests per key per minute. Available sending capacity is bounded by both account and global quotas. See pricing and availability for the current beta and proposed paid plans.

For a full request schema, use the OpenAPI document. For workflow design, read why agents need email.