Identities - Sente

An identity is a long-lived email address on sente.run that your agent owns. It is the communication layer: one identity can hold zero or many registrations at different apps. See Identities and registrations.

The identity object

{
  "id": "idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5",
  "name": "support-agent",
  "description": "Handles signup flows for the QA bot",
  "email": "swift-otter-4821@sente.run",
  "createdAt": "2026-07-20T09:14:03.201Z"
}

Create an identity

POST /v1/identities

Field	Type	Required	Description
`name`	string ≤ 200	no	Display name.
`description`	string ≤ 2000	no	Free-text note.
`localPart`	string	no	Requested address local part: 1–64 chars of `a-z0-9._-`, must start and end alphanumeric, no consecutive dots. Lowercased. Omitted → a random readable address (e.g. `swift-otter-4821`).
`onConflict`	`"error"` \| `"suffix"`	no	What to do if `localPart` is taken. `"error"` (default) → `409`; `"suffix"` → append a random suffix until free.

curl -X POST https://api.sente.run/v1/identities \
  -H "Authorization: Bearer sk_sente_..." \
  -H "content-type: application/json" \
  -d '{"name": "support-agent", "localPart": "acme-qa"}'

Response 201:

{
  "id": "idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5",
  "name": "support-agent",
  "email": "acme-qa@sente.run"
}

Errors:

Status	Body	When
`409`	`{"error": "local-part taken", "localPart": "acme-qa"}`	Requested `localPart` is in use and `onConflict` is `"error"`.
`409`	`{"error": "local-part reserved", "code": "LOCAL_PART_RESERVED", "localPart": "support"}`	Exact reserved words (`support`, `admin`, `billing`, `postmaster`, …) can’t be allocated. `support-bot` is fine; `support` is not.
`429`	`{"error": "identity limit reached (25 per org)", "code": "IDENTITY_LIMIT_EXCEEDED", "limit": 25}`	Per-org identity cap — plan-dependent (9 free / 25 pro / 100 team); `limit` reflects your plan.

List identities

GET /v1/identities

curl https://api.sente.run/v1/identities \
  -H "Authorization: Bearer sk_sente_..."

Response 200:

[
  {
    "id": "idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5",
    "name": "support-agent",
    "email": "acme-qa@sente.run",
    "createdAt": "2026-07-20T09:14:03.201Z"
  }
]

Get an identity

GET /v1/identities/:id

curl https://api.sente.run/v1/identities/idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5 \
  -H "Authorization: Bearer sk_sente_..."

Response 200:

{
  "id": "idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5",
  "name": "support-agent",
  "description": "Handles signup flows for the QA bot",
  "email": "acme-qa@sente.run",
  "createdAt": "2026-07-20T09:14:03.201Z"
}

404 {"error": "not found"} for unknown ids and other orgs’ identities.

Delete an identity

DELETE /v1/identities/:id Hard delete. Removes the identity and everything under it — messages, registrations, runs, and identity-scoped webhooks — and frees the local part for re-creation. Org-wide webhooks are untouched. Mail sent to the old address afterwards is dropped.

This is not reversible, and it deletes the credential vault for every registration under the identity. If the identity has Sente-created accounts you still need, fetch their credentials first.

curl -X DELETE https://api.sente.run/v1/identities/idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5 \
  -H "Authorization: Bearer sk_sente_..."

Response: 204 with no body. Errors:

Status	Body	When
`409`	`{"error": "identity has a live run", "code": "IDENTITY_BUSY"}`	A run is queued, running, awaiting verification, or blocked. Wait for it to finish or abort it.
`404`	`{"error": "not found"}`	Unknown id.

​The identity object

​Create an identity

​List identities

​Get an identity

​Delete an identity

The identity object

Create an identity

List identities

Get an identity

Delete an identity