GMail Tool

Connection Setup Guide

The GMail tool allows your AI agent to manage a user's mailbox securely through the official Google API. It can read, send, and organize emails on the user's behalf.

Key Use Cases:

  • Automated Email Responses: Draft or send replies to common inquiries.
  • Information Retrieval: Find and summarize information from recent emails based on a query.
  • Inbox Triage: Automatically archive promotional emails or mark important messages as read.
  • Drafting for Review: Create draft emails with complex information (e.g., summaries from other tools) for the user to review and send manually.

gmail_tool.send_email

Sends an email to a specified recipient.

Parameters

NameTypeDescription
recipient string The email address of the recipient.
subject string The subject line of the email.
body string The plain text body of the email. 
curl -X POST https://toolstream.dev/v1/tools/execute \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "gmail_tool.send_email",
    "arguments": {
      "recipient": {
        "type": "string",
        "description": "The email address of the recipient."
      },
      "subject": {
        "type": "string",
        "description": "The subject line of the email."
      },
      "body": {
        "type": "string",
        "description": "The plain text body of the email."
      }
    }
  }
}'
import requests
import json

API_KEY = "YOUR_API_KEY"
TOOLSTREAM_URL = "https://toolstream.dev/v1/tools/execute"

payload = {
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "gmail_tool.send_email",
    "arguments": {
      "recipient": {
        "type": "string",
        "description": "The email address of the recipient."
      },
      "subject": {
        "type": "string",
        "description": "The subject line of the email."
      },
      "body": {
        "type": "string",
        "description": "The plain text body of the email."
      }
    }
  }
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(TOOLSTREAM_URL, headers=headers, data=json.dumps(payload))

if response.status_code == 200:
    result = response.json()
    print(json.dumps(result, indent=2))
else:
    print(f"Error: {response.status_code}")
    print(response.text)

gmail_tool.list_messages

Lists messages in the user's mailbox matching a specific query.

Parameters

NameTypeDescription
query string The GMail search query (e.g., 'is:unread', 'from:someone@example.com'). Defaults to 'is:inbox'.
max_results integer The maximum number of messages to return. Defaults to 10. 
curl -X POST https://toolstream.dev/v1/tools/execute \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "gmail_tool.list_messages",
    "arguments": {
      "query": {
        "type": "string",
        "description": "The GMail search query (e.g., 'is:unread', 'from:someone@example.com'). Defaults to 'is:inbox'."
      },
      "max_results": {
        "type": "integer",
        "description": "The maximum number of messages to return. Defaults to 10."
      }
    }
  }
}'
import requests
import json

API_KEY = "YOUR_API_KEY"
TOOLSTREAM_URL = "https://toolstream.dev/v1/tools/execute"

payload = {
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "gmail_tool.list_messages",
    "arguments": {
      "query": {
        "type": "string",
        "description": "The GMail search query (e.g., 'is:unread', 'from:someone@example.com'). Defaults to 'is:inbox'."
      },
      "max_results": {
        "type": "integer",
        "description": "The maximum number of messages to return. Defaults to 10."
      }
    }
  }
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(TOOLSTREAM_URL, headers=headers, data=json.dumps(payload))

if response.status_code == 200:
    result = response.json()
    print(json.dumps(result, indent=2))
else:
    print(f"Error: {response.status_code}")
    print(response.text)

gmail_tool.get_message

Retrieves the full details of a single email message by its ID.

Parameters

NameTypeDescription
message_id string The unique ID of the message to retrieve. 
curl -X POST https://toolstream.dev/v1/tools/execute \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "gmail_tool.get_message",
    "arguments": {
      "message_id": {
        "type": "string",
        "description": "The unique ID of the message to retrieve."
      }
    }
  }
}'
import requests
import json

API_KEY = "YOUR_API_KEY"
TOOLSTREAM_URL = "https://toolstream.dev/v1/tools/execute"

payload = {
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "gmail_tool.get_message",
    "arguments": {
      "message_id": {
        "type": "string",
        "description": "The unique ID of the message to retrieve."
      }
    }
  }
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(TOOLSTREAM_URL, headers=headers, data=json.dumps(payload))

if response.status_code == 200:
    result = response.json()
    print(json.dumps(result, indent=2))
else:
    print(f"Error: {response.status_code}")
    print(response.text)

gmail_tool.reply_to_message

Replies to a specific email, keeping it in the same conversation thread.

Parameters

NameTypeDescription
message_id string The ID of the message to reply to.
body string The plain text body of the reply. 
curl -X POST https://toolstream.dev/v1/tools/execute \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "gmail_tool.reply_to_message",
    "arguments": {
      "message_id": {
        "type": "string",
        "description": "The ID of the message to reply to."
      },
      "body": {
        "type": "string",
        "description": "The plain text body of the reply."
      }
    }
  }
}'
import requests
import json

API_KEY = "YOUR_API_KEY"
TOOLSTREAM_URL = "https://toolstream.dev/v1/tools/execute"

payload = {
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "gmail_tool.reply_to_message",
    "arguments": {
      "message_id": {
        "type": "string",
        "description": "The ID of the message to reply to."
      },
      "body": {
        "type": "string",
        "description": "The plain text body of the reply."
      }
    }
  }
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(TOOLSTREAM_URL, headers=headers, data=json.dumps(payload))

if response.status_code == 200:
    result = response.json()
    print(json.dumps(result, indent=2))
else:
    print(f"Error: {response.status_code}")
    print(response.text)

gmail_tool.create_draft

Creates a draft email for the user to review and send later. Does not send the email.

Parameters

NameTypeDescription
recipient string The email address of the recipient.
subject string The subject line of the email.
body string The plain text body of the email. 
curl -X POST https://toolstream.dev/v1/tools/execute \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "gmail_tool.create_draft",
    "arguments": {
      "recipient": {
        "type": "string",
        "description": "The email address of the recipient."
      },
      "subject": {
        "type": "string",
        "description": "The subject line of the email."
      },
      "body": {
        "type": "string",
        "description": "The plain text body of the email."
      }
    }
  }
}'
import requests
import json

API_KEY = "YOUR_API_KEY"
TOOLSTREAM_URL = "https://toolstream.dev/v1/tools/execute"

payload = {
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "gmail_tool.create_draft",
    "arguments": {
      "recipient": {
        "type": "string",
        "description": "The email address of the recipient."
      },
      "subject": {
        "type": "string",
        "description": "The subject line of the email."
      },
      "body": {
        "type": "string",
        "description": "The plain text body of the email."
      }
    }
  }
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(TOOLSTREAM_URL, headers=headers, data=json.dumps(payload))

if response.status_code == 200:
    result = response.json()
    print(json.dumps(result, indent=2))
else:
    print(f"Error: {response.status_code}")
    print(response.text)

gmail_tool.archive_message

Archives an email message, removing it from the inbox.

Parameters

NameTypeDescription
message_id string The ID of the message to archive. 
curl -X POST https://toolstream.dev/v1/tools/execute \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "gmail_tool.archive_message",
    "arguments": {
      "message_id": {
        "type": "string",
        "description": "The ID of the message to archive."
      }
    }
  }
}'
import requests
import json

API_KEY = "YOUR_API_KEY"
TOOLSTREAM_URL = "https://toolstream.dev/v1/tools/execute"

payload = {
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "gmail_tool.archive_message",
    "arguments": {
      "message_id": {
        "type": "string",
        "description": "The ID of the message to archive."
      }
    }
  }
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(TOOLSTREAM_URL, headers=headers, data=json.dumps(payload))

if response.status_code == 200:
    result = response.json()
    print(json.dumps(result, indent=2))
else:
    print(f"Error: {response.status_code}")
    print(response.text)

gmail_tool.mark_as_read

Marks a message as read.

Parameters

NameTypeDescription
message_id string The ID of the message to mark as read. 
curl -X POST https://toolstream.dev/v1/tools/execute \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "gmail_tool.mark_as_read",
    "arguments": {
      "message_id": {
        "type": "string",
        "description": "The ID of the message to mark as read."
      }
    }
  }
}'
import requests
import json

API_KEY = "YOUR_API_KEY"
TOOLSTREAM_URL = "https://toolstream.dev/v1/tools/execute"

payload = {
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "gmail_tool.mark_as_read",
    "arguments": {
      "message_id": {
        "type": "string",
        "description": "The ID of the message to mark as read."
      }
    }
  }
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(TOOLSTREAM_URL, headers=headers, data=json.dumps(payload))

if response.status_code == 200:
    result = response.json()
    print(json.dumps(result, indent=2))
else:
    print(f"Error: {response.status_code}")
    print(response.text)