Google Apps Script

Class ContactsApp

This class allows users to access their own Google Contacts and create, remove, and update contacts listed therein.

Properties

PropertyTypeDescription
ExtendedFieldExtendedField
FieldField
GenderGender
MonthMonth
PriorityPriority
SensitivitySensitivity

Methods

MethodReturn typeBrief description
createContact(givenName, familyName, email)ContactCreates a new contact.
createContactGroup(name)ContactGroupCreates a contact group with the given name
deleteContact(contact)voidDeletes the contact.
deleteContactGroup(group)voidDeletes the contact group
getContact(emailAddress)ContactGets a contact by the email address.
getContactById(id)ContactGets the contact with this id.
getContactGroup(name)ContactGroupGets a contact group with the given name, or returns null if no such contact group is found.
getContactGroupById(id)ContactGroupGets a contact group with the given id, or returns null if no such contact group is found.
getContactGroups()ContactGroup[]Gets the complete list of the user's contact groups.
getContacts()Contact[]Gets all of the user's contacts.
getContactsByAddress(query)Contact[]Get contacts matching an address.
getContactsByAddress(query, label)Contact[]Get contacts matching an address, limited to a specific field.
getContactsByAddress(query, label)Contact[]Get contacts matching an address, limited to the specified custom address label.
getContactsByCompany(query)Contact[]Get contacts matching the company field.
getContactsByCustomField(query, label)Contact[]Get contacts matching a given value in a custom field.
getContactsByDate(month, day, label)Contact[]Get contacts matching a given month and day for a particular standard field.
getContactsByDate(month, day, year, label)Contact[]Get contacts matching a given month, day, and year for a particular standard field.
getContactsByDate(month, day, year, label)Contact[]Get contacts matching a given month, day, and year for a particular custom field.
getContactsByDate(month, day, label)Contact[]Get contacts matching a given month and day for a particular custom field.
getContactsByEmailAddress(query)Contact[]Get contacts matching an email address.
getContactsByEmailAddress(query, label)Contact[]Get contacts matching an email address, limited to a specific field.
getContactsByEmailAddress(query, label)Contact[]Get contacts matching an email address, limited to the specified custom email address label.
getContactsByGroup(group)Contact[]Get the contacts in a given ContactGroup.
getContactsByIM(query)Contact[]Get contacts matching an instant messaging address.
getContactsByIM(query, label)Contact[]Get contacts matching an instant messaging address, limited to a specific field.
getContactsByIM(query, label)Contact[]Get contacts matching an instant messaging address, limited to the specified custom instant messaging label.
getContactsByJobTitle(query)Contact[]Get contacts matching the job title field.
getContactsByName(query)Contact[]Get contacts matching a name.
getContactsByName(query, label)Contact[]Get contacts matching a name, limited to a specific field.
getContactsByNotes(query)Contact[]Get contacts matching the notes field.
getContactsByPhone(query)Contact[]Get contacts matching a phone number.
getContactsByPhone(query, label)Contact[]Get contacts matching a phone number, limited to a specific field.
getContactsByPhone(query, label)Contact[]Get contacts matching a phone number, limited to the specified custom phone number label.
getContactsByUrl(query)Contact[]Get contacts matching a URL.
getContactsByUrl(query, label)Contact[]Get contacts matching a URL, limited to a specific field.
getContactsByUrl(query, label)Contact[]Get contacts matching a URL, limited to the specified custom URL label.

Detailed documentation

createContact(givenName, familyName, email)

Creates a new contact.

 
// The code below creates a new contact with the name "John Doe" and the email address
 // "john.doe@example.com".
 var contact = ContactsApp.createContact('John', 'Doe', 'john.doe@example.com');
 

Parameters

NameTypeDescription
givenNameStringthe first name of the contact
familyNameStringthe last name of the contact
emailStringthe email address of the contact

Return

Contact — the newly created Contact object

See also


createContactGroup(name)

Creates a contact group with the given name

 
// The code below creates a new contact group named "Work Friends"
 var group = ContactsApp.createContactGroup("Work Friends");
 

Parameters

NameTypeDescription
nameStringthe name of the new contact group

Return

ContactGroup — the newly created contact group

See also


deleteContact(contact)

Deletes the contact.

 
// The code below retrieves a contact with the email address "john.doe@example.com"
 // and then deletes that contact.
 var contact = ContactsApp.getContact('john.doe@example.com');
 ContactsApp.deleteContact(contact);
 

Parameters

NameTypeDescription
contactContactthe contact to be deleted

See also


deleteContactGroup(group)

Deletes the contact group

 
// The code below creates deletes the contact group named "Work Friends"
 var group = ContactsApp.getContactGroup("Work Friends");
 ContactsApp.deleteContactGroup(group);
 

Parameters

NameTypeDescription
groupContactGroupthe contact group to delete

See also


getContact(emailAddress)

Gets a contact by the email address. If multiple contacts share the same email address, the method favors those contacts who have marked the email address as primary; if none of the contacts had the email address marked as primary or multiple contacts had the email address marked as primary, then it returns the first result in the sorted contacts order.

 
// The code below retrieves a contact with the email address "john.doe@example.com".
 var contact = ContactsApp.getContact('john.doe@example.com');
 

Parameters

NameTypeDescription
emailAddressStringthe email address of the contact

Return

Contact — the contact containing that email address

See also


getContactById(id)

Gets the contact with this id.

 
// The code below retrieves the contact with the id
 // "http://www.google.com/m8/feeds/contacts/john.doe%40example.com/base/7c86afde08d34ca5"
 var id = 'http://www.google.com/m8/feeds/contacts/john.doe%40example.com/base/7c86afde08d34c';
 var contact = ContactApp.getContactById(id);
 

Parameters

NameTypeDescription
idStringthe id of the contact to retrieve

Return

Contact — the matching contact or null

See also


getContactGroup(name)

Gets a contact group with the given name, or returns null if no such contact group is found.

 
// The code below returns the contact group with the name "Work Friends"
 var group  = ContactsApp.getContactGroup('Work Friends');
 

Parameters

NameTypeDescription
nameStringthe name of the contact group to match

Return

ContactGroup — the matching contact group or null if no matching contact group is found

See also


getContactGroupById(id)

Gets a contact group with the given id, or returns null if no such contact group is found.

 
// The code below returns the contact group with the id
 // "http://www.google.com/m8/feeds/groups/john.doe%40example.com/base/54eefbb093fdecb"
 var id = "http://www.google.com/m8/feeds/groups/john.doe%40example.com/base/54eefbb093fdecb";
 var group  = ContactsApp.getContactGroupById(id);
 

Parameters

NameTypeDescription
idStringthe id of the contact group to match

Return

ContactGroup — the matching contact group or null if no matching contact group is found

See also


getContactGroups()

Gets the complete list of the user's contact groups. A user can have a list of Contacts, and potentially a list of Contact Groups also. Each Contact Group can contain Contacts. This method returns a list of all the Contact Groups.

 
// The retrieves all the contract groups for the user and then logs the group name of each
 // contact group.
 var groups  = ContactsApp.getContactGroups();
 for (var i = 0; i < groups.length; i++) {
   Logger.log(groups[i].getName());
 }
 

Return

ContactGroup[] — an array of the user's contact groups

See also


getContacts()

Gets all of the user's contacts.

 
// The code below will retrieve all the user's contacts
 var contacts = ContactsApp.getContacts();
 

Return

Contact[] — an array of all the user's contacts

See also


getContactsByAddress(query)

Get contacts matching an address.

 
// The code below returns an array of contacts where the contact's address contains
 // "San Francisco'.
 var contacts = ContactsApp.getContactsByAddress('San Francisco');
 

Parameters

NameTypeDescription
queryStringthe string to search for in contact's addresses

Return

Contact[] — an array of matching contacts

See also


getContactsByAddress(query, label)

Get contacts matching an address, limited to a specific field.

 
// The code below returns an array of contacts where the contact's address contains
 // "San Francisco" in the Home address field.
 var contacts = ContactsApp.getContactsByAddress('San Francisco',
                                                 ContactsApp.Field.HOME_ADDRESS);
 

Parameters

NameTypeDescription
queryStringthe string to search for in contact's addresses
labelFieldthe field to search within

Return

Contact[] — an array of matching contacts

See also


getContactsByAddress(query, label)

Get contacts matching an address, limited to the specified custom address label.

 
// The code below returns an array of contacts where the contact's address contains
 // "San Francisco" in a custom address label (created by the user) called
 // "vacation".
 var contacts = ContactsApp.getContactsByAddress('San Francisco', 'vacation');
 

Parameters

NameTypeDescription
queryStringthe string to search for in contact's addresses with the specified custom address label
labelStringthe custom address label to search within

Return

Contact[] — an array of matching contacts

See also


getContactsByCompany(query)

Get contacts matching the company field.

 
// The code below returns an array of contacts where the contact's company field
 // contains "Google".
 var contacts = ContactsApp.getContactsByCompany('Google');
 

Parameters

NameTypeDescription
queryStringthe string to search for in contact's company field

Return

Contact[] — an array of matching contacts

See also


getContactsByCustomField(query, label)

Get contacts matching a given value in a custom field. The custom field can be specified by a String or as one of the ContactsApp.ExtendedField values.

 
// The code below returns an array of contacts where the contact's custom field
 // named "Favorite Sport" contains "tennis".
 var contacts = ContactsApp.getContactsByCustomField('tennis', 'Favorite Sport');
 

Parameters

NameTypeDescription
queryObjectthe string to search for in contact's custom field
labelExtendedFieldthe custom field to search within

Return

Contact[] — an array of matching contacts

See also


getContactsByDate(month, day, label)

Get contacts matching a given month and day for a particular standard field.

 
// The code below returns an array of contacts where the contact's "Birthday" field
 // contains April for the month and 19 for the day.
 var contacts = ContactsApp.getContactsByDate(ContactsApp.Month.APRIL, 19,
                                               ContactsApp.Field.BIRTHDAY);
 

Parameters

NameTypeDescription
monthMonththe month to match, as one of the values from ContactsApp.Month
dayIntegerthe day to match
labelFieldthe field to search within, from ContactsApp.Field

Return

Contact[] — an array of matching contacts

See also


getContactsByDate(month, day, year, label)

Get contacts matching a given month, day, and year for a particular standard field.

 
// The code below returns an array of contacts where the contact's "Birthday" field
 // contains April for the month, 19 for the day, and 1950 for the year.
 var contacts = ContactsApp.getContactsByDate(ContactsApp.Month.APRIL, 19, 1950,
                                              ContactsApp.Field.BIRTHDAY);
 

Parameters

NameTypeDescription
monthMonththe month to match, as one of the values from ContactsApp.Month
dayIntegerthe day to match
yearIntegerthe year to match, can be null
labelFieldthe field to search within, from ContactsApp.Field

Return

Contact[] — an array of matching contacts

See also


getContactsByDate(month, day, year, label)

Get contacts matching a given month, day, and year for a particular custom field.

 
// The code below returns an array of contacts where the contact's custom "Start Date" field
 // contains April for the month, 19 for the day, and 2011 for the year.
 var contacts = ContactsApp.getContactsByDate(ContactsApp.Month.APRIL, 19, 2011, 'Start Date');
 

Parameters

NameTypeDescription
monthMonththe month to match, as one of the values from ContactsApp.Month
dayIntegerthe day to match
yearIntegerthe year to match, can be null
labelStringthe custom field to search within

Return

Contact[] — an array of matching contacts

See also


getContactsByDate(month, day, label)

Get contacts matching a given month and day for a particular custom field.

 
// The code below returns an array of contacts where the contact's custom "Start Date" field
 // contains April for the month and 19 for the day.
 var contacts = ContactsApp.getContactsByDate(ContactsApp.Month.APRIL, 19, 'Start Date');
 

Parameters

NameTypeDescription
monthMonththe month to match, as one of the values from ContactsApp.Month
dayIntegerthe day to match
labelStringthe custom field to search within

Return

Contact[] — an array of matching contacts

See also


getContactsByEmailAddress(query)

Get contacts matching an email address.

 
// The code below returns an array of contacts where the contact's email address contains
 // "john.doe@example.com'.
 var contacts = ContactsApp.getContactsByEmailAddress('john.doe@example.com');
 

Parameters

NameTypeDescription
queryStringthe string to search for in contact email addresses

Return

Contact[] — an array of matching contacts

See also


getContactsByEmailAddress(query, label)

Get contacts matching an email address, limited to a specific field.

 
// The code below returns an array of contacts where the contact's email address contains
 // "john.doe@example.com" in the Home email field.
 var contacts = ContactsApp.getContactsByEmailAddress('john.doe@example.com',
                                                      ContactsApp.Field.HOME_EMAIL);
 

Parameters

NameTypeDescription
queryStringthe string to search for in contact email addresses
labelFieldthe field to search within

Return

Contact[] — an array of matching contacts

See also


getContactsByEmailAddress(query, label)

Get contacts matching an email address, limited to the specified custom email address label.

 
// The code below returns an array of contacts where the contact's email address contains
 // "john.doe@example.com" in a custom email address label (created by the user) called
 // "alternate".
 var contacts = ContactsApp.getContactsByEmailAddress('john.doe@example.com', 'alternate');
 

Parameters

NameTypeDescription
queryStringthe string to search for in contact email addresses with the specified custom email address label
labelStringthe custom email address label to search within

Return

Contact[] — an array of matching contacts

See also


getContactsByGroup(group)

Get the contacts in a given ContactGroup.

 
// The code below returns an array of contacts in the ContactGroup with the name
 // "Work Friends".
 var group  = ContactsApp.getContactGroup('Work Friends');
 var contacts = ContactsApp.getContactsByGroup(group);
 

Parameters

NameTypeDescription
groupContactGroupthe group of contacts

Return

Contact[] — an array of of contacts in the given group

See also


getContactsByIM(query)

Get contacts matching an instant messaging address.

 
// The code below returns an array of contacts where the contact's instant messaging address
 // contains "ChatWithJohnDoe" in any instant messaging field.
 var contacts = ContactsApp.getContactsByIM('ChatWithJohnDoe');
 

Parameters

NameTypeDescription
queryStringthe string to search for in contact's instant messaging addresses

Return

Contact[] — an array of matching contacts

See also


getContactsByIM(query, label)

Get contacts matching an instant messaging address, limited to a specific field.

 
// The code below returns an array of contacts where the contact's instant messaging address
 // contains "ChatWithJohnDoe" in the AIM instant messaging field.
 var contacts = ContactsApp.getContactsByIM('ChatWithJohnDoe',
                                             ContactsApp.Field.AIM);
 

Parameters

NameTypeDescription
queryStringthe string to search for in contact's instant messaging addresses
labelFieldthe field to search within

Return

Contact[] — an array of matching contacts

See also


getContactsByIM(query, label)

Get contacts matching an instant messaging address, limited to the specified custom instant messaging label.

 
// The code below returns an array of contacts where the contact's instant messaging address
 // contains "ChatWithJohnDoe" in a custom instant messaging label (created by the user) called
 // "eBuddy".
 var contacts = ContactsApp.getContactsByIM('ChatWithJohnDoe', 'eBuddy');
 

Parameters

NameTypeDescription
queryStringthe string to search for in contact's instant messaging addresses with the specified custom instant messaging label
labelStringthe custom instant messaging label to search within

Return

Contact[] — an array of matching contacts

See also


getContactsByJobTitle(query)

Get contacts matching the job title field.

 
// The code below returns an array of contacts where the contact's job title field
 // contains "Product Manager".
 var contacts = ContactsApp.getContactsByJobTitle('Product Manager');
 

Parameters

NameTypeDescription
queryStringthe string to search for in contact's job title field

Return

Contact[] — an array of matching contacts

See also


getContactsByName(query)

Get contacts matching a name.

 
// The code below returns an array of contacts where the contact name contains "John"
 var contacts = ContactsApp.getContactsByName('John');
 

Parameters

NameTypeDescription
queryStringthe string to search for in contact names

Return

Contact[] — an array of matching contacts

See also


getContactsByName(query, label)

Get contacts matching a name, limited to a specific field.

 
// The code below returns an array of contacts where the contact name contains "John"
 // in the Given Name field.
 var contacts = ContactsApp.getContactsByName('John', ContactsApp.Field.GIVEN_NAME);
 

Parameters

NameTypeDescription
queryStringthe string to search for in contact names
labelFieldthe field to search within

Return

Contact[] — an array of matching contacts

See also


getContactsByNotes(query)

Get contacts matching the notes field.

 
// The code below returns an array of contacts where the contact's notes field
 // contains "sent birthday card".
 var contacts = ContactsApp.getContactsByNotes('sent birthday card');
 

Parameters

NameTypeDescription
queryStringthe string to search for in contact's notes field

Return

Contact[] — an array of matching contacts

See also


getContactsByPhone(query)

Get contacts matching a phone number. This method will expand out lettered phone numbers, so if you search for '212-555-CODE' and you have '212-555-2633' in your contacts or vice versa, the method will find the appropriate contact.

 
// The code below returns an array of contacts where the contact's phone number contains
 // "212-555-1234' in any phone number field.
 var contacts = ContactsApp.getContactsByPhone('212-555-1234');
 

Parameters

NameTypeDescription
queryStringthe string to search for in contact's phone numbers

Return

Contact[] — an array of matching contacts

See also


getContactsByPhone(query, label)

Get contacts matching a phone number, limited to a specific field. This method will expand out lettered phone numbers, so if you search for '212-555-CODE' and you have '212-555-2633' in your contacts or vice versa, the method will find the appropriate contact.

 
// The code below returns an array of contacts where the contact's phone number contains
 // "212-555-1234" in the Home phone number field.
 var contacts = ContactsApp.getContactsByPhone('212-555-1234',
                                               ContactsApp.Field.HOME_PHONE);
 

Parameters

NameTypeDescription
queryStringthe string to search for in contact's phone numbers
labelFieldthe field to search within

Return

Contact[] — an array of matching contacts

See also


getContactsByPhone(query, label)

Get contacts matching a phone number, limited to the specified custom phone number label. This method will expand out lettered phone numbers, so if you search for '212-555-CODE' and you have '212-555-2633' in your contacts or vice versa, the method will find the appropriate contact.

 
// The code below returns an array of contacts where the contact's phone number contains
 // "212-555-1234" in a custom phone number label (created by the user) called
 // "alternate".
 var contacts = ContactsApp.getContactsByPhone('212-555-1234', 'alternate');
 

Parameters

NameTypeDescription
queryStringthe string to search for in contact's phone numbers with the specified custom phone number label
labelStringthe custom phone number label to search within

Return

Contact[] — an array of matching contacts

See also


getContactsByUrl(query)

Get contacts matching a URL.

 
// The code below returns an array of contacts where the contact's URL contains
 // "www.example.com' in any URL field.
 var contacts = ContactsApp.getContactsByUrl('www.example.com');
 

Parameters

NameTypeDescription
queryStringthe string to search for in contact's URLs

Return

Contact[] — an array of matching contacts

See also


getContactsByUrl(query, label)

Get contacts matching a URL, limited to a specific field.

 
// The code below returns an array of contacts where the contact's URL contains
 // "www.example.com" in the Work URL field.
 var contacts = ContactsApp.getContactsByUrl('www.example.com',
                                             ContactsApp.Field.WORK_WEBSITE);
 

Parameters

NameTypeDescription
queryStringthe string to search for in contact's URLs
labelFieldthe field to search within

Return

Contact[] — an array of matching contacts

See also


getContactsByUrl(query, label)

Get contacts matching a URL, limited to the specified custom URL label.

 
// The code below returns an array of contacts where the contact's URL contains
 // "www.example.com" in a custom URL label (created by the user) called
 // "alternate work".
 var contacts = ContactsApp.getContactsByUrl('www.example.com', 'alternate work');
 

Parameters

NameTypeDescription
queryStringthe string to search for in contact's URLs with the specified custom URL label
labelStringthe custom URL label to search within

Return

Contact[] — an array of matching contacts

See also

Deprecated methods



Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.