Identities

An identity is an email address or domain connected to your Kurrier workspace. Identities determine which address Kurrier sends from and, when incoming-mail settings are available, which mailbox Kurrier synchronizes.

The API key can access only identities available to the user who created it. For authentication and the hosted API base URL, see API Authentication.

All paths below are relative to:

https://YOUR_KURRIER_HOST/api/kurrier

Identity types

Kurrier supports:

• Email identities, such as support@example.com
• Domain identities, such as example.com

An identity can be backed by a configured mail provider or a custom SMTP account. It can also store verification status, provider configuration, and metadata.

Create an email identity

POST /identities

Creates an email identity backed by an SMTP account. When that account also has IMAP settings, Kurrier starts mailbox discovery, message backfill, and live synchronization.

{
  "value": "user@example.com",
  "displayName": "User Example",
  "smtpAccountId": "0d63d43a-2b3f-4f8e-9a76-2f0f2c9a3b1e"
}

The response includes the created identity and a backfill result:

• completed: mailbox discovery completed and synchronization was queued.
• skipped: the account has no IMAP settings and is send-only.
• failed: mailbox discovery failed or timed out. The identity remains created; review the account's IMAP settings.

If the workspace already contains an email identity with the same address, the API returns 409 IDENTITY_EXISTS.

List identities

GET /identities

Returns the identities visible to the authenticated user in the current workspace.

Get an identity

GET /identities/{id}

Returns an identity by its internal ID when the API key has access to it.

Update an identity

PATCH /identities/{id}

Partially updates an accessible identity. Send only the fields you want to change.

Delete an identity

DELETE /identities/{id}

Permanently deletes the identity. Associated mailbox and synchronization data may also be removed, so verify the ID before making this request.

Example identity object

{
  "id": "1a9b317a-8a84-493a-b9f8-83a3800861e2",
  "owner_id": "be7a7201-76db-4b73-a5e0-ad6a1b93cf1f",
  "kind": "email",
  "public_id": "9ANdDSgvj5",
  "value": "me@example.com",
  "incoming_domain": false,
  "domain_identity_id": "b4950019-500a-44a6-9b24-08b2517f1b3d",
  "dns_records": null,
  "meta": {},
  "provider_id": "c4248dd5-46f2-48f5-9d5b-91b7e7d67c74",
  "smtp_account_id": null,
  "status": "unverified",
  "created_at": "2025-11-15 10:47:23.60418+00",
  "updated_at": "2025-11-15 10:47:23.60418+00"
}