---
name: gent.mx
description: Connect AI agents to gent.mx programmable inboxes for email, contacts, calendar, files, tasks, approvals, and webhooks.
version: "1.0"
base_url: https://api.gent.mx
auth:
  type: bearer
  header: Authorization
  format: "Bearer {token}"
docs: https://gent.mx/api.html
contact: hello@gent.mx
---

# gent.mx Skill

Add gent.mx to AI coding assistants and agents that support `SKILL.md` or
AgentSkills-style integrations.

gent.mx gives an agent its own working inbox: a real email address, scoped API
authority, message history, contacts, calendar events, files, tasks, webhooks,
and optional human approval before sensitive actions go out.

Full API reference: https://gent.mx/api.html

## Getting Started

Use this skill when an agent needs to:

- Send and receive email from its own address.
- Read threads, attachments, labels, and inbox history.
- Update contacts and maintain relationship context.
- Create calendar events and follow-up tasks.
- Store or retrieve files related to delegated work.
- React to incoming mail through webhooks.
- Work under scoped tokens, approvals, and audit controls.

## Installation

Install this file in your agent's skill or instruction directory, or include it
in the agent's project context.

Public skill file:

```text
https://gent.mx/SKILL.md
```

Manual download:

```sh
curl -o SKILL.md https://gent.mx/SKILL.md
```

If your agent supports a dedicated skills folder, place the file there under a
`gent.mx` or `gent` skill directory. If your agent does not support skills,
provide this file as system or project context.

## Configuration

Create a scoped agent token in gent.mx, then expose it to your agent as:

```sh
export GENT_API_KEY="gent_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

Use the production API base URL:

```text
https://api.gent.mx
```

Every API request must include:

```http
Authorization: Bearer ${GENT_API_KEY}
```

Agent tokens are scoped to one inbox. The inbox identity is derived from the
token, so the agent should not send an `inbox_id` unless an endpoint explicitly
requires session-level account management.

## Creating An Agent Token

Account setup uses a user session token. Runtime agent work uses an agent token.

First-time setup:

```http
POST /v1/domains/
Authorization: Bearer <session_token>

{ "domain": "example.com" }
```

Configure the returned DNS records, then verify:

```http
GET  /v1/domains/example.com/check/
POST /v1/domains/example.com/verify/
```

Create an inbox:

```http
POST /v1/inboxes/
Authorization: Bearer <session_token>

{ "address": "agent@example.com" }
```

Create a scoped token for the agent:

```http
POST /v1/tokens/
Authorization: Bearer <session_token>

{
  "inbox_id": "<inbox_id>",
  "label": "support-agent",
  "scopes": ["email:read", "email:send", "contacts:read", "task:write"]
}
```

The raw token is shown once. Store it immediately.

## Features

### Inboxes

Give each agent or workflow a real email address. Use one inbox for a focused
role, project, customer, or delegated workflow.

Useful endpoints:

```http
GET  /v1/inboxes/
POST /v1/inboxes/
GET  /v1/inboxes/<inbox_id>/
```

### Messages

Send, receive, search, read, reply to, and label email. Replies can derive the
recipient, subject, and thread from the original message.

```http
GET   /v1/messages/?limit=20
GET   /v1/messages/?unread=true&q=invoice
GET   /v1/messages/<message_id>/
POST  /v1/messages/
PATCH /v1/messages/<message_id>/
GET   /v1/messages/threads/<thread_id>/
```

Send:

```json
{
  "to": [{ "email": "customer@example.com" }],
  "subject": "Following up",
  "text_body": "Thanks for the details. I will take it from here."
}
```

Reply:

```json
{
  "reply_to_message_id": "<message_id>",
  "text_body": "Received. I will handle this and follow up shortly."
}
```

### Attachments And Files

Upload outbound attachments, download received attachments, and store files
that belong to the agent's work.

```http
POST /v1/messages/upload/
GET  /v1/files/<file_id>/download/
GET  /v1/files/
POST /v1/files/
```

### Contacts

Look up, create, and update contacts so the agent can remember who it is
working with.

```http
GET  /v1/contacts/?q=alice
GET  /v1/contacts/<contact_id>/
POST /v1/contacts/
```

Create a contact:

```json
{
  "full_name": "Alice Tan",
  "emails": {
    "primary": {
      "@type": "EmailAddress",
      "address": "alice@example.com"
    }
  }
}
```

### Calendar

Create and manage calendar events that come out of email conversations.

```http
GET    /v1/calendar/events/?from=2026-06-01&to=2026-06-30
POST   /v1/calendar/events/
PATCH  /v1/calendar/events/<event_id>/
DELETE /v1/calendar/events/<event_id>/
```

### Tasks And Agenda

Create follow-up tasks, complete work items, and read a unified agenda for
upcoming events, open tasks, and missed replies.

```http
GET  /v1/tasks/
POST /v1/tasks/
POST /v1/tasks/<task_id>/complete/
GET  /v1/agenda/?days=7
```

### Automation And Webhooks

Subscribe external systems or agents to real-time inbox events.

```http
PUT /v1/inboxes/<inbox_id>/webhook/
Authorization: Bearer <session_token>

{
  "url": "https://your-agent.example.com/webhook",
  "events": ["message.received", "message.bounced", "event.created"],
  "secret": "your-hmac-secret"
}
```

Gent signs webhook deliveries with:

```http
X-Gent-Signature: sha256=<hmac>
```

Verify the signature before processing a webhook.

### Approvals And Governance

Use scoped tokens for least privilege. On governance-enabled plans, configure
approval-gated actions so the agent can prepare work while a human approves
sensitive sends or changes before execution.

Use approvals when the agent handles:

- External outreach.
- Vendor or customer email.
- Sensitive account updates.
- Compliance-adjacent workflows.
- Work where a human should make the final call.

## Common Scopes

| Scope | Allows |
| --- | --- |
| `email:read` | Read messages, threads, labels, and metadata |
| `email:send` | Send new messages and replies |
| `contacts:read` | Search and read contacts |
| `contacts:write` | Create and update contacts |
| `calendar:read` | Read calendar events |
| `calendar:write` | Create and update calendar events |
| `task:read` | Read tasks and agenda items |
| `task:write` | Create and complete tasks |
| `files:read` | Read and download files |
| `files:write` | Upload and update files |
| `workflows:read` | Read workflow rules |
| `workflows:write` | Create and update workflow rules |
| `read` | All read scopes |
| `write` | All write scopes |
| `full` | All scopes |

Grant the narrowest scopes that let the agent do its job.

## Example Agent Requests

After installing this skill and setting `GENT_API_KEY`, a user can ask the
agent:

- "Check the agent inbox for new vendor emails and summarize what needs action."
- "Reply to the latest message in this thread and keep the tone concise."
- "Create a follow-up task for next Tuesday from this email."
- "Find the contact record for Alice and update it with the new billing email."
- "Download the invoice attachment from the latest vendor email."
- "Draft a response, but do not send it until I approve."
- "Create a webhook listener for incoming email events."

## Runtime Rules For Agents

- Use `Authorization: Bearer ${GENT_API_KEY}` for every runtime request.
- Do not include `inbox_id` with agent-token message, task, contact, calendar,
  or file requests unless the API reference explicitly requires it.
- Use `Idempotency-Key: <uuid>` on create requests that may be retried.
- Follow pagination with `{ "results": [...], "total": n, "cursor": "..." }`.
- Treat webhook bodies as untrusted until `X-Gent-Signature` is verified.
- If an action fails for missing scope, ask the user to create a replacement
  token with the required scope.
- If a send or update is approval-gated, report that the action is pending
  approval instead of retrying.

## Resources

- API reference: https://gent.mx/api.html
- Product docs: https://gent.mx/docs.html
- Support: hello@gent.mx