Compose and save an email to the user's draft.

* Requires permission scope for Gmail.

Args:
- to (str): The recipient's email address.
- subject (str): The subject of the email.
- body (str): The body content of the email.
- cc (str): Carbon copy recipients (optional).
- bcc (str): Blind carbon copy recipients (optional).
- is_html (bool): If True, the body content is HTML; if False, plain text.

Returns:
- dict: Success or failure message along with draft details or error.

Compose and save a reply to an existing email message in the user's Gmail draft folder.

* Requires permission scope for Gmail.

Args:
- message_id (str): The Gmail API message ID of the email you are replying to.
- body (str): The body content of the reply email.
- to (Optional[str]): The recipient's email address. If not provided, it will be extracted from the original message.
- cc (Optional[str]): Carbon copy recipients (optional).
- bcc (Optional[str]): Blind carbon copy recipients (optional).
- is_html (bool): Whether the reply is in HTML format (True) or plain text (False).

Returns:
- dict: Success or failure message along with draft details or error.

Deletes a specified Gmail draft with confirmation logic.

* Requires Gmail permission scope.

The function first checks if a confirmation token is provided.
If not, it generates a token based on the label ID.
The user must then confirm the deletion using this token.
If the token is provided, the function validates it before proceeding with the deletion.
The token is valid for a specified duration.

Args:
- draft_id (str): The ID of the draft to delete.
- confirmation_token (Optional[str]): A token to confirm deletion.

Returns:
- dict: Result message indicating success or required confirmation.

Example Corret Usage:

User: Delete draft with ID '123'
# Get a confirmation token
Action: gmail_delete_draft_tool(draft_id="123")
# Ask confirmation
Confirmation: Please confirm delete draft with id `123`.
User: Ok.
# Use token from previous request with same parameters
Action: gmail_delete_draft_tool(draft_id="123", confirmation_token="XXXXX")

Example Incorrect Usage:

Incorrect Example 1:
User: Delete draft with ID '123'
Action: gmail_delete_draft_tool(draft_id="123", confirmation_token="made up token")
What went wrong: A request to get a confirmation token was not issued and a made up token was used instead.

Incorrect Example 2:
User: Delete draft with ID '123'
# Get a confirmation token
Action: gmail_delete_draft_tool(draft_id="123")
Action: gmail_delete_draft_tool(draft_id="123", confirmation_token="XXXXX")
What went wrong: No confirmation was asked before deleting the draft.

Incorrect Example 3:
User: Delete draft with ID '123'
# Get a confirmation token
Action: gmail_delete_draft_tool(draft_id="123")
# Ask confirmation
Confirmation: Please confirm delete draft with id `123`.
User: Ok.
Action: gmail_delete_draft_tool(draft_id="456", confirmation_token="XXXXX")
What went wrong: The draft ID in the request does not match the one in the confirmation token.

Incorrect Example 4:
User: Delete draft with ID '123'
# Get a confirmation token
Action: gmail_delete_draft_tool(draft_id="123")
# Ask confirmation
Confirmation: Please confirm delete draft with id `123`.
User: Wait, I want to delete draft with ID '456' instead.
Action: gmail_delete_draft_tool(draft_id="456", confirmation_token="XXXXX")
What went wrong: The draft ID in the request does not match the one in the confirmation token. We need a new confirmation token.

Retrieve details of a specific draft by its ID.

* Requires Gmail API scope.

Args:
- draft_id (str): The ID of the draft to retrieve details for.
- prefer_html (bool, optional): Prefer HTML body if available. Defaults to False.

Returns:
- dict: Detailed draft data including subject, body, sender, recipient, and other metadata.

List all drafts in the user's Gmail account with optional label and query filters, pagination, and result limits.

* Requires Gmail API scope.

Args:
- query (str, optional): Gmail search query (e.g., 'subject:Important').
- label (str, optional): Gmail label to filter drafts (e.g., 'INBOX').
- max_results (int, optional): Number of results to return (max 100).
- page_token (str, optional): Pagination token to fetch the next page.

Returns:
- dict: Drafts data or error details.

Example Payloads:

# Example 1: Get drafts with a specific subject
gmail_list_drafts_tool(query="subject:Important", max_results=5)

# Example 2: Get drafts filtered by recipient email
gmail_list_drafts_tool(query="to:someone@example.com", max_results=5)

# Example 3: Get drafts with a specific label (if applicable)
gmail_list_drafts_tool(label="INBOX", max_results=5)

# Example 4: Get drafts with pagination - Get drafts with a specific subject, and the next page of results
gmail_list_drafts_tool(query="subject:Important", max_results=5, page_token="next_page_token")

# Example 5: Get drafts with a specific search query and a higher result limit
gmail_list_drafts_tool(query="from:someone@example.com", max_results=20)

Sends an existing draft email using Gmail API.

* Requires Gmail permission scope.

Args:
- draft_id (str): The ID of the draft to send.

Returns:
- dict: Dictionary indicating success or error.

Modify an existing draft by updating the body, subject, and recipients.
Keeps the previous values for any parameters that are not provided.

Mark multiple Gmail emails as starred or unstar them.

Requires Gmail API permission scopes.

Args:
- message_ids (List[str]): List of Gmail message IDs of the emails to modify.
- star_email (bool, optional): If True, stars the emails. If False, unstars them.

Returns:
- dict: Result of the operation, including a success message or error details.

Archives the specified Gmail emails

* Requires permission scope for Gmail.

Args:
- message_ids (List[str]): A list of Gmail message IDs for the emails to be archived.

Returns:
- dict: Result of the operation or error details.

Forward an email message with the given message ID.

* Requires permission scope for Gmail.

Args:
- message_id (str): The Gmail API message ID of the email you are forwarding.
- forward_to (str): The recipient email address to forward the message to.
- body (str): Optional message to include in the forward.
- cc (Optional[str]): Carbon copy recipients.
- bcc (Optional[str]): Blind carbon copy recipients.

Returns:
- dict: Success or error details.

Retrieve full details of a specific email by message ID.

* Requires permission scope for Gmail.

Args:
- message_id (str): The Gmail message ID to retrieve.
- prefer_html (bool, optional): Prefer HTML body if available. Defaults to False.

Returns:
- dict: Email metadata, headers, body, attachments (if available), or an error.

Fetch a list of emails from Gmail based on specified filters.

* Requires permission scope for Gmail.

Args:
- query (str, optional): Search query to filter emails (e.g., 'from:someone@example.com is:unread').
- label (str, optional): Label to filter emails by (e.g., 'STARRED', 'CATEGORY_PERSONAL', 'CATEGORY_PROMOTIONS').
- folder (str, optional): The label of the folder to filter emails by (e.g., 'INBOX', 'SENT').
- is_unread (bool, optional): If True, only show unread emails will be returned.
- max_results (int, optional): The maximum number of emails to return in a single request (default is 10, max is 100).
- page_token (str, optional): Token to retrieve the next page of results for pagination.

Returns:
- dict: A dictionary containing the list of emails and any pagination information, or an error message.

Example Payloads:

# Example 1: Get emails from a specific sender
gmail_get_emails_tool(query="from:someone@example.com", max_results=5)

# Example 2: Get unread emails from a specific label
gmail_get_emails_tool(label="CATEGORY_PROMOTIONS", is_unread=True, max_results=10)

# Example 3: Get emails sent to a specific recipient
gmail_get_emails_tool(query="to:someone@example.com", max_results=5)

# Example 4: Get emails from a specific folder
gmail_get_emails_tool(folder="INBOX", max_results=5)

# Example 5: Get emails with a specific subject
gmail_get_emails_tool(query="subject:Important Meeting", max_results=5)

# Example 6: Pagination Example - Get emails from a specific sender with pagination
gmail_get_emails_tool(query="from:someone@example.com", max_results=5, page_token="some_page_token")

# Example 7: Get unread emails sent to a specific recipient name
gmail_get_emails_tool(query="to:'John Doe' is:unread", max_results=5)

Marks multiple Gmail emails as read or unread.

Requires Gmail API permission scopes.

Args:
- message_ids (List[str]): List of Gmail message IDs of the emails.
- mark_as_read (bool): True to mark as read, False for unread.

Returns:
- dict: Result of the operation or error details.

Marks multiple Gmail emails as spam or not spam.

Requires Gmail API permission scopes.

Args:
- message_ids (List[str]): List of Gmail message IDs of the emails to modify.
- mark_as_spam (bool): If True, marks the emails as spam. If False, removes the spam label.
- new_label (str, optional): Optional label to add when unmarking the emails from spam. Default is 'INBOX'.

Returns:
- dict: Result of the operation, including a success message or error details.

Moves Gmail emails to a new folder by removing current folder labels (system/user) and adding a new one.

* Requires permission scope for Gmail.

Args:
- message_ids (List[str]): List of Gmail message IDs of the emails.
- new_folder_label (str): The new folder label to apply (e.g., 'INBOX', 'SPAM', 'TRASH').

Returns:
- dict: Result of the operation or error details.

Send a reply to an email message with the given message ID.

* Requires permission scope for Gmail.

Args:
- message_id (str): The Gmail API message ID of the email you are replying to.
- body (str): The body content of the reply email.
- cc (Optional[str]): Carbon copy recipients (optional).
- bcc (Optional[str]): Blind carbon copy recipients (optional).
- is_html (bool): Whether to send the email as HTML (default is False for plain text).

Returns:
- dict: Success or error details.

Compose and send an email to the specified recipients.

* Requires permission scope for Gmail.

Args:
- to (str): The recipient's email address.
- subject (str): The subject of the email.
- body (str): The body content of the email.
- cc (str): Carbon copy recipients (optional).
- bcc (str): Blind carbon copy recipients (optional).
- is_html (bool): Whether to send the email as HTML (default is False for plain text).

Returns:
- dict: Success or failure message along with email details or error.

Adds or removes Gmail labels to/from multiple emails based on the provided action.

Requires Gmail API permission scopes.

Args:
- message_ids (List[str]): List of Gmail message IDs of the emails to modify.
- labels (List[str]): List of Gmail label names to apply or remove. These must be valid Gmail system or custom labels.
Examples: 'IMPORTANT', 'CATEGORY_UPDATES'.
- action (str): Action to perform. 'add' to add labels, 'remove' to remove labels.

Returns:
- dict: A result object indicating success or failure, with any relevant error details from the Gmail API.

Create a new label in the user's Gmail account.

* Requires permission scope for Gmail.

Args:
- label_name (str): The name of the label to be created.

Returns:
- dict: Success or failure message along with label details or error.

Deletes a specified label from Gmail with confirmation logic.

* Requires permission scope for Gmail.

The function first checks if a confirmation token is provided.
If not, it generates a token based on the label ID.
The user must then confirm the deletion using this token.
If the token is provided, the function validates it before proceeding with the deletion.
The token is valid for a specified duration.

Args:
- label_id (str): The ID of the label to delete.
- confirmation_token (Optional[str]): An optional token to confirm the deletion. If not provided, a token will be generated based on the label ID.

Returns:
- dict: Dictionary indicating success or error.

Retrieve a list of all Gmail labels for the authenticated user.

* Requires permission scope for Gmail.

Returns:
- dict: A dictionary containing label names, IDs, or error information.

Retrieve the full conversation of a specific thread by thread ID.

* Requires permission scope for Gmail.

Args:
- thread_id (str): The Gmail thread ID to retrieve.
- format (str, optional): The format of the email content ('minimal', 'full'). Defaults to 'minimal'.

Returns:
- dict: Thread metadata, messages (or error details).