Trusted Senders

AI agent inboxes are 100% owned by agents. When an inbound email contains instructions, the agent needs to know if it should act on them. Trusted Senders lets you configure an allowlist of email addresses per agent.

How It Works

Every email response (REST API, MCP, webhooks) includes is_trusted_sender (boolean) and trusted_sender_name (string or null) fields. The name lets your agent address the sender personally in replies.
The field is computed at retrieval time from the trusted senders list — when you add or remove a sender, all past and future emails reflect the change immediately.
The agent owner's email is automatically added as the default trusted sender when an agent is created. It cannot be removed.
Trusted sender matching is case-insensitive.

REST API

Manage trusted senders via HTTP endpoints.

List trusted senders

GET

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.xobni.ai/api/v1/trusted-senders?agent_id=<agent-uuid>"

Add a trusted sender

POST

curl -X POST "https://api.xobni.ai/api/v1/trusted-senders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent-uuid>",
    "email_address": "boss@company.com",
    "name": "My Boss"
  }'

Remove a trusted sender

DELETE

curl -X DELETE "https://api.xobni.ai/api/v1/trusted-senders/<sender-uuid>?agent_id=<agent-uuid>" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns 400 if you try to remove the default trusted sender.

MCP Tools

Three MCP tools are available for managing trusted senders programmatically.

list_trusted_senders()

Returns all trusted senders for the current agent.

add_trusted_sender(email_address, name?)

Adds an email address to the trusted senders list.

remove_trusted_sender(sender_id)

Removes a trusted sender by ID. Cannot remove the default.

Email Response Example

The is_trusted_sender field appears in all email responses across REST, MCP, and webhooks.

Email response (abbreviated)

{
  "id": "<email-uuid>",
  "from_address": "boss@company.com",
  "is_trusted_sender": true,
  "trusted_sender_name": "My Boss",
  "subject": "Please make a dinner reservation",
  "status": "received",
  ...
}

Usage Pattern

Agent logic (pseudocode)

email = read_email(email_id)

if email["is_trusted_sender"]:
    # Safe to execute instructions from this sender
    name = email["trusted_sender_name"] or email["from_address"]
    execute_instructions(email["body_text"])
    send_email(
        to=[email["from_address"]],
        body_text=f"Hi {name}, I've completed your request."
    )
else:
    # Unknown sender — reply asking them to verify,
    # or forward to human for review
    send_email(
        to=[email["from_address"]],
        body_text="I can only accept instructions from authorized senders."
    )

Claude Skill Setup