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.
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
workflows:read
workflows:write
Outcome
What this gives you.
Inbound email reaches an agent, queue, or internal system with the message record still intact.
Use when
The operational shape.
- A lead, support request, vendor email, or operations message should start work outside the inbox.
- You need routing that can inspect sender, labels, attachments, and message context.
- You want a durable event rather than a fragile mailbox-forwarding script.
API sequence
The calls to make.
01
Read the message event
GET/v1/messages/{message_id}/
Fetch sender, recipients, subject, snippet, labels, and attachments.
02
Create the webhook rule
POST/v1/workflows/
Match inbound mail and send a webhook payload to your downstream system.
Default example
Use this as the default shape for this step.
{
"name": "New lead router",
"trigger": "email_received",
"conditions": [
{"field": "to_address", "op": "eq", "value": "leads@mail.example.com"}
],
"writes": [
{"source": {"from": "event.payload"}, "target": {"type": "webhook", "url": "https://example.com/webhooks/gent-leads", "event_type": "workflow.inbound_route"}}
]
}
03
Refine route conditions
PATCH/v1/workflows/{rule_id}/
Adjust sender, label, subject, attachment state, or AI conditions as the workflow matures.
Default example
Use a deterministic rule when sender, recipient, label, or attachment state is enough to route the message.
{
"conditions": [
{"field": "from_domain", "op": "eq", "value": "partner.example"}
],
"writes": [
{"source": {"from": "event.payload"}, "target": {"type": "email.add_label", "label_id": "lbl_partner"}},
{"source": {"from": "event.payload"}, "target": {"type": "webhook", "url": "https://example.com/webhooks/partner-mail", "event_type": "workflow.partner_mail"}}
]
}
Sender-domain route
Use this when all mail from a vendor, customer, or partner domain should enter the same workflow.
{
"conditions": [
{"field": "from_domain", "op": "eq", "value": "vendor.example"}
],
"writes": [
{"source": {"from": "event.payload"}, "target": {"type": "webhook", "url": "https://example.com/webhooks/vendor-mail", "event_type": "workflow.vendor_mail"}}
]
}
AI condition route
Use this when the route depends on message meaning, not just fixed fields. Keep this behind a plan and review policy.
{
"conditions": [
{"op": "ai", "value": "The message appears to include an invoice or payment request."}
],
"writes": [
{"source": {"from": "event.payload"}, "target": {"type": "email.add_label", "label_id": "lbl_invoice"}},
{"source": {"from": "event.payload"}, "target": {"type": "webhook", "url": "https://example.com/webhooks/finance-mail", "event_type": "workflow.invoice_mail"}}
]
}
04
Receive the webhook event
POSThttps://your-webhook-endpoint.example/inbox-route
Gent sends a POST callback to this endpoint with the message ID, trigger, and routing context.
Webhook event payload
Use this event shape when your own router or webhook consumer owns the final handoff.
{
"event": "workflow_rule_matched",
"message_id": "msg_123",
"inbox_id": "inb_123",
"rule_id": "rule_123",
"trigger": "email_received",
"context": {
"subject": "New lead",
"from_address": "buyer@example.com"
},
"idempotency_key": "msg_123:rule_123"
}
Webhook consumer response
Use this when your system acknowledges the handoff and stores its own downstream work ID.
{
"status": "accepted",
"external_work_id": "lead_789",
"message_id": "msg_123",
"received_idempotency_key": "msg_123:rule_123"
}
Controls
Review points.
- Keep the message ID as the source of truth; downstream tools can fetch richer context when needed.
- Use idempotency keys in your webhook consumer so retries do not create duplicate work.
Related