contacts API
The contacts API allows to access and manage the user’s contacts.
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.
addressBooks
Read and modify your address books and contacts.
Functions
create(parentId, [id], properties)
– [Added in TB 64]
Adds a new contact to the address book with the id parentId.
Parameters
parentId
id
Assigns the contact an id. If an existing contact has this id, an exception is thrown.
properties
The properties object for the new contact. If it includes a vCard member, all specified legacy properties are ignored and the new contact will be based on the provided vCard string. If a UID is specified in the vCard string, which is already used by another contact, an exception is thrown.
Note
Using individual properties is deprecated, use the vCard member instead.
Required permissions
delete(id)
– [Added in TB 64]
Removes a contact from the address book. The contact is also removed from any mailing lists it is a member of.
Required permissions
get(id)
– [Added in TB 64]
Gets a single contact.
Required permissions
getPhoto(id)
– [Added in TB 106]
Gets the photo associated with this contact. Returns null, if no photo is available.
Required permissions
list(parentId)
– [Added in TB 64]
Gets all the contacts in the address book with the id parentId.
Required permissions
quickSearch([parentId], queryInfo)
– [Added in TB 68]
Gets all contacts matching queryInfo in the address book with the id parentId.
Parameters
parentId
The id of the address book to search. If not specified, all address books are searched.
queryInfo
Required permissions
setPhoto(id, file)
– [Added in TB 107]
Sets the photo associated with this contact.
Required permissions
update(id, properties)
– [Added in TB 64]
Updates a contact.
Parameters
id
properties
An object with properties to update the specified contact. Individual properties are removed, if they are set to null. If the provided object includes a vCard member, all specified legacy properties are ignored and the details of the contact will be replaced by the provided vCard. Changes to the UID will be ignored.
Note
Using individual properties is deprecated, use the vCard member instead.
Required permissions
Events
onCreated
– [Added in TB 64]
Fired when a contact is created.
Parameters for onCreated.addListener(listener)
listener(node)
A function that will be called when this event occurs.
Required permissions
onDeleted
– [Added in TB 64]
Fired when a contact is removed from an address book.
Parameters for onDeleted.addListener(listener)
listener(parentId, id)
A function that will be called when this event occurs.
Required permissions
onUpdated
– [Added in TB 64]
Fired when a contact is changed.
Parameters for onUpdated.addListener(listener)
listener(node, changedProperties)
A function that will be called when this event occurs.
Parameters passed to the listener function
node
changedProperties
Required permissions
Types
ContactNode
– [Added in TB 64]
A node representing a contact in an address book.
object
id
The unique identifier for the node. IDs are unique within the current profile, and they remain valid even after the program is restarted.
properties
type
parentId
The id of the parent object.
readOnly
Indicates if the object is read-only.
remote
Indicates if the object came from a remote address book.
ContactProperties
– [Added in TB 64]
A set of individual properties for a particular contact, and its vCard string. Further information can be found in Working with vCard contacts.
object
PropertyChange
– [Added in TB 83]
A dictionary of changed properties. Keys are the property name that changed, values are an object containing oldValue and newValue. Values can be either a string or null.
object
QueryInfo
– [Added in TB 108]
Object defining a query for quickSearch([parentId], queryInfo).
object
includeLocal
Whether to include results from local address books. Defaults to true.
includeReadOnly
Whether to include results from read-only address books. Defaults to true.
includeReadWrite
Whether to include results from read-write address books. Defaults to true.
includeRemote
Whether to include results from remote address books. Defaults to true.
searchString
One or more space-separated terms to search for in predefined contact fields (defined by the preference mail.addr_book.quicksearchquery.format).