Nylas Ruby SDK
The official Ruby SDK for Nylas โ the infrastructure that powers communications
๐ SDK Guide ยท ๐ API Reference ยท ๐ Sign up ยท ๐ก Samples ยท ๐ฌ Forum
The official Ruby SDK for Nylas โ the infrastructure that powers communications. Integrate with Gmail, Microsoft, IMAP, Zoom, and 250+ email, calendar, and meeting providers in 5 minutes. Covers Email, Calendar, Contacts, Scheduler, Notetaker, and Agent Accounts.
This repository is for contributors and anyone installing the SDK from source. If you just want to use the SDK in your app, head straight to the Ruby SDK guide on developer.nylas.com.
Get started
-
Follow the getting started guide to provision an application and create your API key.
-
Bootstrap a project with the Nylas CLI:
brew install nylas/nylas-cli/nylas nylas init
โ๏ธ Install
Requirements: Ruby 3.0 or later.
Add the gem to your Gemfile:
gem "nylas"
Then install:
bundle install
Or install it directly:
gem install nylas
Build from source
git clone https://github.com/nylas/nylas-ruby.git
cd nylas-ruby
bundle install
Run the test suite with rspec spec.
โก๏ธ Usage
Initialize the client with your API key:
require "nylas"
nylas = Nylas::Client.new(
api_key: "NYLAS_API_KEY"
)
Then make a request โ for example, list a grant's calendars:
calendars, request_id, next_cursor = nylas.calendars.list(identifier: "GRANT_ID")
Every SDK call returns a tuple. List endpoints return [data, request_id, next_cursor, headers]; single-record endpoints return [data, request_id]. Destructure the elements you need and ignore the rest with _. Use next_cursor to paginate:
cursor = nil
loop do
page, _request_id, cursor = nylas.calendars.list(
identifier: "GRANT_ID",
query_params: { page_token: cursor }
)
page.each { |calendar| puts calendar[:name] }
break unless cursor
end
For step-by-step walkthroughs, see the developer guides:
Batch event operations
For Google and Microsoft calendars, create, update, and delete events in one call. The
body hashes use the same fields as events.create and events.update. Query parameters
apply to every operation: calendar_id is required; notify_participants, grant_email,
tentative_as_busy, and select (a comma-separated field list) are optional. Omitting
notify_participants preserves the server default of true; Microsoft rejects false.
operations = [
{ method: "create", body: { title: "Standup", when: { start_time: 1798794000, end_time: 1798795800 } } },
{ method: "update", event_id: "EVENT_ID_1", body: { title: "Renamed" } },
{ method: "delete", event_id: "EVENT_ID_2" }
]
query_params = { calendar_id: "primary" }
results, request_id, headers = nylas.events.batch(
identifier: "GRANT_ID",
query_params: query_params,
request_body: { operations: operations }
)
results.each_with_index do |item, index|
puts "Operation #{index}: #{item[:status]}"
# Successful creates/updates have an event in item[:data]; deletes have no data.
next unless item[:error]
# Never retry these operations: the provider already created the event.
next if item[:provider_event_created]
next unless [429, 503].include?(item[:status])
delay = item[:retry_after]
next unless delay.is_a?(Numeric) && delay.finite? && delay >= 0
# This example retries an eligible operation once, after the provider's delay.
# The SDK leaves retry decisions to your application; inspect this result too.
sleep(delay)
retry_results, _retry_request_id = nylas.events.batch(
identifier: "GRANT_ID",
query_params: query_params,
request_body: { operations: [operations[index]] }
)
puts "Retry status: #{retry_results.first[:status]}"
end
The return tuple is [results, request_id, headers], without a pagination cursor.
Results preserve operation order and use symbol keys. HTTP 207 returns normally, even
if all operations failed: check each item's status and error. Errors contain type,
message, and optional provider_error; retry metadata is available as retry_after
(seconds, including zero) and provider_event_created. Invalid whole requests raise
the usual Nylas::NylasApiError. The API validates batch sizes and operations.
Error handling
The SDK raises typed errors you can rescue. API failures raise Nylas::NylasApiError (with type, status_code, request_id, provider_error, headers); OAuth failures raise Nylas::NylasOAuthError; request timeouts raise Nylas::NylasSdkTimeoutError.
begin
nylas..find(identifier: "GRANT_ID", message_id: "MESSAGE_ID")
rescue Nylas::NylasApiError => e
warn "Nylas API error #{e.status_code} (#{e.type}): #{e.}"
rescue Nylas::NylasSdkTimeoutError => e
warn "Request to #{e.url} timed out after #{e.timeout}s"
end
๐ก Examples
- Local examples live in
examples/(messages, events, folders, notetaker). - The Nylas Samples org has end-to-end Ruby apps you can clone and run.
๐ค AI agents
nylas/skills drops Nylas into Claude Code, Cursor, Codex, and other agents that support the skills format:
npx skills add nylas/skills
/plugin marketplace add nylas/skills # Claude Code
The CLI also installs an MCP server for Claude Desktop, Claude Code, Cursor, Windsurf, or VS Code:
brew install nylas/nylas-cli/nylas
nylas mcp install
Walkthrough: give AI agents email access via MCP.
๐ Reference
- Ruby SDK guide
- API reference
- Getting started
- Email ยท Calendar ยท Scheduler ยท Notetaker ยท Agent Accounts ยท Notifications
- Data residency
- Nylas CLI
- Forum
โจ Upgrading
See CHANGELOG.md for release notes, and UPGRADE.md for the 5.x โ 6.x migration guide. The 6.x line targets Nylas API v3; if you're still on v2.7 or earlier, stay on the 5.x SDK.
๐ Contributing
Bug reports, questions, and pull requests are welcome. See Contributing.md for the workflow, and the Nylas Forum for broader discussion.
๐ Security
To report a security vulnerability, follow the Nylas Vulnerability Disclosure Policy. Please don't open a public GitHub issue for security reports.
๐ Other Nylas SDKs
- nylas-nodejs
- nylas-python
- nylas-java (Java & Kotlin)
๐ License
MIT โ see LICENSE.txt.