Identities
Manage email identities in Kurrier
Identities represent email addresses or domains that you have connected to Kurrier. Each identity can optionally belong to a provider (SES, SMTP, Mailgun, etc.) and is used when sending or receiving email.
These endpoints let you create, list, update, and delete identities from your backend using your Kurrier API key.
All routes below are relative to:
https://your-domain.com/api/kurrierWhat is an Identity?
An identity is either:
- an email identity (
email@example.com) - a domain identity (
example.com)
Identities also store DNS verification records, provider configuration, status, and metadata.
Create an email identity
POST /identities
Creates an email identity backed by an SMTP account, assigns it to workspace members, and — when the SMTP account has IMAP settings — kicks off mailbox discovery, backfill, and live sync, exactly like adding the identity from the dashboard.
{
"value": "user@example.com",
"displayName": "User Example",
"smtpAccountId": "0d63d43a-2b3f-4f8e-9a76-2f0f2c9a3b1e"
}| Field | Description |
|---|---|
| value (required) | The email address of the identity. |
| smtpAccountId (required) | The SMTP account that backs this identity. Must belong to the API key owner. |
| displayName (optional) | Display name used when sending. |
| sharedWithWorkspace (optional) | Share the identity with all workspace members. Defaults to false. |
| memberIds (optional) | Workspace member user ids granted access. Defaults to the key owner. Ignored when sharedWithWorkspace is true. |
| dailyQuota (optional) | Daily sending quota. Defaults to the standard IMAP quota. |
| userEmail (optional) | Admin API key only: create the identity on behalf of this user. |
The response contains the created identity plus a backfill field:
"completed"— IMAP mailbox discovery finished and message backfill + IDLE sync were queued"skipped"— the SMTP account has no IMAP settings (send-only)"failed"— mailbox discovery failed or timed out (check the account's IMAP credentials; the identity is still created)
Returns 409 IDENTITY_EXISTS if an email identity with the same address
already exists in the workspace.
List identities
GET /identities
Returns all identities owned by the authenticated user.
Get a single identity
GET /identities/{id}
Fetch an identity by its ID.
Update an identity
PATCH /identities/{id}
Partially update an identity.
Delete an identity
DELETE /identities/{id}
Permanently deletes an identity.
Note: This cascades to mailboxes and worker sync state.
Identity object format
Example response object:
{
"id":"1a9b317a-8a84-493a-b9f8-83a3800861e2",
"owner_id":"be7a7201-76db-4b73-a5e0-ad6a1b93cf1f",
"kind":"email",
"public_id":"9ANdDSgvj5",
"value":"me@myapp.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"
}