gmail-recipes

Gmail Recipes Skill

DEPENDENCY: Load the workato-recipes base skill first if not already loaded. This skill requires the base Workato knowledge for triggers, control flow, datapills, and recipe structure.

You are now equipped with Gmail-specific knowledge for writing Workato recipes using the native Gmail connector.

---

CRITICAL: Pre-Generation Checklist

For EXISTING projects:

1. Read existing Gmail .recipe.json files to understand local patterns

For GREENFIELD projects:

1. Use skill templates - see templates/ directory for validated examples
2. Use descriptive UUIDs - e.g., list-emails-001, get-details-002

ALWAYS:

1. Ask for connection name - exact name of Gmail connection in Workato
2. Confirm operation type - send, list, search, or label management
3. Use API endpoint trigger for testability via curl
4. Use descriptive UUIDs - never copy random hex UUIDs from existing recipes
5. Remember datapill paths - adhoc HTTP uses ["body", ...] wrapper

WARNING: Gmail adhoc HTTP responses wrap data in body. Always use paths like ["body", "messages"] for list/search results.

---

Capabilities

With this skill loaded, you can:

• Create recipes that send emails (text/HTML) with attachments
• Create recipes that list and search emails with Gmail query syntax
• Create recipes that get full message details
• Create recipes that manage labels (create, list, apply, remove)
• Create recipes that archive or modify messages
• Create callable API endpoint recipes for Gmail operations

---

Gmail Connector

This skill covers the native Gmail connector (gmail) which provides:

• 3 native actions for core email operations (send, get by ID, download attachment)
• 1 trigger for new email arrival
• Adhoc HTTP actions for all other Gmail REST API operations (list, search, labels, user info, modify, delete, threads, drafts)

Connector Limitations

Important: The native Gmail connector is built on the Gmail REST API v1 with a hardcoded base URL (https://www.googleapis.com/gmail/v1/users/). This means:

• 3 native actions + 1 trigger — covers send, get email/draft by ID, and download attachment
• Adhoc HTTP required for most operations: list/search emails, labels, user info, message modification, deletion, threads, drafts
• API version locked - Cannot access newer Gmail API features not in v1

If a user needs functionality not supported by the v1 API, recommend they:

1. Check the Workato Community Library for updated Gmail connectors
2. Consider building a custom SDK connector with the needed endpoints
3. Use the HTTP connector with custom OAuth for full API flexibility

Note: Developers can build custom SDK connectors for Gmail with additional actions. See workato-recipes/patterns/custom-connector-actions.md for custom connector patterns. Custom connectors are not included with Workato by default.

---

Gmail-Specific Knowledge

Provider

Use gmail for the native Gmail connector:

"provider": "gmail"

Connection Configuration

{
  "keyword": "application",
  "provider": "gmail",
  "skip_validation": false,
  "account_id": {
    "zip_name": "my_gmail_account.connection.json",
    "name": "My Gmail account",
    "folder": ""
  }
}

Gmail API Base URL

For adhoc HTTP actions, Gmail uses:

https://www.googleapis.com/gmail/v1/users/

Common paths:

• me/messages - List messages
• me/messages/{id} - Get message details
• me/labels - List labels
• me/labels/{id} - Get/modify label

Datapill Paths

Native actions (like send_mail) return data without body wrapper:

"path": ["id"]
"path": ["threadId"]
"path": ["labelIds"]

Adhoc HTTP actions wrap responses in body:

"path": ["body", "messages"]
"path": ["body", "id"]
"path": ["body", "labelIds"]

Gmail Query Syntax

The q parameter supports Gmail search operators:

• from:[email protected] - From specific sender
• to:[email protected] - To specific recipient
• subject:keyword - Subject contains keyword
• is:unread - Unread messages
• is:starred - Starred messages
• has:attachment - Has attachments
• after:2024/01/01 - After date
• before:2024/12/31 - Before date
• label:INBOX - Has specific label

Combine with spaces: from:[email protected] is:unread has:attachment

Optional Parameters Pattern

For optional query parameters, use .presence || skip:

"input": {
  "data": {
    "maxResults": "=_dp('{...}').presence || skip",
    "pageToken": "=_dp('{...}').presence || skip",
    "q": "=_dp('{...}').presence || skip",
    "labelIds": "=_dp('{...}').presence || skip"
  }
}

---

Native Connector Guidance

The Gmail connector provides 3 native actions and 1 trigger. See lint-rules.json for the authoritative list of valid action and trigger names.

Trigger

• new_email — Fires when a new email arrives in the connected account.

Choosing the Right Approach

Native actions (use these when possible):

• send_mail — Send an email (text or HTML) with optional attachments. See detail below.
• get_email_or_draft_by_id — Get full details of a single email or draft by message ID. Returns headers, body, labels, snippet.
• download_attachment — Download an attachment by message ID and attachment ID.

Adhoc HTTP required for everything else:

• List/search emails — Use __adhoc_http_action with GET me/messages and Gmail query syntax via the q parameter. See adhoc patterns below.
• Labels — List, create, modify, delete, apply, or remove labels via me/labels endpoints.
• User info — Get Gmail profile via me/profile.
• Message operations — Modify (add/remove labels, archive), delete, trash via me/messages/{id}/modify, me/messages/{id}/trash.
• Threads and drafts — Full thread and draft management via me/threads, me/drafts.

See patterns/gmail-api-reference.md for the full endpoint catalog.

---

send_mail Detail

Send an email with optional attachments:

{
  "provider": "gmail",
  "name": "send_mail",
  "keyword": "action",
  "input": {
    "email_type": "html",
    "to": "[email protected]",
    "subject": "Email Subject",
    "body": "<p>HTML content here</p>",
    "from": "[email protected]",
    "cc": "[email protected]",
    "bcc": "[email protected]",
    "reply_to": "[email protected]",
    "attachments": {
      "____source": "#{_dp('{...path to attachments array}')}",
      "file_binary_content": "#{_dp('{...path to file content}')}",
      "file_name": "#{_dp('{...path to file name}')}"
    }
  }
}

Email types:

• "text" - Plain text email
• "html" - HTML formatted email

Output fields:

• id - Message ID
• threadId - Thread ID
• labelIds - Array of label IDs

---

Adhoc HTTP Patterns

List Messages

{
  "provider": "gmail",
  "name": "__adhoc_http_action",
  "keyword": "action",
  "input": {
    "mnemonic": "List Emails",
    "verb": "get",
    "response_type": "json",
    "path": "me/messages",
    "input": {
      "schema": "[...]",
      "data": {
        "maxResults": "=_dp('{...}').presence || skip",
        "q": "=_dp('{...}').presence || skip"
      }
    },
    "output": "[{\"name\":\"messages\",\"type\":\"array\",\"of\":\"object\",\"properties\":[{\"name\":\"id\",\"type\":\"string\"},{\"name\":\"threadId\",\"type\":\"string\"}]}]"
  }
}

Get Message Details

{
  "provider": "gmail",
  "name": "__adhoc_http_action",
  "keyword": "action",
  "input": {
    "mnemonic": "Get Message Details",
    "verb": "get",
    "response_type": "json",
    "path": "me/messages/#{_dp('{...message_id}')}",
    "output": "[{\"name\":\"id\",\"type\":\"string\"},{\"name\":\"threadId\",\"type\":\"string\"},{\"name\":\"labelIds\",\"type\":\"array\",\"of\":\"string\"},{\"name\":\"snippet\",\"type\":\"string\"},{\"name\":\"payload\",\"type\":\"object\",\"properties\":[...]}]"
  }
}

---

Common Patterns

List + Enrich Pattern

Gmail's list endpoint returns minimal data (just IDs). To get full details, use a foreach loop:

1. List messages (returns IDs only)
2. Declare a list variable
3. Foreach message ID:
   • Get message details
   • Add to list variable
4. Return enriched list

See templates/list-emails.json for a complete example.

Error Handling

Wrap Gmail operations in try/catch for robust error handling:

{
  "keyword": "try",
  "block": [
    // Gmail operations
  ]
},
{
  "keyword": "catch",
  "block": [
    // Return error response
  ]
}

---

Validation

See validation-checklist.md for Gmail-specific validation, which references the base checklist in workato-recipes/validation-checklist.md.

---

Reference Files

• skills/workato-recipes/SKILL.md - Base platform knowledge
• skills/gmail-recipes/patterns/native-gmail-actions.md - Native action details
• skills/gmail-recipes/patterns/gmail-api-reference.md - API endpoint reference
• skills/gmail-recipes/templates/ - Validated recipe templates

---

Usage

Before Generating Recipes

Ask the user for these details:

1. Gmail connection name - What is their Gmail connection called?

   • Example: "My Gmail account"

2. Operation type - Send, list, search, or manage labels?

3. Trigger type - API endpoint, scheduler, or event-driven?

Recipe Generation Steps

1. Ask for connection name (REQUIRED)
2. Identify the operation needed
3. Determine if native action or adhoc HTTP is required
4. Generate valid JSON using base skill structure + Gmail specifics

---

Example Prompts

• "Create a recipe that sends an HTML email with attachments via API"
• "Create a recipe that lists unread emails from a specific sender"
• "Create a recipe that searches for emails and returns full details"
• "Create a recipe that applies a label to matching emails"