identities API

The identities API allows to manage the user’s identities (each account can have multiple identities).

Permissions

The following permissions influence the behavior of the API. Depending on which permissions are requested, additional methods might be available, or certain data may be included in responses.

Hint

Request permissions only when needed. Unnecessary requests may result in rejection during ATN review.

accountsIdentities



Create, modify or delete your mail account identities.

accountsRead



See your mail accounts, their identities and their folders.

Note

The permission accountsRead is required to use messenger.identities.*.

Functions

create(accountId, details)

– [Added in TB 91]

Create a new identity in the specified account.

Parameters

accountId

accountId

(MailAccountId)



details

details

(MailIdentity)



Return type (Promise)

_returns

MailIdentity



Required permissions

accountsIdentities
accountsRead

delete(identityId)

– [Added in TB 91]

Attempts to delete the requested identity. Default identities cannot be deleted.

Parameters

identityId

identityId

(string)



Required permissions

accountsIdentities
accountsRead

get(identityId)

– [Added in TB 91]

Returns details of the requested identity, or null if it doesn’t exist.

Parameters

identityId

identityId

(string)



Return type (Promise)

_returns

MailIdentity or null



Required permissions

accountsRead

getDefault(accountId)

– [Added in TB 91]

Returns the default identity for the requested account, or null if it is not defined.

Parameters

accountId

accountId

(MailAccountId)



Return type (Promise)

_returns

MailIdentity or null



Required permissions

accountsRead

list([accountId])

– [Added in TB 91]

Returns the identities of the specified account, or all identities if no account is specified. Do not expect the returned identities to be in any specific order. Use getDefault(accountId) to get the default identity of an account.

Parameters

accountId

[accountId]

(MailAccountId, optional)



Return type (Promise)

_returns

array of MailIdentity



Required permissions

accountsRead

setDefault(accountId, identityId)

– [Added in TB 91]

Sets the default identity for the requested account.

Parameters

accountId

accountId

(MailAccountId)



identityId

identityId

(string)



Required permissions

accountsRead

update(identityId, details)

– [Added in TB 91]

Updates the details of an identity.

Parameters

identityId

identityId

(string)



details

details

(MailIdentity)



Return type (Promise)

_returns

MailIdentity



Required permissions

accountsIdentities
accountsRead

Events

onCreated

– [Added in TB 91]

Fired when a new identity has been created and added to an account. The event also fires for default identities that are created when a new account is added.

Parameters for onCreated.addListener(listener)

listener(identityId, identity)

listener(identityId, identity)



A function that will be called when this event occurs.

Parameters passed to the listener function

identityId

identityId

(string)



identity

identity

(MailIdentity)



Required permissions

accountsRead

onDeleted

– [Added in TB 91]

Fired when an identity has been removed from an account.

Parameters for onDeleted.addListener(listener)

listener(identityId)

listener(identityId)



A function that will be called when this event occurs.

Parameters passed to the listener function

identityId

identityId

(string)



Required permissions

accountsRead

onUpdated

– [Added in TB 91]

Fired when one or more properties of an identity have been modified. The returned MailIdentity includes only the changed values.

Parameters for onUpdated.addListener(listener)

listener(identityId, changedValues)

listener(identityId, changedValues)



A function that will be called when this event occurs.

Parameters passed to the listener function

identityId

identityId

(string)



changedValues

changedValues

(MailIdentity)



Required permissions

accountsRead

Types

EncryptionCapabilities

– [Added in TB 128]

object

canEncrypt

canEncrypt

(boolean)



Whether the encryption technology is configured to support message encryption.

canSign

canSign

(boolean)



Whether the encryption technology is configured to support message signing.

MailIdentity

– [Added in TB 91]

object

accountId

[accountId]

(MailAccountId, optional)



The id of the MailAccount this identity belongs to. The accountId property is read-only.

composeHtml

[composeHtml]

(boolean, optional)



If the identity uses HTML as the default compose format.

email

[email]

(string, optional)



The user’s email address as used when messages are sent from this identity.

encryptionCapabilities

[encryptionCapabilities]

(object, optional)

– [Added in TB 128]



The encryption capabilities of this identity. Read only.

OpenPGP

OpenPGP

(EncryptionCapabilities)

– [Added in TB 128]



The capabilities of this identity for the OpenPGP encryption technology.

S/MIME

S/MIME

(EncryptionCapabilities)

– [Added in TB 128]



The capabilities of this identity for the S/MIME encryption technology.

id

[id]

(string, optional)



A unique identifier for this identity. The id property is read-only.

label

[label]

(string, optional)



A user-defined label for this identity.

name

[name]

(string, optional)



The user’s name as used when messages are sent from this identity.

organization

[organization]

(string, optional)



The organization associated with this identity.

replyTo

[replyTo]

(string, optional)



The reply-to email address associated with this identity.

signature

[signature]

(string, optional)



The signature of the identity.

signatureIsPlainText

[signatureIsPlainText]

(boolean, optional)



If the signature should be interpreted as plain text or as HTML.