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

1. Sign up for a free Nylas account.

2. Follow the getting started guide to provision an application and create your API key.

3. 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:

• Email
• Calendar
• Scheduler
• Notetaker
• Agent Accounts
• Notifications & webhooks

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.messages.find(identifier: "GRANT_ID", message_id: "MESSAGE_ID")
rescue Nylas::NylasApiError => e
  warn "Nylas API error #{e.status_code} (#{e.type}): #{e.message}"
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.