A simple Ruby gem to interact with the Zoho Mail API using OAuth2 and Curb.
Create a Zoho "Self client" app from https://api-console.zoho.com/ to get you client id and secret. Generate a grant token (aka "Code") with scopes ZohoMail.accounts.READ, ZohoMail.folders.READ, ZohoMail.messages.ALL.
This gem is for internal use. To set up dependencies:
bundle installCreate a .env file in the root directory (see .env.example):
ZOHOMAIL_CLIENT_ID=your_client_id
ZOHOMAIL_CLIENT_SECRET=your_client_secret
ZOHOMAIL_ACCOUNT_ID=your_account_id
ZOHOMAIL_REFRESH_TOKEN=your_refresh_token
ZOHOMAIL_CACHE_FILE_PATH=./zoho_cache.jsonThe cache_file_path is used to store folder IDs mapped to their names. This avoids fetching the full list of folders from Zoho on every request when using folder_name instead of folder_id.
First, configure the gem with your Zoho credentials:
require 'zohomail_client'
ZohomailClient.configure do |config|
config.client_id = ENV['ZOHOMAIL_CLIENT_ID']
config.client_secret = ENV['ZOHOMAIL_CLIENT_SECRET']
config.refresh_token = ENV['ZOHOMAIL_REFRESH_TOKEN']
config.account_id = ENV['ZOHOMAIL_ACCOUNT_ID']
config.cache_file_path = ENV['ZOHOMAIL_CACHE_FILE_PATH'] # Optional: Path to store folder ID cache
config.allow_send_mail = false # Set to true to allow sending emails; false forces all emails as drafts (default: false)
end
# Refreshes the access token using the configuration and returns a client
client = ZohomailClient.clientAlternatively, you can provide the access token and user ID manually to create a client without a refresh token cycle:
client = ZohomailClient::Client.new(
access_token: 'your_access_token',
account_id: 'your_account_id',
cache_file_path: './zoho_cache.json' # Optional
)# List messages (default: 10 messages from Inbox)
response = client.list_messages
# List messages with options
response = client.list_messages(folder_name: "Inbox", limit: 5)
response["data"].each do |message|
puts "Subject: #{message['subject']}"
puts "From: #{message['sender']}"
puts "ID: #{message['messageId']}"
puts "---"
end# Search for messages using Zoho Mail search syntax
# See https://www.zoho.com/mail/help/search-syntax.html for search syntax details
# Search for emails from a specific sender
response = client.search_messages("sender:john@example.com", limit: 10)
# Search for emails with specific subject
response = client.search_messages("subject:meeting", limit: 10)
# Search for emails with attachments
response = client.search_messages("has:attachment", limit: 10)
# Search with multiple criteria
response = client.search_messages("from:john@example.com subject:project", limit: 10)
# Search for exact phrase
response = client.search_messages('entire:"Hello world"', limit: 10)
response["data"].each do |message|
puts "Subject: #{message['subject']}"
puts "From: #{message['sender']}"
puts "ID: #{message['messageId']}"
puts "---"
end# Fetch content using folder_name and message_id
response = client.get_message_content("Inbox", "987654321")
puts "Content: #{response['data']['content']}"# Send a new email
client.send_email(
to: "recipient@example.com",
subject: "Hello from Ruby",
content: "This is a test email sent via Zoho Mail API."
)
# Send with additional options
client.send_email(
to: "recipient@example.com",
subject: "Hello from Ruby",
content: "This is a test email sent via Zoho Mail API.",
from: "sender@example.com",
mail_format: "html",
is_draft: true
)# Reply to a message
response = client.send_reply(
folder_name: "Inbox",
message_id: "987654321",
content: "Thank you for your email."
)
# Reply with options
response = client.send_reply(
folder_name: "Inbox",
message_id: "987654321",
content: "Thank you for your email.",
mail_format: "html",
is_draft: true
)
# Reply with custom recipient
response = client.send_reply(
folder_name: "Inbox",
message_id: "987654321",
content: "Thank you for your email.",
to: "custom@example.com"
)First, you need a grant token from the Zoho Developer Console (Self-Client).
./bin/zohomail-auth <grant_token>This will exchange the grant token for a refresh token and store it in your .env file.
To see your folders and their IDs:
./bin/zohomail-folders./bin/zohomail-list [options]Options:
--limit LIMIT: Number of emails to fetch (default: 10)--folder-name NAME: Folder name to fetch from (e.g. Inbox)--format FORMAT: Output format: text or json (default: text)--help: Show help
Examples:
./bin/zohomail-list
./bin/zohomail-list --limit 20 --folder-name "Trash"
./bin/zohomail-list --format json./bin/zohomail-search [options] <search_key>Options:
--limit LIMIT: Number of emails to fetch (default: 10)--format FORMAT: Output format: text or json (default: text)--help: Show help
Search Key Examples:
sender:john@example.com- Search by sendersubject:meeting- Search by subjecthas:attachment- Emails with attachmentshas:flags- Flagged emailsentire:"Hello world"- Exact phrase searchfrom:john@example.com subject:project- Multiple criteria
Examples:
./bin/zohomail-search "sender:john@example.com"
./bin/zohomail-search --limit 20 "subject:meeting"
./bin/zohomail-search --format json "has:attachment"
./bin/zohomail-search 'entire:"Hello world"'See https://www.zoho.com/mail/help/search-syntax.html for more search syntax details.
./bin/zohomail-get [options] <message_id>Options:
--folder-name NAME: Folder name (e.g. Inbox)--format FORMAT: Output format: text or json (default: text)--help: Show help
Examples:
./bin/zohomail-get --folder-name Inbox 987654321
./bin/zohomail-get --folder-name "Sent" 987654321
./bin/zohomail-get --format json --folder-name Inbox 987654321./bin/zohomail-send [options]Options:
-t, --to EMAIL: Recipient email address (required)--cc EMAIL: CC recipient email address (comma separated for multiple)-s, --subject SUBJECT: Email subject (required unless replying)-c, --content CONTENT: Email content (interprets \n as newline, required)-f, --from EMAIL: Sender email address (required)--format FORMAT: Email format: html or plaintext (default: plaintext)--skip-draft: Skip creating a draft and send immediately--reply-to ID: Reply to a specific message ID-h, --help: Show help
Examples:
./bin/zohomail-send -t recipient@example.com -s "Hello" -c "Test email" -f sender@example.com
./bin/zohomail-send -t recipient@example.com --cc cc1@example.com,cc2@example.com -s "Hello" -c "Test email" -f sender@example.com --format html./bin/zohomail-reply [options] <message_id>Options:
-c, --content CONTENT: Reply content (interprets \n as newline)--cc EMAIL: CC recipient email address (comma separated for multiple)--folder-name NAME: Folder name of the original message--to EMAIL: Recipient email address (optional, defaults to original sender)--format FORMAT: Email format: html or plaintext (default: plaintext)--skip-draft: Skip creating a draft and send immediately-h, --help: Show help
Examples:
./bin/zohomail-reply --folder-name Inbox -c "Thank you for your email." 987654321
./bin/zohomail-reply --folder-name Inbox --cc cc@example.com -c "Thank you for your email." 987654321
./bin/zohomail-reply --folder-name "Sent" -c "Thank you for your email." 987654321
./bin/zohomail-reply --format html --skip-draft -c "<p>Thank you for your email.</p>" 987654321
./bin/zohomail-reply --to custom@example.com --folder-name Inbox -c "Thank you for your email." 987654321Bug reports and pull requests are welcome on GitHub at https://github.com/plerohellec/zohomail_client.
The gem is available as open source under the terms of the MIT License.