Manage contacts with the Nylas Ruby SDK

The Nylas Ruby SDK is the quickest way to integrate Google and Microsoft (Exchange, Outlook, Office365) contacts into your app with Ruby and the Nylas Contacts API. The Nylas Contacts API makes it very easy to create and modify contacts for your users' Google and Microsoft accounts.

Learn how to manage Google and Microsoft contacts with the Nylas Ruby SDK and Contacts API. A contact can include basic information, such as names and email addresses, and extended information, such as notes and websites.

What you'll learn

In this tutorial, you'll learn how to do the following:

Read contacts from an account's contact list.
Create and save Google and Microsoft contacts.
Delete contacts.

Prerequisites

Prerequisites include installing the Nylas Ruby SDK and setting up your environment. Before you start this tutorial, make sure that you complete the Getting started with the Nylas Ruby SDK tutorial.

Step 1: Initialize the Nylas object

At its core, the Nylas Communication Platform is an API client that interfaces with all major contact providers.

All of the functionality of the Nylas Communications Platform is available through the API object. Before you make requests, initialize the API object with your client ID, client secret, and access token.

#!/usr/bin/env ruby
CLIENT_ID = 'your_nylas_client_id'
CLIENT_SECRET = 'your_nylas_client_secret'
ACCESS_TOKEN = 'your_account_access_token'
require 'nylas'

nylas = Nylas::API.new(
    app_id: CLIENT_ID,
    app_secret: CLIENT_SECRET,
    access_token: ACCESS_TOKEN
)

For more information on initializing the API object, refer to the Getting started with the Nylas Ruby SDK tutorial.

Step 2: Change the base API URL

You can optionally change the base API URL depending on your location:

Location	API URL	Scheduler API URL
United States (Oregon)	`https://api.nylas.com`	`https://api.schedule.nylas.com`
Europe (Ireland)	`https://ireland.api.nylas.com`	`https://ireland.api.schedule.nylas.com`

For more information, see Data residency and Migration guide for data centers.

Pass API_URL to change the base API URL.

#!/usr/bin/env ruby
CLIENT_ID = 'your_nylas_client_id'
CLIENT_SECRET = 'your_nylas_client_secret'
ACCESS_TOKEN = 'your_account_access_token'
API_URL='your_base_api_url'
require 'nylas'

nylas = Nylas::API.new(
    app_id: CLIENT_ID,
    app_secret: CLIENT_SECRET,
    access_token: ACCESS_TOKEN,
    api_server: API_URL
)

Step 3: Read contacts

Use the nylas object to read contacts from an account.

In this tutorial, we'll read the first and last name, email address, and ID for the first ten contacts.

Read the first ten contacts.
```
contacts = nylas.contacts.limit(10)   
```
Use the each method to log the first name (contact.given_name), last name (contact.surname), first email address (contact.emails[0].email), and ID (contact.id) for each contact.
```
contacts.each{|contact|
  puts "Name: #{contact.given_name} #{contact.surname} | Email: #{contact.emails[0].email} | ID: #{contact.id}"
}   
```
For information on available attributes, see GET /contacts

Example: Read contacts

#!/usr/bin/env ruby
CLIENT_ID = 'your_nylas_client_id'
CLIENT_SECRET = 'your_nylas_client_secret'
ACCESS_TOKEN = 'your_account_access_token'
require 'nylas'

nylas = Nylas::API.new(
    app_id: CLIENT_ID,
    app_secret: CLIENT_SECRET,
    access_token: ACCESS_TOKEN
)

contacts = nylas.contacts.limit(10)
contacts.each{|contact|
  puts "Name: #{contact.given_name} #{contact.surname} | Email: #{contact.emails[0].email} | ID: #{contact.id}"
}

Step 4: Create and save contacts

Create a new contact and assign contact attributes.

Create contacts

Use nylas to create a new contact object.
```
contact = nylas.contacts.create   
```
Assign attributes.
```
contact.given_name = "My"
contact.middle_name = "Nylas"
contact.surname = "Friend"
contact.emails['work'] = ['[email protected]']
contact.notes = "Make sure to keep in touch!"
contact.phone_numbers['business'] = ['(555) 555-5555']
contact.web_pages['homepage'] = ["https://nylas.com"]   
```
- contact.given_name, contact.middle_name, and contact.surname define the contact's first, middle, and last name.
- contact.emails adds an email address to the contact and sets type to work. Supported type values are work,, personal, and other.
- contact.notes adds a note to the contact.
- contact.phone_numbers adds a phone number to the contact and sets type as business. Google and Microsoft label the phone number with the business type as the contact’s work phone number. Supported type values are business, home, mobile, page, business_fax, home_fax,organization_main, assistant, radio and other.
- webPages connects a website URL to the contact and sets type to homepage. Supported type values are homepage, profile, work, and blog.
For information on available attributes, see POST /contacts.

Save contacts

Call contact.save on the contact object to save the contact to Nylas. Nylas syncs the new contact to the end user's service provider.

contact.save

Example: Create and save contacts

The following example creates and saves a contact called "My Nylas Friend":

#!/usr/bin/env ruby
CLIENT_ID = 'your_nylas_client_id'
CLIENT_SECRET = 'your_nylas_client_secret'
ACCESS_TOKEN = 'your_account_access_token'
require 'nylas'

nylas = Nylas::API.new(
    app_id: CLIENT_ID,
    app_secret: CLIENT_SECRET,
    access_token: ACCESS_TOKEN
)

contact = nylas.contacts.create
# Add a first, middle, and last name for the contact.
contact.given_name = "My"
contact.middle_name = "Nylas"
contact.surname = "Friend"

# Email address 'type' must be either 'work' or 'personal'
contact.emails = [{type: 'work', email: '[email protected]'}]
contact.notes = "Make sure to keep in touch!"

# Phone number type must be one of 'business', 'organization_main',
# 'mobile', 'assistant', 'business_fax', 'home_fax', 'radio', 'car', 'home', or 'pager'
# Google and Microsoft label 'business' phone numbers as the contact's Work phone number
contact.phone_numbers = [{type: 'business', number: '555 555-5555'}]

# Web page type must be one of 'homepage', 'profile', 'work', or 'blog'
contact.web_pages = [{type: 'homepage', url: 'https://nylas.com'}]

contact.save
puts contact.to_json

The following is the example contact created in Google:

Google contact example

You can create the same contact in Microsoft Outlook:

Microsoft contact example

Step 5: Delete contacts

To delete a contact from Google, get the id of the contact and pass it as an argument to the contacts.find().destroy function. You can use the same endpoint you used earlier to Read contacts to retrieve the contact ID.

Example: Delete contacts

The following example deletes a specific contact from Google. Make sure that you want to do this before proceeding.

#!/usr/bin/env ruby
CLIENT_ID = 'your_nylas_client_id'
CLIENT_SECRET = 'your_nylas_client_secret'
ACCESS_TOKEN = 'your_account_access_token'
require 'nylas'

nylas = Nylas::API.new(
    app_id: CLIENT_ID,
    app_secret: CLIENT_SECRET,
    access_token: ACCESS_TOKEN
)

nylas.contacts.find('{CONTACT_ID}').destroy

More resources

If you’ve made it this far, congrats! You’ve successfully learned how to manage Google and Microsoft contacts with the Nylas Contacts API! There's plenty more that you can do with Nylas. Take a look at the following resources:

Follow our Ruby SDK tutorials.
Learn more about the Nylas API.
Learn more about the Nylas Contacts API.
Learn more about how the Nylas Communications Platform works.
Read the blog post Working with the Nylas Contacts API and Ruby SDK.