Workflow library

Email workflows, from common to Gent-only.

Start with familiar inbox automation patterns. Then see the workflows that need Gent's agent inbox, authority, context, approval, and audit model.

Prerequisite

Get to a working agent inbox first.

Every recipe below assumes the agent already has a verified domain, an inbox, and a scoped token. This is the setup sequence that used to live in the API quickstart.

01

Start with a verified domain

POST/v1/domains/

Register the customer-owned domain or subdomain that will hold agent inboxes. If you omit domain_use, Gent treats it as an existing domain and starts DMARC at quarantine.

Default example
Use session auth. Gent returns DNS records for MX, SPF, DKIM, DMARC, and ownership verification.
{
  "domain": "mail.yourco.com"
}
Reserved subdomain example
Use this when the subdomain is reserved for Gent/agent mail and you want the stricter default DMARC posture.
{
  "domain": "agents.yourco.com",
  "domain_use": "dedicated_subdomain"
}
02

Verify DNS

POST/v1/domains/{domain}/verify/

After adding the records at your registrar, verify the domain before creating inboxes.

Optional check
Use the check endpoint when you want record-level status without mutating verification state.
GET /v1/domains/mail.yourco.com/check/
03

Create the agent inbox

POST/v1/inboxes/

Give the agent its own address on the verified domain.

Example payload
Use session auth. Save the returned inbox_id for management calls.
{
  "address": "agent@yourco.com"
}
04

Issue an agent token

POST/v1/tokens/

Create a scoped credential for the agent instead of handing it a user session.

Example payload
Use the narrowest scopes the workflow needs. The raw token is shown once.
{
  "inbox_id": "<inbox_id>",
  "scopes": ["email:read", "email:send"],
  "label": "my-agent"
}
05

Send and read mail

POST/v1/messages/

Use the agent token to send the first message, then list messages to confirm the inbox is live.

Send example
Use agent auth. For replies, pass reply_to_message_id and Gent derives the recipient and subject.
{
  "to": [{ "email": "hello@example.com" }],
  "subject": "Hello from gent.mx",
  "text_body": "Sent via the API."
}
Read example
Use agent auth with email:read.
GET /v1/messages/?limit=5
Inbox setup guide Authentication reference Domain API Inbox API Agent skill file

Recipe files

Install repeatable workflows from TOML.

Use TOML when you want a workflow recipe that can be reviewed, shared, versioned, and installed from the dashboard without writing a long integration runbook first.

Write a recipe as TOML, paste it into the dashboard, validate the normalized API payloads, then install live resources through the same sequence, work-route, and workflow APIs documented in this library.

Tiny recipe example
This example creates one workflow rule from user-provided inbox and webhook inputs.
schema_version = "2026-06-18"
kind = "gent.workflow_recipe"
name = "Route leads to CRM"
description = "Send inbound lead email events to a CRM webhook."
category = "lead_response"

[inputs.inbox_id]
type = "inbox"
required = true
label = "Agent inbox"

[inputs.crm_webhook_url]
type = "url"
required = true
label = "CRM webhook URL"

[[resources.workflow]]
key = "lead_route"
name = "Route leads to CRM"
inbox_id = "{{ inputs.inbox_id }}"
trigger = "email_received"
conditions = [
  { field = "to_address", op = "contains", value = "leads@" }
]
writes = [
  { source = { from = "trigger.email" }, target = { type = "webhook", url = "{{ inputs.crm_webhook_url }}" } }
]
Use TOML recipes TOML reference Workflow API

Common use cases

The workflows people already know they need.

These map ordinary email operations into concrete API calls: inbox setup, routing, triage, approvals, follow-up, files, tasks, and client workspaces.

Agent inbox setup

Create an agent inbox

Give an agent its own address, domain, token, and operating boundary before it starts handling mail.

View recipe

Inbound routing

Route inbound email to a webhook

Receive a message, classify it, and send the event to the service that should own the next step.

View recipe

Inbound triage

Triage inbound email with rules and AI

Classify inbound mail, suggest labels, score priority, prepare safe replies, and surface only the work that needs a person.

View recipe

Human review

Hold agent replies for approval

Let an agent draft or request a send action while a human approves sensitive mail before it leaves.

View recipe

Work routing

Route an email request for sign-off

Send an email-based approval, acknowledgement, or text-response request to several people and record their replies.

View recipe

Outbound follow-up

Run an email follow-up sequence

Enroll a contact or thread into a controlled sequence, stop on reply, and keep the history attached to the inbox.

View recipe

Files and intake

Save email attachments to Files

Promote inbound attachments into structured Files API records with folders, versions, collaborators, and source history.

View recipe

Files and intake

Process an invoice email into a spreadsheet

Capture invoice mail, store the source record, and append extracted invoice fields to a spreadsheet for finance review.

View recipe

Task automation

Turn an email into a task

Convert inbound mail into a tracked action item with labels, status, context, and optional follow-up.

View recipe

Agency operations

Create a client project inbox

Give a client, tenant, project, or workstream its own inbox, token boundary, labels, and operational record.

View recipe

API foundations

Ship a production API integration

Use schemas, scoped auth, idempotency, error handling, and rate-limit behavior before moving an agent workflow to production.

View recipe

Uniquely Gent

Workflows that need more than an email API.

These depend on Gent's model of delegated correspondence: each agent has its own address, scoped authority, shared context, human review, and durable history.

Outbound follow-up

Send relationship-aware outreach

Use relationship history, contact enrichment, templates, and sequence prompts so outreach references the real record.

View recipe

Team collaboration

Run a team inbox with one contact graph

Fan shared-address mail into member inboxes, share contact cards, add thread notes, and preserve relationship context across the team.

View recipe

Agent memory

Retrieve inbox context before an agent acts

Assemble messages, contacts, files, activity, and audit entries before drafting, routing, or escalating an email.

View recipe

Retrieval

Answer repeated customer questions from approved sources

Use a retrieval source bucket to draft or support email answers for common customer questions without creating a separate chat surface.

View recipe

Governance

Configure AI consent, region, and audit controls

Set tenant and inbox controls before AI features process customer content, then keep export and deletion paths ready.

View recipe

Delivery controls

Configure sender rules, forwarding, and templates

Set the operating guardrails around who can reach the inbox, where copies go, and how repeated replies are shaped.

View recipe

Governance

Pause an agent and take over

Pause, rotate, or revoke a token, then hand back the conversation to a human.

View recipe

Usage controls

Track usage and set caps

Measure inbox growth, workflow volume, approvals, files, and storage before applying flexible or enforced limits.

View recipe

Coverage

Built around the same primitives as the API.

The library covers the core surfaces that turn email into delegated work: inboxes, messages, tokens, approvals, routes, files, context, activity, and usage controls.

AI workflows Activity Agenda Alerts Approvals Audit log Auth API Caps Compliance Contact sharing Contacts Context groups Distribution lists Domains Enrichment Errors Event types Events Files Forwarding Idempotency Inbox settings Inboxes Invites Labels Messages Pricing Rate limits Relationships Retrieval Schemas Sender rules Sequences Stats Tasks Templates Thread notes Time utils Tokens Usage Usage controls Work Routes Workflow rules Workflows