Skip to main content

Gmail

Connect Gmail to BotDojo so agents can search, read, draft, and send email from a connected Google account.

Before You Start​

You will need:

  • A Google account with Gmail access
  • Access to BotDojo's Integrations page
  • Permission to approve the Gmail OAuth scopes during connect

Connect Gmail in BotDojo​

  1. Open Integrations in BotDojo.
  2. Find Gmail in the Agent Tools section.
  3. Click Connect.
  4. Sign in with your Google account and approve the requested Gmail permissions.
  5. Wait for BotDojo to finish the OAuth flow and save the integration.

Supported Actions​

Gmail supports these agent actions:

  • Search messages
  • List messages
  • Get a message by ID
  • Send a message
  • List send-as addresses
  • Create a draft
  • List drafts
  • Get a draft
  • Update a draft
  • Send a draft
  • Delete a draft
  • Add labels to a message
  • Remove labels from a message
  • Create a label
  • Mark a message as read
  • Mark a message as unread
  • List labels

Send, draft, and draft-update actions can include attachments from public http(s) URLs or workspace file paths such as /mnt/workspace/report.pdf. You can mix both forms in the same request:

{
  "attachments": [
    "https://example.com/invoices/INV-154546.pdf",
    "/mnt/workspace/invoices/INV-154546.pdf"
  ]
}

If an attachment cannot be fetched or read, BotDojo fails the action instead of sending or saving a partial message. Get Message and Get Draft return attachmentCount, attachmentFilenames, and detailed attachment metadata with attachmentId values. Download Attachment can return base64 content or save the file to a workspace path.

Use List Send-As Addresses before setting from or sendAsEmail. Gmail only allows sending from the connected mailbox and verified aliases. Send Message, Create Draft, and Update Draft validate the requested sender before calling Gmail.

List Drafts returns compact summaries by default: draft IDs, message IDs, subject, sender, recipients, snippet, and attachment summary fields. Use format: "full" only when you need bodies, raw headers, and complete attachment objects. Use Get Draft for a single full draft.

Update Draft replaces the Gmail draft message content under the hood. If attachments is omitted, BotDojo preserves existing draft attachments. If attachments is provided, that array is the final attachment set. For removals, prefer removeAttachmentFilenames; filename matching is case-insensitive and removes all current draft attachments with that filename. If an ID-based removal is required, call Get Draft immediately first and pass the draft attachment's attachmentRemovalId to removeAttachmentIds. Raw Gmail attachmentId values are best-effort because Gmail can regenerate them during draft updates. If a requested removal does not match the current draft, BotDojo fails the update instead of silently preserving the attachment.

Use Delete Draft to remove test or unwanted drafts by draftId.

Troubleshooting​

  • Connect fails: make sure you approved the Gmail scopes during OAuth.
  • Missing messages or labels: confirm the connected Google account is the one that owns the mailbox you want to use.
  • Send actions fail: check that the account has Gmail send permission and that the OAuth grant was completed again after any scope changes.
  • Send-as fails: call List Send-As Addresses and use an address with canSend: true.
  • Draft attachment missing: call Get Draft and check attachmentCount and attachmentFilenames before sending.