orthogonal-sh/gmail

Gmail

Send, read, and manage emails through Gmail integration. Connect to your Gmail account to send emails, check your inbox, read messages, create drafts, and more.

Requirements

• Install the orth CLI
• Connect your Gmail account at https://orthogonal.com/dashboard/integrations
• OAuth connection must be active (HTTP 428 response means not connected)

Actions

Send Email

Send an email with optional attachments and formatting.

orth run gmail /send-email --body '{
  "recipient_email": "[email protected]",
  "body": "Hello, this is a test email.",
  "subject": "Test Email"
}'

Parameters:

• recipient_email (required) - Primary recipient's email address
• body (required) - Email content/message
• subject - Email subject line
• cc - CC recipients (comma-separated emails)
• bcc - BCC recipients (comma-separated emails)
• is_html - Send as HTML format (true/false)
• attachment - File attachment path
• extra_recipients - Additional recipients array
• user_id - Specific user ID to send as

List Emails

Retrieve emails from your inbox or specific folders.

orth run gmail /list-emails --body '{
  "max_results": 10,
  "query": "is:unread"
}'

Parameters:

• query - Gmail search query (e.g., "is:unread", "from:[email protected]")
• label_ids - Specific Gmail label IDs to search
• max_results - Maximum number of emails to return
• verbose - Include detailed email data (true/false)
• ids_only - Return only message IDs (true/false)
• include_payload - Include full message content (true/false)
• include_spam_trash - Include spam and trash folders (true/false)
• page_token - Token for pagination
• user_id - Specific user ID to query

Get Email

Retrieve a specific email by its message ID.

orth run gmail /get-email --body '{
  "message_id": "MESSAGE_ID_HERE"
}'

Parameters:

• message_id (required) - Gmail message ID to retrieve
• format - Response format (full, metadata, minimal)
• user_id - Specific user ID to query

Create Draft

Create a draft email for later sending.

orth run gmail /create-draft --body '{
  "recipient_email": "[email protected]",
  "body": "Draft email content",
  "subject": "Draft Subject"
}'

Parameters:

• recipient_email (required) - Primary recipient's email address
• body (required) - Email content/message
• subject (required) - Email subject line
• cc - CC recipients (comma-separated emails)
• bcc - BCC recipients (comma-separated emails)
• is_html - Draft as HTML format (true/false)
• thread_id - Thread ID to reply within
• attachment - File attachment path
• extra_recipients - Additional recipients array
• user_id - Specific user ID to create draft as

Usage Examples

Send a quick email:

orth run gmail /send-email -b '{"recipient_email":"[email protected]","body":"The report is ready for review.","subject":"Report Ready"}'

Check unread emails:

orth run gmail /list-emails -b '{"query":"is:unread","max_results":5}'

Get a specific email:

orth run gmail /get-email -b '{"message_id":"17a1b2c3d4e5f6g7"}'

Create HTML draft:

orth run gmail /create-draft -b '{"recipient_email":"[email protected]","subject":"Weekly Update","body":"<h1>Weekly Report</h1><p>All tasks completed.</p>","is_html":true}'

Error Handling

• HTTP 428 - Gmail integration not connected. Visit https://orthogonal.com/dashboard/integrations to connect your account
• 400 Bad Request - Invalid email format or missing required parameters
• 403 Forbidden - Insufficient permissions or quota exceeded
• 404 Not Found - Message ID does not exist
• 429 Rate Limited - Too many requests, wait before retrying

Tips

• Use Gmail search syntax in query parameter (is:unread, from:email, has:attachment)
• Set max_results appropriately to avoid large responses
• Use ids_only=true for fast email counting
• HTML emails need is_html=true parameter
• Draft emails can be edited later in Gmail interface