Gmail - Setup Guide

Gmail API integration for automated email management with Axellero.

Step 1: Create Credential

Getting OAuth 2.0 Credentials from Google Cloud

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Navigate to APIs & Services → Library
4. Search for "Gmail API" and click Enable
5. Go to APIs & Services → OAuth consent screen
   • Select User Type (Internal or External)
   • Fill in required fields (App name, Support email)
   • Add the required scopes (see table below)
6. Go to APIs & Services → Credentials
7. Click Create Credentials → OAuth client ID
8. Select Web application
9. Add your OAuth callback URL to Authorized redirect URIs
10. Click Create and save the Client ID and Client Secret

Required Scopes:

Adding Credential to Axellero

1. Navigate to Application > Integrations > Credentials
2. Click "Add Credential"
3. Select OAuth 2.0
4. Enter:
   • Name: "Gmail - Production"
   • Client ID: From Google Cloud Console
   • Client Secret: From Google Cloud Console
   • Authorization URL: https://accounts.google.com/o/oauth2/v2/auth
   • Token URL: https://oauth2.googleapis.com/token
   • Scopes: Add the required scopes
5. Click Save, then click "Authorize"
6. Complete the Google sign-in and grant permissions

Axellero automatically handles token refresh and secure storage.

Step 2: Create Connector

1. Navigate to Application > Integrations > Connectors
2. Click "Add Connector"
3. Select Gmail from the list
4. Configure:
   • Name: "Gmail - Production"
   • Credential: Select the OAuth 2.0 credential you created
5. Click Save
6. Test the connection using the "Test" button (calls getProfile)

The connector is now available in any workflow or agentflow.

Step 3: Create Trigger

For supported events and payload examples, see main documentation.

3.1 Pub/Sub Prerequisites

Gmail triggers use Google Cloud Pub/Sub for real-time notifications.

1. Go to Google Cloud Pub/Sub
2. Click "Create Topic"
3. Enter topic name (e.g., gmail-notifications)
4. Click "Create"
5. Open your topic → Permissions tab
6. Click "Add Principal"
7. Add: gmail-api-push@system.gserviceaccount.com
8. Assign role: Pub/Sub Publisher
9. Click "Save"

Note the full topic name: projects/{project-id}/topics/{topic-name}

3.2 Create Trigger

1. Navigate to Integrations > Triggers
2. Click "Add Trigger" (+) button
3. Select your Gmail connector
4. Configure:
   • Pub/Sub Topic: Full topic name from step 3.1
   • Label Filter: Labels to watch (default: INBOX)
   • Filter Behavior: Include or exclude specified labels
   • History Types: Event types to track (messageAdded, labelAdded, etc.)
5. Click Save

How it works: Axellero automatically sets up Gmail watch on your mailbox. When emails arrive, Gmail notifies Pub/Sub, which forwards to Axellero.

3.3 Create Push Subscription

1. In Google Cloud Pub/Sub, go to your topic
2. Click "Create Subscription"
3. Select Push delivery type
4. Enter the Axellero webhook URL (from trigger settings)
5. Click "Create"

3.4 Add Trigger to Workflow

1. Open Workflow Builder
2. Find your trigger in the Triggers section
3. Drag to canvas as starting node
4. Build workflow logic after the trigger

3.5 Test the Trigger

1. Send a test email to your Gmail account
2. Check workflow execution logs in Axellero
3. Verify trigger data via {{ctx.nodes.gmail_trigger.outputs.data}}

Workflow Examples

Example 1: Auto-Forward Important Emails

Forward emails from VIP senders to Telegram.

Workflow Steps:

1. Gmail Trigger: Events = messageAdded, Label = INBOX
2. Condition: Check if sender matches VIP list
3. Telegram - sendMessage: Forward to notification channel

Trigger Configuration:

{
  "topicName": "projects/my-project/topics/gmail-notifications",
  "labelIds": "INBOX",
  "historyTypes": "messageAdded"
}

Example 2: Support Ticket Creation

Create Linear issues from support emails.

Workflow Steps:

1. Gmail Trigger: Events = messageAdded, Label = Support
2. Gmail - getMessage: Fetch full email content
3. Linear - createIssue: Create issue with email subject as title

Example 3: Daily Email Digest

Send a daily summary of unread emails.

Workflow Steps:

1. Schedule Trigger: Daily at 9:00 AM
2. Gmail - listMessages: Query is:unread with limit 20
3. Loop: For each message, get details
4. Gmail - sendMessage: Send compiled digest

Configuration:

{
  "q": "is:unread",
  "maxResults": 20,
  "labelIds": "INBOX"
}

Example 4: Attachment Processing

Download and store attachments from incoming emails.

Workflow Steps:

1. Gmail Trigger: Watch for new messages
2. Gmail - getMessage: Get message with attachments
3. Condition: Check if attachments exist
4. Gmail - getAttachment: Download each attachment
5. HTTP Request: Store attachment in external storage

Troubleshooting

Common Issues

Token expires frequently

• Axellero handles token refresh automatically
• If still failing, re-authorize the credential

Trigger not receiving emails

• Verify Pub/Sub topic permissions include gmail-api-push@system.gserviceaccount.com
• Check push subscription endpoint URL is correct
• Ensure Gmail watch is active (auto-renewed by Axellero)

Missing emails in trigger

• Check label filter configuration
• Verify historyTypes includes the event you want

Security Best Practices

• Use Axellero Credential Manager for encrypted storage
• Axellero handles token refresh automatically
• Use minimum required scopes for your use case
• Monitor API usage in Google Cloud Console
• Review OAuth app permissions periodically

Resources

• Gmail API Documentation
• Gmail API Reference
• Google OAuth 2.0 Guide
• Google Cloud Pub/Sub
• Back to Main Documentation