≡ identities API
≡ Related information
The identities API allows to manage the user's identities (each account can have multiple identities).
.. rst-class:: api-main-section
.. api-member:: :name: :permission:`accountsIdentities` Create, modify or delete your mail account identities
.. rst-class:: api-permission-info
Note
The permission accountsRead is required to use messenger.identities.*.
.. rst-class:: api-main-section
.. api-section-annotation-hack::
Create a new identity in the specified account.
.. api-header::
:label: Parameters
.. api-member::
:name: ``accountId``
:type: (:ref:`accounts.MailAccountId`)
.. api-member::
:name: ``details``
:type: (:ref:`identities.MailIdentity`)
.. api-header::
:label: Return type (`Promise`_)
.. api-member::
:type: :ref:`identities.MailIdentity`
.. _Promise: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
.. api-header:: :label: Required permissions - :permission:`accountsRead` - :permission:`accountsIdentities`
.. api-section-annotation-hack::
Attempts to delete the requested identity. Default identities cannot be deleted.
.. api-header::
:label: Parameters
.. api-member::
:name: ``identityId``
:type: (string)
.. api-header:: :label: Required permissions - :permission:`accountsRead` - :permission:`accountsIdentities`
.. api-section-annotation-hack::
Returns details of the requested identity, or null if it doesn't exist.
.. api-header::
:label: Parameters
.. api-member::
:name: ``identityId``
:type: (string)
.. api-header::
:label: Return type (`Promise`_)
.. api-member::
:type: :ref:`identities.MailIdentity` or null
.. _Promise: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
.. api-header:: :label: Required permissions - :permission:`accountsRead`
.. api-section-annotation-hack::
Returns the default identity for the requested account, or null if it is not defined.
.. api-header::
:label: Parameters
.. api-member::
:name: ``accountId``
:type: (:ref:`accounts.MailAccountId`)
.. api-header::
:label: Return type (`Promise`_)
.. api-member::
:type: :ref:`identities.MailIdentity` or null
.. _Promise: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
.. api-header:: :label: Required permissions - :permission:`accountsRead`
.. api-section-annotation-hack::
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 :ref:`identities.getDefault` to get the default identity of an account.
.. api-header::
:label: Parameters
.. api-member::
:name: [``accountId``]
:type: (:ref:`accounts.MailAccountId`, optional)
.. api-header::
:label: Return type (`Promise`_)
.. api-member::
:type: array of :ref:`identities.MailIdentity`
.. _Promise: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
.. api-header:: :label: Required permissions - :permission:`accountsRead`
.. api-section-annotation-hack::
Sets the default identity for the requested account.
.. api-header::
:label: Parameters
.. api-member::
:name: ``accountId``
:type: (:ref:`accounts.MailAccountId`)
.. api-member::
:name: ``identityId``
:type: (string)
.. api-header:: :label: Required permissions - :permission:`accountsRead`
.. api-section-annotation-hack::
Updates the details of an identity.
.. api-header::
:label: Parameters
.. api-member::
:name: ``identityId``
:type: (string)
.. api-member::
:name: ``details``
:type: (:ref:`identities.MailIdentity`)
.. api-header::
:label: Return type (`Promise`_)
.. api-member::
:type: :ref:`identities.MailIdentity`
.. _Promise: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
.. api-header:: :label: Required permissions - :permission:`accountsRead` - :permission:`accountsIdentities`
.. rst-class:: api-main-section
.. api-section-annotation-hack::
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.
.. api-header::
:label: Parameters for onCreated.addListener(listener)
.. api-member::
:name: ``listener(identityId, identity)``
A function that will be called when this event occurs.
.. api-header::
:label: Parameters passed to the listener function
.. api-member::
:name: ``identityId``
:type: (string)
.. api-member::
:name: ``identity``
:type: (:ref:`identities.MailIdentity`)
.. api-header:: :label: Required permissions - :permission:`accountsRead`
.. api-section-annotation-hack::
Fired when an identity has been removed from an account.
.. api-header::
:label: Parameters for onDeleted.addListener(listener)
.. api-member::
:name: ``listener(identityId)``
A function that will be called when this event occurs.
.. api-header::
:label: Parameters passed to the listener function
.. api-member::
:name: ``identityId``
:type: (string)
.. api-header:: :label: Required permissions - :permission:`accountsRead`
.. api-section-annotation-hack::
Fired when one or more properties of an identity have been modified. The returned :ref:`identities.MailIdentity` includes only the changed values.
.. api-header::
:label: Parameters for onUpdated.addListener(listener)
.. api-member::
:name: ``listener(identityId, changedValues)``
A function that will be called when this event occurs.
.. api-header::
:label: Parameters passed to the listener function
.. api-member::
:name: ``identityId``
:type: (string)
.. api-member::
:name: ``changedValues``
:type: (:ref:`identities.MailIdentity`)
.. api-header:: :label: Required permissions - :permission:`accountsRead`
.. rst-class:: api-main-section
.. api-section-annotation-hack::
.. api-header::
:label: object
.. api-member::
:name: ``canEncrypt``
:type: (boolean)
Whether the encryption technology is configured to support message encryption.
.. api-member::
:name: ``canSign``
:type: (boolean)
Whether the encryption technology is configured to support message signing.
.. api-section-annotation-hack:: -- [Added in TB 76]
.. api-header::
:label: object
.. api-member::
:name: [``accountId``]
:type: (:ref:`accounts.MailAccountId`, optional)
The id of the :ref:`accounts.MailAccount` this identity belongs to. The :value:`accountId` property is read-only.
.. api-member::
:name: [``composeHtml``]
:type: (boolean, optional)
:annotation: -- [Added in TB 85, backported to TB 78.7.0]
If the identity uses HTML as the default compose format.
.. api-member::
:name: [``email``]
:type: (string, optional)
The user's email address as used when messages are sent from this identity.
.. api-member::
:name: [``encryptionCapabilities``]
:type: (object, optional)
:annotation: -- [Added in TB 128]
The encryption capabilities of this identity. Read only.
.. api-member::
:name: ``OpenPGP``
:type: (:ref:`identities.EncryptionCapabilities`)
The capabilities of this identity for the OpenPGP encryption technology.
.. api-member::
:name: ``S/MIME``
:type: (:ref:`identities.EncryptionCapabilities`)
The capabilities of this identity for the S/MIME encryption technology.
.. api-member::
:name: [``id``]
:type: (string, optional)
A unique identifier for this identity. The :value:`id` property is read-only.
.. api-member::
:name: [``label``]
:type: (string, optional)
A user-defined label for this identity.
.. api-member::
:name: [``name``]
:type: (string, optional)
The user's name as used when messages are sent from this identity.
.. api-member::
:name: [``organization``]
:type: (string, optional)
The organization associated with this identity.
.. api-member::
:name: [``replyTo``]
:type: (string, optional)
The reply-to email address associated with this identity.
.. api-member::
:name: [``signature``]
:type: (string, optional)
:annotation: -- [Added in TB 91]
The signature of the identity.
.. api-member::
:name: [``signatureIsPlainText``]
:type: (boolean, optional)
:annotation: -- [Added in TB 91]
If the signature should be interpreted as plain text or as HTML.