Email

Overview

Use the Email API when an agent needs to send a notification, confirmation, or batch of personalized messages. Messages go through your own SMTP mail server, connected to the workspace as an email-smtp connector. Robots Center checks the agent's permissions and approval policies before sending and records a trace you can inspect afterward.

Authorization is part of every send

The endpoint evaluates grants and approval policies using the recipient payload plus optional top-level environment, amount, risk_score, and contains_phi. A separate auth check is informative only and does not reserve a later decision.

Idempotency protects the SMTP side effect

Supply one Idempotency-Key for each logical single or bulk send. Conflict detection hashes the connector, action, and validated SMTP payload; changing one of those under the same key conflicts. Policy-only environment, amount, risk_score, and contains_phi inputs are evaluated again on every request but are not part of that hash, so keep them stable for a predictable logical retry.

Approval is not queued by email routes

A requires_approval result is returned as HTTP 400 problem JSON, just like a policy denial; the email is not sent and no approval workflow is automatically resumed. Use the Gateway tool-action approval flow when an operator-approved execution is required.

How it works

1. Prepare connector access

   Have an operator create the SMTP connector and grant the service agent send_email and, if needed, send_bulk_email. Confirm the connector is active and the relay is allowed by outbound network policy.

2. Optionally preflight policy

   POST /api/v1/auth_checks with the same connector, action name, payload characteristics, and policy fields. Treat the result as a point-in-time explanation, not proof the subsequent send must succeed.

3. Send once and retain the receipt

   Use a stable idempotency key, then record the returned SMTP message_id, runtime trace_id, connector identity, and duration. A bulk response reports totals and can succeed with a nonzero failed count.

Examples

These examples are illustrative. Replace the sample values with your own. Keep credentials in environment variables or a secret manager, never in client-side code.

export AGENTOPS_BASE_URL="https://robotscenter.net"
export AGENT_TOKEN="machine_token_with_gateway_check"

curl --fail-with-body --silent --show-error \
  -X POST \
  -H 'content-type: application/json' \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  --data '{"connector_slug":"email-smtp","action_name":"send_email","payload":{"to":"customer@example.com","subject":"Receipt"},"environment":"production","contains_phi":false}' \
  "$AGENTOPS_BASE_URL/api/v1/auth_checks" | jq .

export AGENTOPS_BASE_URL="https://robotscenter.net"
export AGENT_TOKEN="machine_token_with_email_send"
export EMAIL_IDEMPOTENCY_KEY="receipt-ord-example-1042-v1"

curl --fail-with-body --silent --show-error \
  -X POST \
  -H 'content-type: application/json' \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Idempotency-Key: $EMAIL_IDEMPOTENCY_KEY" \
  --data '{"connector_slug":"email-smtp","to":"customer@example.com","subject":"Your receipt","body":"Thank you for order ord-example-1042.","environment":"production","contains_phi":false}' \
  "$AGENTOPS_BASE_URL/api/v1/email/send" | jq .

export AGENTOPS_BASE_URL="https://robotscenter.net"
export AGENT_TOKEN="machine_token_with_email_send"
export EMAIL_IDEMPOTENCY_KEY="daily-digest-2026-09-16"

curl --fail-with-body --silent --show-error \
  -X POST \
  -H 'content-type: application/json' \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Idempotency-Key: $EMAIL_IDEMPOTENCY_KEY" \
  --data '{"connector_slug":"email-smtp","recipients":[{"to":"one@example.com","subject":"Daily digest","body":"One new item."},{"to":"two@example.com","subject":"Daily digest","body":"Two new items."}],"environment":"production"}' \
  "$AGENTOPS_BASE_URL/api/v1/email/bulk" | jq .

Troubleshooting

The send returns denied or requires_approval

Both are HTTP 400 problem responses on the email routes and no SMTP action runs. Check the connector grant and policy inputs; use the Gateway approval flow instead if execution truly must wait for a human decision.

The connector is 404 or the wrong type

Connector lookups are workspace-scoped and return only active, non-archived rows. Email endpoints additionally require slug email-smtp; another connector type produces invalid_connector_type.

An idempotency retry conflicts

The key was reused with a changed connector, action, or validated SMTP payload, or a prior attempt is still in progress or failed indeterminately. Policy-only inputs do not produce this hash conflict, but they are re-authorized. Do not generate a new key merely to force a second SMTP side effect.

An attachment is rejected

Send inline base64 only: at most 10 files, 2 MiB decoded per file, and 5 MiB decoded in total. URL and filesystem-path attachments are intentionally refused.

Endpoint reference

Ready to integrate? Open an endpoint for its required permissions, request fields, response format, and status codes. The examples above explain the workflow; these details define each individual request.

{
  "status": "sent",
  "action": "send_email",
  "message_id": "<abc123@smtp.delivered>",
  "trace_id": "a1b2c3d4e5f6",
  "duration_ms": 245,
  "connector_id": "550e8400-e29b-41d4-a716-446655440000",
  "connector_slug": "email-smtp"
}

{
  "status": "completed",
  "total": 3,
  "failed": 0,
  "sent": 3,
  "action": "send_bulk_email",
  "trace_id": "a1b2c3d4e5f6",
  "duration_ms": 812,
  "connector_id": "550e8400-e29b-41d4-a716-446655440000",
  "connector_slug": "email-smtp"
}