Agent inbox setup
Create an agent inbox.
Give an agent its own address, domain, token, and operating boundary before it starts handling mail.
Token first
Make sure the agent has these scopes.
Create a new token or update the agent's current token before trying the calls below.
Required token scopes
email:read
email:send
email:write
Outcome
What this gives you.
An agent can receive and send mail from a real inbox without borrowing a person's account.
Use when
The operational shape.
- You are launching a new agent, assistant, or workflow that needs a stable email address.
- You need one token per agent or integration, with scopes that match the job.
- You want custom-domain mail with ownership, storage, and audit separated from human inboxes.
API sequence
The calls to make.
01
Verify the sending domain
POST/v1/domains/
Use a signed-in owner or admin session to create or reuse a verified custom domain for agent mail.
Default example
Omit domain_use for the default existing-domain path. Gent defaults DMARC to quarantine unless you explicitly choose a reserved sending subdomain or DMARC policy.
{
"domain": "mail.example.com"
}
Reserved subdomain
Use this when the subdomain is reserved for Gent/agent mail and you want the stricter default DMARC posture.
{
"domain": "agents.example.com",
"domain_use": "dedicated_subdomain"
}
02
Create the inbox
POST/v1/inboxes/
Use session auth to name the inbox for the agent, workflow, client, or queue it represents.
Default example
Use this as the default shape for this step.
{
"address": "agent@mail.example.com"
}
03
Issue a scoped token
POST/v1/tokens/
Create the agent token with only the message, file, contact, or workflow scopes it needs.
Default example
Use this for an agent that can read and write messages but only access the extra surfaces it needs.
{
"inbox_id": "inb_123",
"label": "ops-agent-production",
"scopes": ["email:read", "email:send", "email:write", "files:read"]
}
Supervised send token
Use this when the agent should read context and draft replies, but outbound email must be approved first.
{
"inbox_id": "inb_123",
"label": "supervised-reply-agent",
"scopes": ["email:read", "email:send"],
"requires_approval": ["email:send"]
}
Read-only observer token
Use this for classification, monitoring, reporting, or retrieval agents that should never modify inbox state.
{
"inbox_id": "inb_123",
"label": "triage-observer",
"scopes": ["email:read", "contacts:read", "files:read"]
}
04
Set storage and safety limits
PUT/v1/billing/caps/mailbox/
Use an admin session for cap changes before production traffic starts.
Default example
Use enforced caps when you want the inbox to stop future growth before it crosses the configured storage limit.
{
"inbox_id": "inb_123",
"limit_gb": 10,
"mode": "enforce",
"alert_thresholds": [80, 95]
}
Flexible caps
Use this when you want usage to continue while alerts and billing reflect growth beyond the allocation.
{
"inbox_id": "inb_123",
"limit_gb": 10,
"mode": "allow_and_bill",
"alert_thresholds": [80, 95]
}
Controls
Review points.
- Store the token immediately; the raw value is only shown at creation or rotation.
- Use one token per agent or integration so revocation does not disrupt unrelated work.
Related