Skip to Content

The IdentityClient type of the TypeScript SDK, which identities.listClients take or answer.

type IdentityClient = {
  accountId: string | null
  asOrg: string | null
  asn: number | null
  city: string | null
  client: string | null
  country: string | null
  credentialActive: boolean | null
  credentialId: string | null
  credentialKind: string | null
  credentialName: string | null
  facets: ('mail' | 'pim')[]
  firstSeenAt: number
  id: string
  identityId: string
  ip: string
  lastSeenAt: number
  notifiedAt: number | null
  protocol: ('imap' | 'pop3' | 'sieve' | 'smtp' | 'caldav' | 'carddav' | 'dav' | 'jmap' | 'webmail' | 'api')
  touchCount: number
}

Fields

FieldTypeDescription
accountIdstring | nullThe identity's account at first sighting, or null
asOrgstring | nullAutonomous system organisation, or null (same rule)
asnnumber | nullAutonomous system number, or null (same rule)
citystring | nullCity, or null (same rule as country)
clientstring | nullThe client's self-description (User-Agent, IMAP ID) as last seen, or null
countrystring | nullISO 3166-1 alpha-2 country, or null when NOBODY LOOKED — never 'unknown'. Mail-protocol rows carry null until the fleet resolves locations
credentialActiveboolean | nullWhether the credential would still be accepted now: true while it exists, is not revoked and is not past its expiry; false once revoked, expired or purged; null when unattributed. Each webmail sign-in mints its own credential, so a webmail row whose value is false is a session that has ended
credentialIdstring | nullThe credential the client presented — the thing to revoke — or null when the reporting surface could not attribute one. Never render null as 'your password'
credentialKindstring | nullpassword (the identity's own password) or app_password; null when unattributed or purged
credentialNamestring | nullThe credential's label as its owner gave it ("old-phone"; webmail names its sessions "webmail session"), so a reader can say which app password to revoke without a lookup per row. null when unattributed, unnamed, or purged; a revoked credential keeps its name
facets('mail' | 'pim')[]What the client TOUCHED — mail, pim (calendars, contacts, tasks) or both — never what the identity owns. A JMAP client that read a mailbox and a calendar carries both
firstSeenAtnumberFirst sighting, epoch seconds
idstringClient row ULID — the FIRST sighting's; not the sort key
identityIdstringThe identity this client reached
ipstringThe client's address as LAST seen, canonical (RFC 5952 for v6). An IPv6 client is one row per /64: the address here is the most recent host within it
lastSeenAtnumberLast sighting, epoch seconds — coalesced hourly, so exact for a first sighting and up to one hour stale after it. 'Connected now' is a presentation rule over this, not a fact the row asserts
notifiedAtnumber | nullWhen this client was flagged as a NEW LOCATION — a network or (country, network operator) the identity had not been reached from before — and the notice raised: mail to the identity's inbox and verified recovery address (unless the identity's prefs carry notifyNewClient: false) and an identity.client.new event. null for the first client an identity ever had, for a known network or location, and past the daily cap
protocol('imap' | 'pop3' | 'sieve' | 'smtp' | 'caldav' | 'carddav' | 'dav' | 'jmap' | 'webmail' | 'api')How the client reached the platform. dav is a CalDAV/CardDAV request on neither half (a principal PROPFIND); api is the REST surface; webmail is a browser session reported by the webmail frontend
touchCountnumberHow many coalesced sightings were recorded, not how many connections were made

Used by

MethodWhat it does
identities.listClientsList an identity's clients

On this page