Guide
Start simple.
Add control as the inbox takes on more work.
Use this guide to set up an agent inbox, run the everyday features, then layer in workflows, approvals, webhooks, and deeper controls.
Guide map
Start Create the address, add a domain, issue a token, and connect an agent. Run Use labels, files, caps, sender rules, forwarding, activity, and audit. Power Combine workflows, sequences, approvals, alerts, webhooks, and context. Recipes Use the workflow library when you want copyable API calls for a complete use case. API Use the API reference when you need endpoints, payloads, scopes, and schemas. Limits Check plan limits, add-ons, storage, sending, and usage controls.Getting the House in Order.
Your Inbox
Creating an inbox is how you give your agent somewhere to be. Choose an address that reflects the work it does — assistant@yourco.com, ops@yourco.com, or something more specific. You can create more than one.
Each inbox is fully isolated — its own address, its own history, its own credentials. Nothing crosses over to your personal email.
DNS Records
To send and receive from your own domain, you'll need to add five records to your DNS provider. These tell the internet your agent is authorised to send on your domain's behalf, where incoming mail should be delivered, and that you control the domain.
Your exact values are generated when you add the domain in the dashboard. The record types you'll need:
| Type | Name | Purpose |
|---|---|---|
| MX | @ | Routes incoming mail to your agent's inbox |
| TXT | @ | SPF — declares which servers may send on your behalf |
| TXT | gent._domainkey | DKIM — cryptographically signs outgoing mail |
| TXT | _dmarc | DMARC — tells receivers what to do with failing mail |
| TXT | _gent-verify | Ownership — proves you control this domain |
Connecting Your Agent
Once your inbox is live, generate a token and hand it to your agent. That's the connection. Your agent uses the token to read, send, and manage email on your behalf — nothing else required.
The token is passed as a bearer credential in the API header. Your agent framework handles the rest.
The Right Keys to the Right Doors.
Scoped Tokens
Tokens are how you grant your agent access to an inbox. Each token carries a scope — a defined set of permissions that limits exactly what it can do. Give your agent only what it needs.
All read-only operations — email:read, contacts:read, calendar:read, files:read, labels:read, alerts:read, context:read, llm:read, billing:read, workflows:read. Cannot send, reply, or modify anything. Useful for agents that only need to observe.
Compose and send messages only. Cannot read existing threads or access any other resources. The right choice for outbound-only notification agents.
Complete access — all read operations plus send, move, delete, flag messages, manage contacts, calendar, files, labels, alert rules, and workflow rules; apply and remove labels on contacts and calendar events; manage Enrichment config. Use for agents that own a full conversation workflow.
You can also use granular atomic scopes — email:write, contacts:write, calendar:write, and so on — to grant exactly the permissions your agent needs and nothing more. See the API reference for the full scope table.
Creating & Revoking
Create tokens from the dashboard. Each token is shown once — copy it immediately and pass it to your agent. It cannot be retrieved again.
A token's scope is set at creation and cannot be changed. If you need different permissions, create a new token and revoke the old one.
Revoking a token cuts off access immediately. The agent will receive an auth error and stop. Issue a new token to restore access.
Expiration
Tokens can be set to expire automatically — after 30 days, 90 days, 1 year, or on a specific date. When a token expires it behaves exactly like a revoked one.
Short-lived tokens are better practice for agents running sensitive workflows. Rotate regularly — it costs nothing and limits exposure if a token is ever compromised.
Setting the Rules Before You Need Them.
Spend Alerts
Get notified when usage crosses a threshold — before you hit a hard limit. Set alerts at 50%, 80%, and 100% of your cap. Notifications are delivered to a webhook endpoint of your choice.
Usage Caps
Set limits on how much your agent can send or how much mailbox attachment storage an inbox can use. Tenant admins decide whether each limit is enforced as a hard stop or tracked as a flexible billing threshold.
Send caps apply per inbox per period — daily, weekly, or monthly. In hard-limit mode, send attempts are either rejected or held in a queue until the period resets. In flexible mode, sends continue and additional usage is billed.
Mailbox attachment caps set a limit for inbox message and attachment storage. In hard-limit mode, the server blocks new mailbox growth after the limit; it does not delete existing data if the inbox already exceeds the configured limit. In flexible mode, the inbox keeps receiving data while alerts and billing continue.
Sender Rules
Sender rules control who your agent is allowed to communicate with — both inbound (who can send to it) and outbound (who it can send to). The default mode for both directions is open, meaning no restrictions apply.
No restrictions. All inbound messages are accepted; all outbound sends are permitted.
Only addresses or domains on the allowlist are accepted. Everything else is blocked. Use for tightly controlled agents that should only interact with known parties.
All addresses and domains are accepted except those explicitly blocked. Use to filter out known bad actors without restricting general communication.
Patterns are email addresses (user@example.com) or domain wildcards (@example.com). Inbound and outbound rules are configured independently — your agent can be open inbound but restricted outbound, or vice versa.
Forwarding
Forwarding sends copies of incoming messages to another address — a human inbox, a Slack integration, another agent, or any external system. You configure a default forward address and optional rules that forward selectively based on sender, subject, or recipient.
Rules are evaluated in priority order. Each rule specifies a condition_type (all, sender, domain, subject_keyword) and a destination address. Use all for a catch-all rule. Rules can be enabled or disabled individually without deleting them.
Pausing
Pausing a token suspends its API access without revoking it. Your agent's credential remains valid — it just stops working until you resume it. The token can be resumed at any time, restoring full access immediately.
Use pausing when you want to temporarily take the agent offline — to review its recent activity, investigate an issue, or step in and handle something manually — without permanently cutting off access. A paused token returns 401 Unauthorized on any API call, so your agent will stop and wait.
Pausing is different from revoking: a revoked token is gone and cannot be restored. A paused token can be unpaused in one request.
Taking Over
When you pause an agent's token and step in, you need to know exactly where things stand. The handoff context endpoint gives you a snapshot of the inbox at that moment: which tokens are paused, the threads that have been active recently, your agent's last 30 actions, and the contacts it's been in closest contact with over the past 30 days.
Use this context to orient yourself before replying to open threads, making decisions the agent was about to make, or understanding why you paused it in the first place. When you're done, resume the token and the agent picks up where it left off — in the same inbox, with the same history.
Organize on Your Own Terms.
Labels
Labels are the simplest way to bring structure to your agent's inbox. Tag any message, thread, or contact — priority, contract, do-not-respond — and that structure follows the item everywhere: in search, in filters, in policies.
Labels can be created manually or applied automatically by rules. They're primitives — context groups can reference them, but labels themselves are simple and deliberate. You decide what they mean.
Label Scopes
Each label carries permissions that control what your agent can do with it. You set the scope when creating the label — or adjust it at any time.
Your agent can see items with this label and use them for filtering or context. It cannot apply, remove, or modify the label itself. Useful for labels that represent human decisions — approved, escalate.
Your agent can read and apply this label to new items, but cannot remove it once applied. Useful for classification labels where human review should remove them.
Full label access — read, apply, and remove. Useful for operational labels your agent manages entirely: needs-followup, processed.
Auto-label Rules
Rules apply labels automatically when a message arrives. Define a condition — sender domain, subject pattern, recipient address — and the label is applied before your agent ever reads the message.
Rules evaluate in order. The first match wins. You can combine conditions (all must match) or use any-match logic. Rules can be enabled, disabled, or reordered without deleting them.
Policies
Attach behavior to a label and that behavior applies to every item carrying it. Policies let you encode decisions once and have them enforced automatically.
Available policy types:
Agent cannot send from threads bearing this label. Useful for legal-hold or do-not-contact.
Automatically forward labeled items to a specified address — a human reviewer, a Slack integration, another system.
Override the default storage expiration for labeled items — keep them longer or shorter than your inbox default.
Send a webhook notification whenever this label is applied.
Keeping What Matters.
How It Works
Messages and message attachments are stored as inbox data. Files created through the Files API are separate records with owner, tenant, folder, version, viewer, and collaborator metadata. An email attachment is not automatically a shared File unless a workflow or user promotes it into Files.
Each inbox includes message and attachment storage based on your plan: 1 GB on Builder, 3 GB on Startup, and 10 GB on Scale. Files created through the Files API use the workspace Files allocation shown on the pricing page. Your dashboard shows a breakdown by content type so you can see what's taking up space. Custom storage terms belong in Scale agreements.
Expiration Policies
Set rules for how long content is retained before it's automatically deleted. Policies can be configured per inbox and per content type — you might keep message bodies for a year but delete attachments after 90 days.
Available retention periods: 30 days, 90 days, 6 months, 1 year, or indefinitely. Deleted content is unrecoverable — you'll receive a notification 7 days before any content is due to expire.
The View From the Top.
Activity Feed
The operational view — what your agent is doing right now. New messages arriving, sends going out, files attached, events created. It's the dashboard you'd glance at to confirm things are moving. Ordered by time, filterable by inbox or action type.
The feed is live but not archival. It's for awareness, not investigation.
Audit Log
The compliance record. Every action your agent takes is written here immediately and immutably. Entries are retained for the configured retention period — 90 days by default, up to 10 years for team plans. They cannot be modified or manually deleted via the API.
Where the feed tells you what's happening, the audit log tells you what happened — with a timestamp you can rely on. Use it when something needs to be investigated, verified, or disputed. It records that an action occurred, not the full content of what was sent or received.
Usage Dashboard
A summary view of storage consumed, emails sent, active threads, and contacts touched. Updated daily. Useful for understanding cost trends before your invoice arrives and for spotting unusual activity patterns early.
Know Before You Miss It.
Alert Rules
Alert rules let you subscribe to events in your agent's inbox and receive a webhook notification when they fire. Each rule specifies which events to watch, an optional filter to narrow scope, and a delivery endpoint.
Rules are created via the API or dashboard and stay active until disabled or deleted. You can have multiple rules watching the same event with different filters — useful for routing different label types or contacts to different systems.
Time-based events (calendar events and contact anniversaries) support an offset — deliver the webhook minutes, hours, or days before the scheduled time. System events (cap.reached, storage.threshold, auth.failed) use a threshold value to set when they trigger.
Event Types
Alert rules can subscribe to any combination of the following events:
A new message arrives in the inbox.
Your agent successfully sends a message.
A label is applied to a message or contact.
A label is removed from a message or contact.
A calendar event is created. Supports offset to notify ahead of the event start time.
A calendar event is updated. Supports offset.
A calendar event is cancelled. Supports offset.
Matches an anniversary entry whose type equals {type}. Any value is valid — birthday, nameday, or anything you define. Fires annually at 08:00 account timezone. Supports offset to notify days or hours in advance.
Send or spend usage crosses a configured level. Set threshold to a percentage of the configured cap (e.g. 80 fires at 80%).
Consecutive API authentication failures reach a count. Set threshold to the number of failures that trigger the alert.
Message and attachment storage crosses a configured level. Set threshold to a percentage of your storage limit.
contact.{type} events read from the anniversaries field on each contact. The type string on each anniversary entry determines the event name — any value you define is valid. Dates set through the API are recognized.Offset, Threshold & Retry
Time-based rules (calendar events, contact anniversaries) accept an offset to fire the webhook in advance — specify a value and unit (minutes, hours, or days). Omit the offset to fire at the scheduled time.
System rules (cap.reached, storage.threshold, auth.failed) accept a threshold value that sets when the rule fires — percentage of cap or limit for usage events, consecutive failure count for authentication events.
Every alert rule accepts an optional filter to narrow which events trigger it. Filter by label_id to watch a specific label, or by contact_id to watch a specific contact. Without a filter, the rule fires on every matching event across the inbox.
Webhook deliveries are retried on failure. Set the number of attempts (default 3) and the backoff strategy — immediate, fixed, or exponential. After the final attempt, the event is logged as undelivered and can be replayed from the dashboard or via the API.
Each delivery includes a signature header you can use to verify the payload came from gent.mx. The full event payload is included in the request body.
What the System Sees.
Activity Timeline
Where the activity feed shows inbox-level movement and the audit log records administrative changes, the timeline assembles a contact-centered story. It draws on messages, delivery events, ticket updates, calendar activity, and related context for one contact at a time.
Use it before stepping into a thread or making a decision about a customer, stakeholder, or approver. For API clients, query the timeline with a stable contact ID when available, or an email address before the contact is linked.
Relationships
The system tracks how often your agent interacts with each contact, how recently, and in what context. Over time a picture emerges — who appears most in your agent's work, who it's been out of touch with, where attention might be needed.
Relationship data is derived from your agent's actual communication. It updates continuously and requires no manual input.
Context Groups
Your agent's threads, contacts, and activity naturally organize into groups — a project, a client, a recurring task. These groups aren't something you set up. The system finds patterns across the communication and surfaces them.
You'll see a project take shape before you've named it. You can rename groups and merge ones that overlap, but the structure emerges on its own. Context groups can draw on any signal in your inbox — individual messages, events, contacts, and labels you've already applied.
Act Without Being Asked.
Rules
Workflow rules run server-side whenever a trigger fires — a message arrives, a label is applied, a contact is created. Each rule specifies a trigger, optional conditions, and one or more actions to execute. No polling, no browser tab required.
Workflow triggers use names such as message_received, email_received, and label_applied. Conditions narrow which events fire the rule — filter by sender domain, label, or contact field. Actions validate source data against a contract before writing to targets such as labels, folders, replies, files, sequences, or webhooks.
Available actions depend on your plan tier. Builder covers safe, non-outbound actions. Startup and above unlock outbound targets, enrichment, sequence enrollment, and more. See the full action list in the API reference →
Sequences
Sequences are multi-step, timed email cadences your agent runs autonomously. Define a series of steps — each with a delay and either static body copy or a prompt your agent evaluates at send time — and enroll a contact. The sequence advances on schedule and exits automatically when the contact replies.
Sequences can be reusable templates (defined once, enrolled many times) or inline and ad-hoc (defined per contact, per context). Either way, your agent handles timing and execution without intervention.
Active sequences per contact are visible in the contact detail API. See the sequences API reference →
Control Without Friction.
Approval Queues
Mark a token as requiring approval and any outbound action it attempts — sending a message, enrolling a contact, executing an automation — is held before it goes out. A human reviewer sees a pending action queue and can approve or reject each item. Approved actions execute immediately. Rejected ones are discarded and logged.
This lets you run an agent in a supervised mode — it does the work, you do the final check. Useful for agents handling sensitive outreach, compliance-adjacent workflows, or any context where a human in the loop matters.
Token Controls
Beyond pausing and revoking, governance-tier plans give you fine-grained controls over token behaviour. Tokens can be configured with a requires_approval list at creation time, which routes matching actions through the approval queue. To change approval-gated scopes, create a replacement token and revoke the old one.
Full governance (Scale plan or Pro Controls add-on) adds MFA enforcement for all team members and configurable audit retention — extend the default 90-day window up to the maximum your plan allows. Audit entries themselves are always immutable.
See the token API reference → for the full set of governance fields.
Connecting to What You Already Use.
OpenClaw
Connecting to OpenClaw is two steps — one for you, one for the agent.
For you: Create a token with the appropriate scope and add it to your agent's environment:
GENT_API_KEY=your_token_here
OpenClaw's email tool picks it up automatically. The inbox address, display name, and available scopes are all discovered at runtime — nothing else to configure.
For the agent: A SKILL.md is available at gent.mx/SKILL.md — a public integration guide for installing gent.mx in AI coding assistants and agent frameworks. It explains the runtime token, supported API surfaces, scopes, webhooks, and common agent requests.
Other Frameworks
Any agent framework can connect via the REST API using a scoped token as a bearer credential. The full API reference is available in the API docs.
Webhooks
Webhooks are how gent.mx pushes events to your systems in real time. Set up an endpoint and configure alert rules to subscribe to the events that matter — incoming messages, label changes, contact dates, usage thresholds, and more.
See the Alerts section for the full event type list, filter options, and retry behavior. To test webhook flows without touching a production tenant, use the demo server.
Demo Server
The demo server is a public, resettable API environment for onboarding, dashboard previews, and integration tests. It mirrors the main API shape where practical, but uses generated sample data and short-lived state. Use https://demo.gent.mx as the base URL when you want to build or test a client before connecting it to a real tenant.
Demo state is scoped by the X-Gent-Demo-Session header. Browser clients receive this header automatically and send it back on later requests. CLI and server-side clients should create a stable random value and reuse it while testing, so alert rules, webhook deliveries, and sample events stay isolated from other demo users.
| Endpoint | Purpose |
|---|---|
| POST /v1/alerts/ | Create an event notification for the current demo session. |
| POST /v1/alerts/test/ | Send one sample delivery to a configured webhook target. |
| POST /__demo/events/emit | Emit a sample event and deliver it to matching alert rules in the same demo session. |
| POST /__demo/webhooks/{sink_id} | Receive a webhook payload in the built-in demo sink. |
| GET /__demo/webhook-deliveries | Read delivery attempts recorded for the current demo session. |
A fixed X-Gent-Demo-Session keeps your rules and deliveries separate from other users. Without one, the server issues a temporary session ID.
External webhook deliveries are rate-limited per session, source IP, target URL, and globally. Repeated failures pause the target for the session window.
Built-in /__demo/webhooks/{sink_id} sinks are intended for quick tests and do not count against external delivery limits.
Production uses real authentication, tenant state, durable audit records, and real webhook delivery behavior. Demo-only /__demo/ endpoints are not part of the production API.
A minimal webhook test uses one session value across all calls: create an alert with a target such as https://demo.gent.mx/__demo/webhooks/my-test, emit message.received, then read /__demo/webhook-deliveries?sink_id=my-test.
No Surprises.
Usage & Costs
Self-serve plans are priced per inbox, with volume and custom commercial terms on higher tiers. Additional sending and mailbox attachment storage can be billed when tenant admins enable flexible caps; AI usage is billed at provider token cost plus 5%.
Plan send inclusions cover normal inbox activity — agent replies, sequences, distribution list sends, and small campaigns to your contact groups. Additional sending is priced to discourage large-scale broadcast use, but the more important consideration is fit: intelligence features like enrichment, relationship tracking, and context groups compound with contact frequency. The system gets smarter the more your agent interacts with the same people. A cold list of strangers doesn't benefit from any of that.
No minimum. No contract. See the pricing page for the full breakdown including capability tiers.
Invoices
Invoices are generated on the 1st of each month and charged to your payment method on file. Your first invoice covers only the days remaining in your billing cycle from the date you created your inbox — prorated to the day.
Your current cycle's accrued cost is always visible in the dashboard — so there are no surprises when the invoice arrives. Download past invoices at any time.
Data Export & Closure
Before closing an inbox, all stored messages, contacts, and files can be exported from the dashboard — MBOX for email, vCard for contacts, ZIP for files. Exports are available at any time, not only at closure.
Closing an inbox does not delete data immediately. Content is retained for 30 days to allow export before permanent removal. Inboxes can also be deactivated without deletion — your agent loses access but the data remains intact until you choose to restore or remove it.