addressBooks.contacts API
The contacts API allows to access and manage the user’s contacts.
Permissions
Read and modify your address books and contacts
Transfer sensitive user data (if access has been granted) to a remote server for further processing
Functions
create(parentId, vCard)
Adds a new contact to the address book with the id parentId.
Parameters
parentId
(string)
vCard
(string)
The vCard for the new contact. If it includes an (optional) id and an existing contact has this id already, an exception is thrown.
Return type (Promise)
string
The ID of the new contact.
Required permissions
delete(id)
Removes a contact from the address book. The contact is also removed from any mailing lists it is a member of.
Parameters
id
(string)
Required permissions
get(id)
Gets a single contact.
Parameters
id
(string)
Return type (Promise)
Required permissions
getPhoto(id)
Gets the photo associated with this contact. Returns null, if no photo is available.
Parameters
id
(string)
Required permissions
list(parentId)
Gets all the contacts in the address book with the id parentId.
Parameters
parentId
(string)
Return type (Promise)
array of ContactNode
Required permissions
query(queryInfo)
Gets all contacts matching queryInfo.
Parameters
Return type (Promise)
array of ContactNode
Required permissions
setPhoto(id, file)
Sets the photo associated with this contact.
Required permissions
update(id, vCard)
Updates a contact.
Parameters
id
(string)
vCard
(string)
The updated vCard for the contact.
Required permissions
Events
onCreated
Fired when a contact is created.
Parameters for onCreated.addListener(listener)
listener(node)
A function that will be called when this event occurs.
Parameters passed to the listener function
Required permissions
onDeleted
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.
Parameters passed to the listener function
parentId
(string)
id
(string)
Required permissions
onUpdated
Fired when a contact is changed.
Parameters for onUpdated.addListener(listener)
listener(node, oldVCard)
A function that will be called when this event occurs.
Required permissions
Types
ContactNode
A node representing a contact in an address book.
object
id
(string)
The unique identifier for the node. IDs are unique within the current profile, and they remain valid even after the program is restarted.
Always set to contact.
vCard
(string)
[parentId]
(string, optional)
The id of the parent object.
[readOnly]
(boolean, optional)
Indicates if the object is read-only.
[remote]
(boolean, optional)
Indicates if the object came from a remote address book.
ContactProperties
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
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
Object defining a query for contacts.quickSearch.
object
[includeLocal]
(boolean, optional)
Whether to include results from local address books. Defaults to true.
[includeReadOnly]
(boolean, optional)
Whether to include results from read-only address books. Defaults to true.
[includeReadWrite]
(boolean, optional)
Whether to include results from read-write address books. Defaults to true.
[includeRemote]
(boolean, optional)
Whether to include results from remote address books. Defaults to true.
[parentId]
(string, optional)
The id of the address book to search. If not specified, all address books are searched.
[searchString]
(string, optional)
One or more space-separated terms to search for in predefined contact fields (defined by the preference mail.addr_book.quicksearchquery.format).