Identities Guide

Overview

Use identities to decide who sends outbound messages from Enginy. The public API lets you list identities, inspect the mailboxes attached to each identity, update public profile fields, and automate the email signature.

Find an Identity

Call GET /v1/identities to list identities available to your API key workspace.

curl "https://openapi.enginy.ai/v1/identities?page=1&pageSize=25" \
  -H "x-api-key: $ENGINY_API_KEY"

Each identity includes:

Field	Notes
`id`	Use this as `identityId` in update and mailbox endpoints.
`appUrl`	Direct Enginy app URL for opening the identity.
`email`	Primary email address stored on the identity.
`emails`	All active mailbox email addresses associated with the identity.
`signature`	HTML appended to outbound emails sent from this identity.

Update Profile Fields

Call PATCH /v1/identities/{identityId} to update public profile fields for one identity. This endpoint currently requires an API key with the ALL scope. Enginy has an IDENTITIES_READ scope for reads, but there is not yet an identity-specific write scope in the public API key model.

curl -X PATCH "https://openapi.enginy.ai/v1/identities/123" \
  -H "x-api-key: $ENGINY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "Jane Doe",
    "firstName": "Jane",
    "lastName": "Doe",
    "jobTitle": "VP Sales",
    "phoneNumber": "+34600000000",
    "linkedInUrl": "https://www.linkedin.com/in/jane-doe",
    "scheduleMeetingUrl": "https://cal.example.com/jane",
    "timezone": "Europe/Madrid"
  }'

Writable fields:

Field	Type
`name`	string or null
`firstName`	string or null
`lastName`	string or null
`jobTitle`	string or null
`email`	string or null
`phoneNumber`	string or null
`linkedInUrl`	string or null
`scheduleMeetingUrl`	string or null
`timezone`	string or null
`profileOverview`	string or null
`keyResponsibilities`	string or null
`interests`	string[] or null
`languages`	string[] or null
`gender`	string or null
`seniorityLevel`	string or null
`educations`	string or null
`previousPositions`	string or null
`countryCode`	string or null
`signature`	string or null

You only need to send the fields you want to change. At least one field is required.

Update Email Signature

Send signature as HTML. Enginy stores the exact HTML in signature and appends it to outbound emails sent from the identity.

curl -X PATCH "https://openapi.enginy.ai/v1/identities/123" \
  -H "x-api-key: $ENGINY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "signature": "<p>Jane Doe<br>VP Sales at Enginy</p><p><a href=\"https://enginy.ai\">enginy.ai</a></p>"
  }'

Example response fields:

{
  "signature": "<p>Jane Doe<br>VP Sales at Enginy</p><p><a href=\"https://enginy.ai\">enginy.ai</a></p>"
}

Clear Email Signature

Send signature: null to remove the signature.

curl -X PATCH "https://openapi.enginy.ai/v1/identities/123" \
  -H "x-api-key: $ENGINY_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "signature": null }'

Mailboxes

The email field on the identity is the primary identity email address, but it does not configure mailbox credentials by itself. Use the mailbox endpoints when you need to inspect or configure sending mailboxes:

GET /v1/identities/{identityId}/mailboxes
POST /v1/identities/{identityId}/mailboxes

Validation and Errors

Status	Meaning
`400`	The identity ID or request body is invalid.
`404`	The identity does not exist in the API key workspace or was deleted.

API documentation

Endpoints

Overview

Find an Identity

Update Profile Fields

Update Email Signature

Clear Email Signature

Mailboxes

Validation and Errors

​Overview

​Find an Identity

​Update Profile Fields

​Update Email Signature

​Clear Email Signature

​Mailboxes

​Validation and Errors

Overview

Find an Identity

Update Profile Fields

Update Email Signature

Clear Email Signature

Mailboxes

Validation and Errors