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 Contacts API makes it simple to create and modify contacts for your users' Google and Microsoft accounts.

This page discusses how to manage Google and Microsoft contacts with the Nylas Ruby SDK and Contacts API. A Contact can include basic information (for example, names and email addresses) and extended information (for example, notes and websites).

What you'll learn

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

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

Prerequisites

Before you start this tutorial, you must install the Nylas Ruby SDK and set up your environment. See Get started with the Nylas Ruby SDK for more information.

Step 1: Initialize the `API` object

All of the functionality of the Nylas 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, see Get started with the Nylas Ruby SDK.

Step 2: (Optional) Change the base API URL

You can choose to 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 the API_URL parameter 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
)

If you're using the Nylas EU region: The base API URL defaults to the US region, but you can specify api_server: 'https://ireland.api.nylas.com' to use the EU region. See Data Residency for more information.

Step 3: Read contacts

To read contacts from an account, use the nylas object. Here, we'll read the first and last names, email addresses, and IDs of the first ten contacts in the account:

Fetch the first ten contacts from the account:
```
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}"
}   
```

Learn More

For information on available attributes, see the GET /contacts documentation.

When put together, the code looks like this:

#!/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

Now, we'll create a contact and assign its attributes. Then, we'll save the contact to the user's account:

Use the nylas object to create a contact:
```
contact = nylas.contacts.create   
```
Assign attributes to the contact:
```
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"]   
```
- The contact.given_name, contact.middle_name, and contact.surname parameters define the contact's first, middle, and last name, respectively.
- contact.emails adds an email address to the contact and sets its type (work, personal, or other).
- contact.notes adds a note to the contact.
- contact.phone_numbers adds a phone number to the contact and sets its type (business, home, mobile, page, business_fax, home_fax, organization_main, assistant, radio, or other). Google and Microsoft label any business-type phone numbers as the contact’s work phone number.
- The webPages parameter associates a website URL with the contact and sets its type (homepage, profile, work, or blog).
Learn More
For information on available attributes, see the POST /contacts documentation.
Call contact.save to save it to Nylas. Nylas syncs the contact to the end user's service provider.

Example: Create and save a contact

This 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 '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 'homepage', 'profile', 'work', or 'blog'
contact.web_pages = [{type: 'homepage', url: 'https://nylas.com'}]

contact.save
puts contact.to_json

When you create the contact for a Google account, it looks like this:

Google contact example

For Microsoft Outlook, the new contact looks like this:

Microsoft contact example

Step 5: Delete a contact

To delete a contact from an account, you must get the contact's id and pass it as an argument to the contacts.find().destroy function. You can use the same endpoint that you used in Step 3 to retrieve the contact ID.

Example: Delete a contact

This example deletes a specific contact from your service provider. 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 these 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 platform works.
Read our Working with the Nylas Contacts API and Ruby SDK blog post.

Manage contacts with the Nylas Ruby SDK

What you'll learn

Prerequisites

Step 1: Initialize the API object

Step 2: (Optional) Change the base API URL

Step 3: Read contacts

Step 4: Create and save contacts

Example: Create and save a contact

Step 5: Delete a contact

Example: Delete a contact

More resources

Step 1: Initialize the `API` object