🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
GmailToolkit
class GmailToolkit(BaseToolkit):
A comprehensive toolkit for Gmail operations.
This toolkit provides methods for Gmail operations including sending emails, managing drafts, fetching messages, managing labels, and handling contacts. It supports both plain text and HTML email formats, attachment handling, and comprehensive Gmail API integration.
Parameters:
- timeout (Optional[float]): The timeout value for API requests in seconds. If None, no timeout is applied. (default: :obj:
None)
Note:
This toolkit requires Google OAuth2 authentication. On first use, it will open a browser window for authentication and store credentials for future use.
Authentication Scopes:
The toolkit requests the following Gmail API scopes:
https://www.googleapis.com/auth/gmail.readonly- Read-only accesshttps://www.googleapis.com/auth/gmail.send- Send emailshttps://www.googleapis.com/auth/gmail.modify- Modify emailshttps://www.googleapis.com/auth/gmail.compose- Compose emailshttps://www.googleapis.com/auth/gmail.labels- Manage labelshttps://www.googleapis.com/auth/contacts.readonly- Read contactshttps://www.googleapis.com/auth/userinfo.profile- User profile access
init
def __init__(
self,
timeout: Optional[float] = None,
):
Initialize a new instance of the GmailToolkit class.
Parameters:
- timeout (Optional[float]): The timeout value for API requests in seconds. If None, no timeout is applied. (default: :obj:
None)
send_email
def send_email(
self,
to: Union[str, List[str]],
subject: str,
body: str,
cc: Optional[Union[str, List[str]]] = None,
bcc: Optional[Union[str, List[str]]] = None,
attachments: Optional[List[str]] = None,
is_html: bool = False,
) -> Dict[str, Any]:
Send an email through Gmail.
Parameters:
- to (Union[str, List[str]]): Recipient email address(es).
- subject (str): Email subject.
- body (str): Email body content.
- cc (Optional[Union[str, List[str]]]): CC recipient email address(es).
- bcc (Optional[Union[str, List[str]]]): BCC recipient email address(es).
- attachments (Optional[List[str]]): List of file paths to attach.
- is_html (bool): Whether the body is HTML format. Set to True when sending formatted emails with HTML tags (e.g., bold, links, images). Use False (default) for plain text emails.
Returns:
- Dict[str, Any]: A dictionary containing the result of the operation with keys:
success(bool): Whether the operation was successfulmessage_id(str): The ID of the sent messagethread_id(str): The ID of the email threadmessage(str): Status message
Example:
from camel.toolkits import GmailToolkit
gmail = GmailToolkit()
result = gmail.send_email(
to="[email protected]",
subject="Hello from CAMEL",
body="This is a test email",
cc=["[email protected]"],
attachments=["/path/to/file.pdf"],
is_html=False
)
print(result)
# {'success': True, 'message_id': 'abc123', 'thread_id': 'abc123', 'message': 'Email sent successfully'}
create_email_draft
def create_email_draft(
self,
to: Union[str, List[str]],
subject: str,
body: str,
cc: Optional[Union[str, List[str]]] = None,
bcc: Optional[Union[str, List[str]]] = None,
attachments: Optional[List[str]] = None,
is_html: bool = False,
) -> Dict[str, Any]:
Create a draft email in Gmail.
Parameters:
- to (Union[str, List[str]]): Recipient email address(es).
- subject (str): Email subject.
- body (str): Email body content.
- cc (Optional[Union[str, List[str]]]): CC recipient email address(es).
- bcc (Optional[Union[str, List[str]]]): BCC recipient email address(es).
- attachments (Optional[List[str]]): List of file paths to attach.
- is_html (bool): Whether the body is HTML format.
Returns:
- Dict[str, Any]: A dictionary containing the result of the operation with keys:
success(bool): Whether the operation was successfuldraft_id(str): The ID of the created draftmessage(str): Status message
fetch_emails
def fetch_emails(
self,
query: str = "",
max_results: int = 10,
include_spam_trash: bool = False,
label_ids: Optional[List[str]] = None,
) -> Dict[str, Any]:
Retrieve messages from Gmail.
Parameters:
- query (str): Gmail search query (e.g., "from:[email protected]", "subject:urgent"). (default: :obj:
"") - max_results (int): Maximum number of messages to retrieve. (default: :obj:
10) - include_spam_trash (bool): Whether to include messages from spam and trash. (default: :obj:
False) - label_ids (Optional[List[str]]): List of label IDs to filter by.
Returns:
- Dict[str, Any]: A dictionary containing the result of the operation with keys:
success(bool): Whether the operation was successfulmessages(List[Dict]): List of message objects with metadatatotal_count(int): Total number of messages foundmessage(str): Status message
Example:
# Get recent messages
result = gmail.fetch_emails(max_results=5)
# Search for specific emails
result = gmail.fetch_emails(query="from:[email protected]", max_results=10)
# Get unread messages
result = gmail.fetch_emails(query="is:unread")
_get_message_details (internal)
def _get_message_details(self, message_id: str) -> Optional[Dict[str, Any]]:
Get detailed fields for a message (subject, from, to, cc, bcc, date, body, attachments). Intended for internal use.
get_attachment
def get_attachment(
self,
message_id: str,
attachment_id: str,
save_path: Optional[str] = None,
) -> Dict[str, Any]:
Retrieve attachments from a specific message.
Parameters:
- message_id (str): The ID of the message containing the attachment.
- attachment_id (str): The ID of the attachment to retrieve.
- save_path (Optional[str]): Path to save the attachment. If None, returns the attachment data.
Returns:
- Dict[str, Any]: A dictionary containing the result of the operation with keys:
success(bool): Whether the operation was successfulattachment_data(bytes): The attachment data (if save_path is None)saved_path(str): The path where the attachment was saved (if save_path is provided)filename(str): The name of the attachment filesize(int): The size of the attachment in bytes
list_gmail_labels
def list_gmail_labels(self) -> Dict[str, Any]:
Retrieve all labels from Gmail.
Returns:
- Dict[str, Any]: A dictionary containing the result of the operation with keys:
success(bool): Whether the operation was successfullabels(List[Dict]): List of label objects with metadatamessage(str): Status message
create_label
def create_label(
self,
name: str,
message_list_visibility: str = "show",
label_list_visibility: str = "labelShow",
) -> Dict[str, Any]:
Create a new label in Gmail.
Parameters:
- name (str): The name of the label to create.
- message_list_visibility (str): Visibility of the label in the message list. (default: :obj:
"show") - label_list_visibility (str): Visibility of the label in the label list. (default: :obj:
"labelShow")
Returns:
- Dict[str, Any]: A dictionary containing the result of the operation with keys:
success(bool): Whether the operation was successfullabel_id(str): The ID of the created labelmessage(str): Status message
modify_email_labels
def modify_email_labels(
self,
message_id: str,
add_label_ids: Optional[List[str]] = None,
remove_label_ids: Optional[List[str]] = None,
) -> Dict[str, Any]:
Modify labels of a specific message.
Parameters:
- message_id (str): The ID of the message to modify.
- add_label_ids (Optional[List[str]]): List of label IDs to add to the message.
- remove_label_ids (Optional[List[str]]): List of label IDs to remove from the message.
Returns:
- Dict[str, Any]: A dictionary containing the result of the operation with keys:
success(bool): Whether the operation was successfulmessage_id(str): The ID of the modified messagemessage(str): Status message
move_to_trash
def move_to_trash(self, message_id: str) -> Dict[str, Any]:
Delete a specific message.
Parameters:
- message_id (str): The ID of the message to delete.
Returns:
- Dict[str, Any]: A dictionary containing the result of the operation with keys:
success(bool): Whether the operation was successfulmessage(str): Status message
get_contacts
def get_contacts(
self,
max_results: int = 100,
page_size: int = 100,
) -> Dict[str, Any]:
Retrieve contacts from Google Contacts.
Parameters:
- max_results (int): Maximum number of contacts to retrieve. (default: :obj:
100) - page_size (int): Number of contacts per page. (default: :obj:
100)
Returns:
- Dict[str, Any]: A dictionary containing the result of the operation with keys:
success(bool): Whether the operation was successfulcontacts(List[Dict]): List of contact objects with metadatatotal_count(int): Total number of contacts foundmessage(str): Status message
search_people
def search_people(
self,
query: str,
max_results: int = 10,
) -> Dict[str, Any]:
Search for contacts by name or email.
Parameters:
- query (str): Search query for contacts.
- max_results (int): Maximum number of contacts to retrieve. (default: :obj:
10)
Returns:
- Dict[str, Any]: A dictionary containing the result of the operation with keys:
success(bool): Whether the operation was successfulcontacts(List[Dict]): List of matching contact objectstotal_count(int): Total number of contacts foundmessage(str): Status message
get_profile
def get_profile(self) -> Dict[str, Any]:
Retrieve the current user's Gmail profile information.
Returns:
- Dict[str, Any]: A dictionary containing the result of the operation with keys:
success(bool): Whether the operation was successfulprofile(Dict): User profile information including email, name, etc.message(str): Status message
list_threads
def list_threads(
self,
query: str = "",
max_results: int = 10,
include_spam_trash: bool = False,
label_ids: Optional[List[str]] = None,
) -> Dict[str, Any]:
Retrieve email threads from Gmail.
Parameters:
- query (str): Gmail search query for threads. (default: :obj:
"") - max_results (int): Maximum number of threads to retrieve. (default: :obj:
10) - include_spam_trash (bool): Whether to include threads from spam and trash. (default: :obj:
False) - label_ids (Optional[List[str]]): List of label IDs to filter by.
Returns:
- Dict[str, Any]: A dictionary containing the result of the operation with keys:
success(bool): Whether the operation was successfulthreads(List[Dict]): List of thread objects with metadatatotal_count(int): Total number of threads foundmessage(str): Status message
fetch_thread_by_id
def fetch_thread_by_id(
self,
thread_id: str,
) -> Dict[str, Any]:
Retrieve a specific email thread by ID.
Parameters:
- thread_id (str): The ID of the thread to retrieve.
- format (Literal["minimal", "full", "metadata"]): The format of the thread to retrieve. (default: :obj:
"full")
Returns:
- Dict[str, Any]: A dictionary containing the result of the operation with keys:
success(bool): Whether the operation was successfulthread(Dict): The thread object with all messagesthread_id(str): The ID of the retrieved thread
get_tools
def get_tools(self) -> List[FunctionTool]:
Get all available Gmail tools as FunctionTool objects.
Returns:
- List[FunctionTool]: List of FunctionTool objects for all Gmail operations.
Example:
from camel.toolkits import GmailToolkit
from camel.agents import ChatAgent
# Initialize Gmail toolkit
gmail_toolkit = GmailToolkit()
# Get all tools
tools = gmail_toolkit.get_tools()
# Create an agent with Gmail tools
agent = ChatAgent(
system_message="You are a helpful Gmail assistant.",
tools=tools
)
# Use the agent
response = agent.step("Send an email to [email protected] with subject 'Meeting' and body 'Let's meet tomorrow'")
Usage Examples
Basic Email Operations
from camel.toolkits import GmailToolkit
# Initialize the toolkit
gmail = GmailToolkit()
# Send a simple email
result = gmail.send_email(
to="[email protected]",
subject="Hello from CAMEL",
body="This is a test email sent using the CAMEL Gmail toolkit."
)
# Send an HTML email with attachments
result = gmail.send_email(
to=["[email protected]", "[email protected]"],
subject="Important Update",
body="<h1>Important Update</h1><p>Please review the attached document.</p>",
cc="[email protected]",
attachments=["/path/to/document.pdf"],
is_html=True
)
# Create a draft
draft_result = gmail.create_draft(
to="[email protected]",
subject="Draft: Project Proposal",
body="Here's the initial draft of our project proposal..."
)
Message Management
# Get recent messages
messages = gmail.fetch_emails(max_results=10)
# Search for specific emails
urgent_emails = gmail.fetch_emails(query="is:unread subject:urgent")
# Get messages from a specific sender
from_sender = gmail.fetch_emails(query="from:[email protected]")
# Get message details (internal helper)
message = gmail._get_message_details("message_id_here")
# Move a message to trash
delete_result = gmail.move_to_trash("message_id_here")
Label Management
# Get all labels
labels = gmail.list_gmail_labels()
# Create a new label
new_label = gmail.create_label("Important Projects")
# Modify message labels
gmail.modify_email_labels(
message_id="message_id_here",
add_label_ids=["label_id_here"],
remove_label_ids=["INBOX"]
)
Contact Management
# Get all contacts
contacts = gmail.get_contacts()
# Search for specific contacts
search_results = gmail.search_contacts("John Smith")
# Get user profile
profile = gmail.get_profile()
Thread Management
# Get recent threads
threads = gmail.list_threads(max_results=5)
# Get a specific thread
thread = gmail.fetch_thread_by_id("thread_id_here")
# Search for threads
project_threads = gmail.get_threads(query="subject:project")
Error Handling
All methods return a dictionary with a success boolean field. Check this field to determine if the operation was successful:
result = gmail.send_email(
to="invalid-email",
subject="Test",
body="Test message"
)
if result["success"]:
print(f"Email sent successfully! Message ID: {result['message_id']}")
else:
print(f"Failed to send email: {result['message']}")
Authentication
The Gmail toolkit uses OAuth2 authentication with Google's Gmail API. This section covers the complete authentication setup and mechanisms.
Prerequisites
Before using the Gmail toolkit, you need to set up Google API credentials:
Google Cloud Console Setup:
- Go to the Google Cloud Console
- Create a new project or select an existing one
- Enable the Gmail API and Google People API
- Create OAuth 2.0 credentials (Desktop application type)
Download Credentials:
- Download the
credentials.jsonfile from the Google Cloud Console - Place it in your project directory or set the
GOOGLE_APPLICATION_CREDENTIALSenvironment variable
- Download the
Authentication Flow
The Gmail toolkit implements a multi-step OAuth2 authentication process:
1. Initial Authentication
On first use, the toolkit will:
# The authentication process happens automatically when initializing
gmail = GmailToolkit() # This triggers the OAuth flow
What happens behind the scenes:
- Loads the
credentials.jsonfile - Opens a browser window for user consent
- Requests permission for all required Gmail scopes
- Exchanges authorization code for access and refresh tokens
- Stores tokens securely in
token.jsonfor future use
2. Token Storage
The toolkit stores authentication tokens in a local token.json file:
{
"token": "ya29.a0AfH6SMC...",
"refresh_token": "1//04...",
"token_uri": "https://oauth2.googleapis.com/token",
"client_id": "your-client-id.apps.googleusercontent.com",
"client_secret": "your-client-secret",
"scopes": ["https://mail.google.com/", ...],
"expiry": "2024-01-01T12:00:00Z"
}
3. Automatic Token Refresh
The toolkit automatically handles token refresh:
- Access tokens expire after 1 hour
- Refresh tokens are used to obtain new access tokens
- Automatic refresh happens before each API call if needed
- No user intervention required after initial setup
Required Scopes
The toolkit requests the following Gmail API scopes:
| Scope | Purpose | Access Level |
|---|---|---|
https://www.googleapis.com/auth/gmail.readonly |
Read emails and metadata | Read-only |
https://www.googleapis.com/auth/gmail.send |
Send emails | Write |
https://www.googleapis.com/auth/gmail.modify |
Modify emails and labels | Write |
https://www.googleapis.com/auth/gmail.compose |
Create drafts and compose | Write |
https://www.googleapis.com/auth/gmail.labels |
Manage labels | Write |
https://www.googleapis.com/auth/contacts.readonly |
Read Google Contacts | Read-only |
https://www.googleapis.com/auth/userinfo.profile |
Access user profile | Read-only |
Environment Variables
You can configure authentication using environment variables:
# Set the path to your credentials file
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"
# Optional: Set custom token storage location
export GMAIL_TOKEN_PATH="/custom/path/token.json"
Authentication Methods
Method 1: Credentials File (Recommended)
# Place credentials.json in your project directory
gmail = GmailToolkit()
Method 2: Environment Variable
import os
os.environ['GOOGLE_APPLICATION_CREDENTIALS'] = '/path/to/credentials.json'
gmail = GmailToolkit()
Method 3: Explicit Path
# The toolkit will look for credentials.json in the current directory
# or use the path specified in GOOGLE_APPLICATION_CREDENTIALS
gmail = GmailToolkit()
Troubleshooting Authentication
Common Issues and Solutions
1. "Credentials not found" Error:
# Error: FileNotFoundError: [Errno 2] No such file or directory: 'credentials.json'
# Solution: Ensure credentials.json is in the correct location
2. "Invalid credentials" Error:
# Error: google.auth.exceptions.RefreshError: The credentials do not contain the necessary fields
# Solution: Re-download credentials.json from Google Cloud Console
3. "Access denied" Error:
# Error: googleapiclient.errors.HttpError: <HttpError 403 when requesting...>
# Solution: Check that Gmail API is enabled in Google Cloud Console
4. "Token expired" Error:
# Error: google.auth.exceptions.RefreshError: The credentials have been revoked
# Solution: Delete token.json and re-authenticate
Debug Authentication Issues
import logging
logging.basicConfig(level=logging.DEBUG)
# This will show detailed authentication logs
gmail = GmailToolkit()
Security Considerations
Token Security
- Never commit
token.jsonto version control - Use environment variables for production deployments
- Rotate credentials regularly in production
- Limit scope to only required permissions
Production Deployment
# For production, use service account credentials
# or implement your own token management system
import os
from google.oauth2 import service_account
# Load service account credentials
credentials = service_account.Credentials.from_service_account_file(
'/path/to/service-account.json',
scopes=SCOPES
)
# Use with Gmail toolkit (requires additional implementation)
Re-authentication
If you need to re-authenticate (e.g., after changing scopes):
import os
# Delete the existing token file
if os.path.exists('token.json'):
os.remove('token.json')
# Re-initialize the toolkit
gmail = GmailToolkit() # This will trigger re-authentication
Multi-User Support
For applications supporting multiple users:
# Each user needs their own token file
user_id = "user123"
token_file = f"token_{user_id}.json"
# You would need to modify the toolkit to support custom token paths
# This is an advanced use case requiring custom implementation
Best Practices
Credential Management:
- Store credentials securely
- Use environment variables in production
- Implement proper error handling
Token Handling:
- Monitor token expiration
- Implement retry logic for token refresh
- Log authentication events
Scope Management:
- Request only necessary scopes
- Regularly review and update permissions
- Document scope requirements
Error Handling:
- Handle authentication errors gracefully
- Provide clear error messages to users
- Implement fallback mechanisms
Example: Complete Authentication Setup
import os
from camel.toolkits import GmailToolkit
def setup_gmail_authentication():
"""Complete Gmail authentication setup."""
# Check if credentials file exists
if not os.path.exists('credentials.json'):
raise FileNotFoundError(
"credentials.json not found. Please download it from Google Cloud Console."
)
try:
# Initialize Gmail toolkit (triggers authentication)
gmail = GmailToolkit()
print("✓ Gmail authentication successful!")
return gmail
except Exception as e:
print(f"✗ Gmail authentication failed: {e}")
print("Please check your credentials.json file and try again.")
raise
# Usage
if __name__ == "__main__":
gmail = setup_gmail_authentication()
# Test authentication by getting user profile
profile = gmail.get_user_profile()
if profile['success']:
print(f"Authenticated as: {profile['profile']['emailAddress']}")
else:
print("Authentication test failed")
This comprehensive authentication documentation covers all aspects of setting up and using the Gmail toolkit with proper security considerations and troubleshooting guidance.