Google and Microsoft Contacts with Ruby
Learn how to manage Google and Microsoft contacts with the Nylas Ruby SDK. Build your contacts book integration in 15 minutes.
Create Your Free Developer Account
Ready to build your email integration? Create your Nylas developer account to get started.
Ruby is ranked among the top ten programming languages in terms of growth and popularity worldwide. The Nylas Contacts API makes it very easy to create and modify contacts for your user’s Google and Microsoft accounts.
This guide explains how to use the Nylas Ruby SDK and Contacts API to create Google and Microsoft (Exchange, Outlook, Office365) contacts and modify their attributes. It covers the following steps:
- Set up your Nylas developer account and get your API keys
- Install the Nylas Ruby SDK
- Manage Google & Microsoft contacts
- Explore the Nylas Contacts API
Prerequisites
Before you can start using the Nylas Python SDK, make sure you have done the following:
-
Sign up for your developer account.
-
Get your Nylas keys:
CLIENT_ID
- The CLIENT ID found on the dashboard page for your Nylas App.CLIENT_SECRET
- The CLIENT SECRET found on the dashboard page for your Nylas App.ACCESS_TOKEN
- The access token provided when you authenticate an account to your Nylas App.
-
Ensure that gem installed on your development environment.
Install the Nylas Ruby SDK
Run either gem install nylas
in your terminal.
Congratulations!
You’re now ready to write code with the Nylas Ruby SDK.
Configure the API Client
At its core, the Nylas Communication Platform is an API client that interfaces with all major email providers. You'll first need to require
the nylas
package. Create a new instance of this class and pass in the variables you gathered when you received your developer API keys. In the example shown below, replace CLIENT_ID
, CLIENT_SECRET
, and ACCESS_TOKEN
with your values.
nylas = Nylas::API.new(
app_id: "CLIENT_ID",
app_secret: "CLIENT_SECRET",
access_token: "ACCESS_TOKEN"
)
Be Careful with Secrets
Make sure to follow best practices when including authentication secrets like this in your code. Increase security by storing these values as environment variables and accessing them with the dotenv
gem.
List Contacts
The next example demonstrates how to display the first and last name, email address, and ID for the first 10 contacts returned from an account. The first step is to get a list of contact objects. The following example uses the nylas
object to return the first 10 contacts from the user account.
contacts = nylas.contacts.limit(10)
Next, we’ll iterate through the list of contact objects and return their first and last name, the first email address stored for the contact, and the contact id
, which can be used to make modifications to the contact.
contacts.each{|contact|
puts "Name: #{contact.given_name} #{contact.surname} | Email: #{contact.emails[0].email} | ID: #{contact.id}"
}
This example uses contact.given_name
and contact.surname
to construct the contact’s full name. Take a look at the API reference for the contacts endpoint to learn more about the attributes the contact object contains.
Here is the entire code example to list contacts for a user account.
#!/usr/bin/env ruby
require 'dotenv/load'
require 'nylas'
nylas = Nylas::API.new(
app_id: ENV["CLIENT_ID"],
app_secret: ENV["CLIENT_SECRET"],
access_token: ENV["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}"
}
Create a Contact
To create a contact, use nylas
to create a new contact object:
contact = nylas.contacts.create
Now it’s time to define some attributes for this new 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"]
There is quite a bit happening here, so let’s break it all down.
contact.given_name
,contact.middle_name
, andcontact.surname
define the first, middle, and last name for the contact.contact.emails
adds an email address to the contact and sets the type towork
. You can also specifypersonal
as a type.- Similarly,
contact.phone_numbers
attaches a phone number to the contact using the typebusiness
; Google and Microsoft label this as the contact’s work phone number. This label must be one ofbusiness
,organization_main
,mobile
,assistant
,business_fax
,home_fax
,radio
,car
,home
, orpager
. - Finally,
contact.web_pages
connects a website URL to the contact with the labelhomepage
. This label must be one ofhomepage
,profile
,work
, orblog
.
Take a look a the API reference for the contact creation endpoint to learn more about the attributes you can assign to a contact object.
The very last thing you need to do is call .save()
on the contact object. This saves the contact to Nylas, which then syncs the new contact to the third party provider.
contact.save
Once the contact has been saved and synced to Google, you should see a contact that looks something like this:
Here is an example of the same contact in Microsoft Outlook.
Here is the full example for creating a contact.
#!/usr/bin/env ruby
require 'dotenv/load'
require 'nylas'
nylas = Nylas::API.new(
app_id: ENV["CLIENT_ID"],
app_secret: ENV["CLIENT_SECRET"],
access_token: ENV["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
Delete a Contact
To delete a contact, you need to get the id
of the contact and pass it as an argument to the contacts.find().destroy
function. In the following example, replace CONTACT_ID
with the ID of the contact you want to delete.
You're about to delete a contact!
The next commands will delete the specified! Make sure you want to do this before proceeding.
nylas.contacts.find('{CONTACT_ID}').destroy
Here is the entire code example to delete a contact.
#!/usr/bin/env ruby
require 'dotenv/load'
require 'nylas'
nylas = Nylas::API.new(
app_id: ENV["CLIENT_ID"],
app_secret: ENV["CLIENT_SECRET"],
access_token: ENV["ACCESS_TOKEN"]
)
# WARNING: before running this script,
# ensure you want to delete the contact with this designated ID
nylas.contacts.find('{CONTACT_ID}').destroy
Explore the Nylas Contacts API
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 is plenty more that you can do with it: take a look at the following resources to learn more about the Nylas Communications Platform capabilities.
- Learn about some of the more important features of the Nylas Contacts API.
- Take a look at additional code examples for the Ruby SDK to see what else you can do with email, calendars, and contacts.
- Follow our tutorials to learn about other aspects of the Nylas Email, Calendar, and Contacts APIs.
- Read about how the Nylas Communications Platform works.
- Review The Basics to learn about what it takes to integrate the Nylas Contacts API into your app.
- Read the blog post Working with the Nylas Contacts API and Ruby.