Gent API Documentation

API basics
Overview

The gent.mx API gives your agents a dedicated email address, token-based access control, and a growing set of communication primitives — starting with email.

  • Workspace — Email, Labels, Contacts, Calendar & Tasks, Workflow
  • Intelligence — activity feeds, relationship graphs, AI enrichment
  • Team Collaboration — contact sharing, thread notes, templates, distribution lists
  • Management — inboxes, tokens, settings
  • Billing & Audit — spend caps, usage, audit log
  • Compliance — GDPR / SOC2
  • Reference — schemas, errors, rate limits
Base URL
https://api.gent.mx
All requests over HTTPS. Paths start with /v1/. All responses are JSON, including errors.
Request Access

Gent is invite-only. Submit an email address to request access — the team reviews it and sends a single-use sign-up link. No account required.

POST /v1/waitlist/ Submit an access request  public
Request
{ "email": "you@example.com" }
FieldTypeRequiredDescription
emailstringrequiredApplicant's email address. Idempotent — submitting the same address twice returns 202 without creating a duplicate.
202 Accepted
{ "status": "pending" }
Response is identical whether the email was new or already on the list — no enumeration. Public access-request endpoints use stricter abuse controls than authenticated API traffic.
GET /v1/waitlist/validate/ Validate a sign-up token  public
Query params
ParamTypeRequiredDescription
emailstringrequiredEmail address from the approval link.
signup_tokenstringrequiredSingle-use token from the approval link.
200 OK — token is valid
{ "email": "you@example.com" }
Called by the sign-up page before showing the registration form. Returns 400 when the token is invalid, expired, or already redeemed. Pass both email and signup_token from the approval email link.
API basics
Authentication

All requests pass a Bearer token in the Authorization header. Two token types — agent tokens for scoped inbox access, session tokens for account management.

Agent token — scoped per inbox
Authorization: Bearer gent_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Created via POST /v1/tokens/ with explicit scopes (e.g. email:read, email:send). Used across Workspace, Intelligence, Team Collaboration, and Billing & Audit. Endpoints marked scope: xxx require an agent token with that scope.

Session token — identifies the account owner
Authorization: Bearer <access_token>

Issued on sign-in. Required for inbox and token management. Endpoints marked user auth accept only session tokens; most other endpoints accept both.

Sign in
# Returns access_token (short-lived) + refresh_token (long-lived) POST /auth/login/ { "email": "you@example.com", "password": "..." } # 200 OK { "access_token": "eyJ...", "refresh_token": "eyJ..." }
Header Required Description
Authorization required Bearer token — agent token (gent_…) or session token depending on the endpoint.
Content-Type required Must be application/json for write requests.
inbox_id convention
  • Agent token — inbox_id is derived from the token; never supply it.
  • Session token — supply inbox_id as a query param on GET / PATCH / DELETE, or in the request body on POST.
  • Endpoints marked scope: xxx — accept an agent token with that scope, or any session token for the same inbox.
  • Endpoints marked user auth — session token only; agent tokens are not accepted.
Sign up — or create an account at gent.mx/join
# Step 1 — create account POST /auth/signup/ { "email": "you@example.com", "password": "...", "region": "eu" } # Step 2 — confirm email (code sent to inbox) POST /auth/signup/confirm/ { "email": "you@example.com", "code": "123456" }
After confirmation, sign in and check GET /v1/users/me/ - the next_step field tells you exactly what to do next. A verified domain is required before creating your first inbox. See the workflow quickstart for the full setup sequence.
API basics
Workflow Quickstart

The full setup sequence now lives at the top of the workflow library, where it acts as the prerequisite for every recipe: verify a domain, create an inbox, issue an agent token, send a first message, and read from the inbox.

→
Open the workflow quickstart

Use it before the recipe library. This API reference keeps the endpoint details, schemas, errors, scopes, and edge-case behavior.

Need the raw endpoint details? Continue to Domains, Inboxes, Tokens, and Messages.
API basics
Where to Build Next

Use the workflow library when you want a practical implementation path. Use this API reference when you need the exact contract for an endpoint, scope, schema, error, or limit.

→
Workflow library

Prerequisite setup, common use cases, and Gent-only workflows with example payloads.

→
Endpoint reference

Read, send, automate, approve, govern, and audit delegated email work.