Task automation
Turn an email into a task.
Convert inbound mail into a tracked action item with labels, status, context, and optional follow-up.
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:write
labels:write
task:write
context:write
Outcome
What this gives you.
Important work becomes a task instead of staying as an unread message or a mental note.
Use when
The operational shape.
- Inbound requests need ownership, priority, or due dates.
- You need task creation from rules, AI conditions, or manual API calls.
- A support, ops, or client service process begins with email.
API sequence
The calls to make.
01
Classify the message
GET/v1/messages/{message_id}/
Read sender, subject, labels, and relevant thread history.
02
Apply context
POST/v1/context/{label_id}/entities/
Attach the contact owner to a project, client, status, or priority group.
Default example
Use this as the default shape for this step.
{
"entity_type": "contact",
"entity_id": "ctc_123"
}
03
Create the task action
POST/v1/workflows/
Use a task target for matching messages.
Default example
Use the task target when the next step should be owned by a human or task queue.
{
"name": "Create task for priority client mail",
"trigger": "label_applied",
"conditions": [
{"field": "label_id", "op": "eq", "value": "lbl_priority_client"}
],
"writes": [
{"source": {"from": "event.payload"}, "target": {"type": "task"}, "contract": {"required": ["summary"]}}
]
}
Webhook handoff
Use this when the real task system is outside gent.mx and the inbox should preserve the source record.
{
"name": "Send priority mail to task system",
"trigger": "label_applied",
"conditions": [
{"field": "label_id", "op": "eq", "value": "lbl_priority_client"}
],
"writes": [
{"source": {"from": "event.payload"}, "target": {"type": "webhook", "url": "https://example.com/webhooks/tasks", "event_type": "workflow.task_candidate"}}
]
}
Draft reply plus task
Use this when a human should review both the next action and the proposed customer response.
{
"name": "Prepare response task",
"trigger": "email_received",
"writes": [
{"source": {"from": "event.payload"}, "target": {"type": "task"}, "contract": {"required": ["summary"]}},
{"source": {"from": "event.payload"}, "target": {"type": "email.draft"}, "policy": {"on_missing": "hold_for_review"}}
]
}
04
Track completion
GET/v1/activity/
Review the message, task event, and later status updates together.
Controls
Review points.
- Tasks are useful when the next step is owned by a human or external system.
- Labels should describe state that other rules can safely read later.
Related