From d95ee57181a0070bcdad66fd3cb31e47bdcb72e3 Mon Sep 17 00:00:00 2001
From: Kai Koenig <kai@ventego-creative.co.nz>
Date: Wed, 13 May 2026 13:09:21 +1200
Subject: [PATCH 1/7] feat(gmail): upgrade to SDK 2.0.0 (ActionError, schema
 cleanup, version bump)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Source-side upgrade per the upgrading-sdk-v2 skill:

  * Import ActionError alongside ActionResult
  * Convert all 21 error returns from
      `return ActionResult(data={"error": str(e)}, cost_usd=0.0)`
    to
      `return ActionError(message=str(e))`
  * Drop redundant `"result": True` keys from every success-path
    return — success/failure now lives on `result.type` (ACTION_SUCCESS
    vs ACTION_ERROR) instead of a duplicated payload field
  * Strip the matching `"error"` and `"result"` properties (and
    their entries in `required`) from every action's output_schema
    in config.json — 42 schema keys removed across 21 actions
  * Harden the auth lookup (skill gotcha #9) so a missing access_token
    surfaces as an upstream auth error rather than a KeyError:
      `context.auth.get("credentials", {}).get("access_token", "")`
  * Bump config.json version 0.1.0 → 2.0.0 (major bump for the
    SDK breaking change)
  * requirements.txt: autohive-integrations-sdk~=1.0.2 → ~=2.0.0

No `context.fetch()` work needed — gmail uses Google's
`googleapiclient.discovery.build()` directly, so the FetchResponse
breaking change has no impact on the source.

Validation:
  ✅ validate_integration.py — 0 errors, 1 warning (unused-scopes
     false positive on gmail.modify)
  ✅ check_code.py — passed
  ✅ ruff check / ruff format — clean

Refs #324
---
 gmail/config.json      | 362 +++++++++++------------------------------
 gmail/gmail.py         |  83 +++++-----
 gmail/requirements.txt |   2 +-
 3 files changed, 137 insertions(+), 310 deletions(-)

diff --git a/gmail/config.json b/gmail/config.json
index 5e604c24..531f1b94 100644
--- a/gmail/config.json
+++ b/gmail/config.json
@@ -1,7 +1,7 @@
 {
     "name": "Gmail",
     "display_name": "Gmail",
-    "version": "0.1.0",
+    "version": "2.0.0",
     "description": "Send, read, and manage emails with labels and threads.",
     "entry_point": "gmail.py",
     "auth": {
@@ -53,7 +53,10 @@
                     "body_format": {
                         "type": "string",
                         "description": "Format of the reply body content. When set to 'html', the body parameter will be treated as HTML content and the reply will be sent as a rich HTML email with automatic plain text fallback for maximum compatibility. When set to 'text' (default), the body will be sent as plain text. LLMs can use 'html' to generate well-formatted replies with styling, links, tables, headers, lists, and other rich formatting elements. When using 'html' format, NEVER include CSS rule blocks (like <style> tags) in the body - instead use the 'style' attribute directly on HTML tags for styling (e.g., <p style=\"color: red;\">).",
-                        "enum": ["text", "html"],
+                        "enum": [
+                            "text",
+                            "html"
+                        ],
                         "default": "text"
                     },
                     "files": {
@@ -75,7 +78,11 @@
                                     "description": "The file content encoded as base64"
                                 }
                             },
-                            "required": ["name", "contentType", "content"]
+                            "required": [
+                                "name",
+                                "contentType",
+                                "content"
+                            ]
                         }
                     }
                 },
@@ -91,23 +98,13 @@
                     "id": {
                         "type": "string",
                         "description": "The ID of the sent reply"
-                    },
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the reply send operation"
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
                     }
                 },
                 "required": [
-                    "id",
-                    "result"
+                    "id"
                 ]
             }
         },
-
         "mark_emails_as_unread": {
             "display_name": "Mark Emails as Unread",
             "description": "Mark emails as unread",
@@ -134,22 +131,9 @@
             },
             "output_schema": {
                 "type": "object",
-                "properties": {
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the email modification"
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
-                    }
-                },
-                "required": [
-                    "result"
-                ]
+                "properties": {}
             }
         },
-
         "mark_emails_as_read": {
             "display_name": "Mark Emails as Read",
             "description": "Mark emails as read",
@@ -176,22 +160,9 @@
             },
             "output_schema": {
                 "type": "object",
-                "properties": {
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the email modification"
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
-                    }
-                },
-                "required": [
-                    "result"
-                ]
+                "properties": {}
             }
         },
-
         "get_user_info": {
             "display_name": "Get User Info",
             "description": "Get user info",
@@ -237,23 +208,13 @@
                             "threads_total",
                             "history_id"
                         ]
-                    },
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the user info"
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
                     }
                 },
                 "required": [
-                    "user_info",
-                    "result"
+                    "user_info"
                 ]
             }
         },
-
         "read_email": {
             "display_name": "Read Email",
             "description": "Read an email",
@@ -277,10 +238,6 @@
             "output_schema": {
                 "type": "object",
                 "properties": {
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the email read"
-                    },
                     "email": {
                         "type": "object",
                         "description": "The email object",
@@ -351,22 +308,20 @@
                                     "description": "The file content encoded as base64"
                                 }
                             },
-                            "required": ["name", "contentType", "content"]
+                            "required": [
+                                "name",
+                                "contentType",
+                                "content"
+                            ]
                         }
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
                     }
                 },
                 "required": [
                     "email",
-                    "result",
                     "files"
                 ]
             }
         },
-
         "send_email": {
             "display_name": "Send Email",
             "description": "Send an email",
@@ -400,7 +355,10 @@
                     "body_format": {
                         "type": "string",
                         "description": "Format of the email body content. When set to 'html', the body parameter will be treated as HTML content and the email will be sent as a rich HTML email with automatic plain text fallback for maximum compatibility. When set to 'text' (default), the body will be sent as plain text. LLMs can use 'html' to generate well-formatted emails with styling, links, tables, headers, lists, and other rich formatting elements. When using 'html' format, NEVER include CSS rule blocks (like <style> tags) in the body - instead use the 'style' attribute directly on HTML tags for styling (e.g., <p style=\"color: red;\">).",
-                        "enum": ["text", "html"],
+                        "enum": [
+                            "text",
+                            "html"
+                        ],
                         "default": "text"
                     },
                     "files": {
@@ -422,7 +380,11 @@
                                     "description": "The file content encoded as base64"
                                 }
                             },
-                            "required": ["name", "contentType", "content"]
+                            "required": [
+                                "name",
+                                "contentType",
+                                "content"
+                            ]
                         }
                     }
                 },
@@ -438,23 +400,13 @@
                     "id": {
                         "type": "string",
                         "description": "The ID of the email"
-                    },
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the email send"
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
                     }
                 },
                 "required": [
-                    "id",
-                    "result"
+                    "id"
                 ]
             }
         },
-
         "read_inbox": {
             "display_name": "Read Inbox",
             "description": "List emails in the user's inbox, filtered by read status. Results are paginated - use the nextPageToken from a previous response to retrieve the next page.",
@@ -468,7 +420,11 @@
                     "scope": {
                         "type": "string",
                         "description": "Filter emails by read status. 'all' returns all emails, 'unread' returns only unread emails, 'read' returns only emails that have been read.",
-                        "enum": ["all", "read", "unread"]
+                        "enum": [
+                            "all",
+                            "read",
+                            "unread"
+                        ]
                     },
                     "pageToken": {
                         "type": "string",
@@ -483,10 +439,6 @@
             "output_schema": {
                 "type": "object",
                 "properties": {
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the email list"
-                    },
                     "nextPageToken": {
                         "type": "string",
                         "description": "An optional parameter: The page token to get the next page of results (only present if there are more results)"
@@ -544,19 +496,13 @@
                                 "snippet"
                             ]
                         }
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
                     }
                 },
                 "required": [
-                    "emails",
-                    "result"
+                    "emails"
                 ]
             }
         },
-
         "read_all_mail": {
             "display_name": "Read All Mail",
             "description": "List all emails across the entire mailbox regardless of labels, filtered by read status. Results are paginated - use the nextPageToken from a previous response to retrieve the next page.",
@@ -570,7 +516,11 @@
                     "scope": {
                         "type": "string",
                         "description": "Filter emails by read status. 'all' returns all emails, 'unread' returns only unread emails, 'read' returns only emails that have been read.",
-                        "enum": ["all", "read", "unread"]
+                        "enum": [
+                            "all",
+                            "read",
+                            "unread"
+                        ]
                     },
                     "pageToken": {
                         "type": "string",
@@ -589,10 +539,6 @@
             "output_schema": {
                 "type": "object",
                 "properties": {
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the email list"
-                    },
                     "nextPageToken": {
                         "type": "string",
                         "description": "An optional parameter: The page token to get the next page of results (only present if there are more results)"
@@ -650,19 +596,13 @@
                                 "snippet"
                             ]
                         }
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
                     }
                 },
                 "required": [
-                    "emails",
-                    "result"
+                    "emails"
                 ]
             }
         },
-
         "list_labels": {
             "display_name": "List Gmail Labels",
             "description": "List all Gmail labels (folders) available to the user. Can filter by label type (user-created or system labels).",
@@ -676,7 +616,10 @@
                     "label_type": {
                         "type": "string",
                         "description": "Optional filter for label type. 'user' for user-created labels, 'system' for Gmail system labels (like INBOX, SENT, etc.)",
-                        "enum": ["user", "system"]
+                        "enum": [
+                            "user",
+                            "system"
+                        ]
                     }
                 },
                 "required": [
@@ -719,23 +662,13 @@
                                 "type"
                             ]
                         }
-                    },
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the label list operation"
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
                     }
                 },
                 "required": [
-                    "labels",
-                    "result"
+                    "labels"
                 ]
             }
         },
-
         "list_emails_by_label": {
             "display_name": "List Emails by Label",
             "description": "List emails that have specific Gmail labels (folders). By default, only returns emails in the inbox (excludes archived emails) unless include_archived is true or INBOX label is explicitly specified. Supports pagination and can filter by multiple labels. Uses label names (not IDs) for filtering.",
@@ -841,23 +774,13 @@
                     "nextPageToken": {
                         "type": "string",
                         "description": "An optional parameter: The page token to get the next page of results (only present if there are more results)"
-                    },
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the email list operation"
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
                     }
                 },
                 "required": [
-                    "emails",
-                    "result"
+                    "emails"
                 ]
             }
         },
-
         "add_labels_to_emails": {
             "display_name": "Add Labels to Emails",
             "description": "Add one or more labels to specified emails. This is equivalent to moving emails to folders or applying tags.",
@@ -893,22 +816,9 @@
             },
             "output_schema": {
                 "type": "object",
-                "properties": {
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the label addition operation"
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
-                    }
-                },
-                "required": [
-                    "result"
-                ]
+                "properties": {}
             }
         },
-
         "remove_labels_from_emails": {
             "display_name": "Remove Labels from Emails",
             "description": "Remove one or more labels from specified emails. This is equivalent to moving emails out of folders or removing tags.",
@@ -944,22 +854,9 @@
             },
             "output_schema": {
                 "type": "object",
-                "properties": {
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the label removal operation"
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
-                    }
-                },
-                "required": [
-                    "result"
-                ]
+                "properties": {}
             }
         },
-
         "create_label": {
             "display_name": "Create Custom Label",
             "description": "Create a new custom label (folder) in Gmail. Labels are used to organize and categorize emails.",
@@ -977,13 +874,20 @@
                     "messageListVisibility": {
                         "type": "string",
                         "description": "Whether to show messages with this label in the message list",
-                        "enum": ["show", "hide"],
+                        "enum": [
+                            "show",
+                            "hide"
+                        ],
                         "default": "show"
                     },
                     "labelListVisibility": {
                         "type": "string",
                         "description": "How to display the label in the label list",
-                        "enum": ["labelShow", "labelShowIfUnread", "labelHide"],
+                        "enum": [
+                            "labelShow",
+                            "labelShowIfUnread",
+                            "labelHide"
+                        ],
                         "default": "labelShow"
                     },
                     "textColor": {
@@ -1035,23 +939,13 @@
                             "messageListVisibility",
                             "labelListVisibility"
                         ]
-                    },
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the label creation operation"
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
                     }
                 },
                 "required": [
-                    "label",
-                    "result"
+                    "label"
                 ]
             }
         },
-
         "get_thread_emails": {
             "display_name": "Get Thread Emails",
             "description": "Get all emails in a thread, returned as snippets in chronological order",
@@ -1132,24 +1026,14 @@
                                 "snippet"
                             ]
                         }
-                    },
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the thread retrieval operation"
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
                     }
                 },
                 "required": [
                     "thread_id",
-                    "emails",
-                    "result"
+                    "emails"
                 ]
             }
         },
-
         "archive_emails": {
             "display_name": "Archive Emails",
             "description": "Archive emails by removing the INBOX label. Archived emails remain accessible but are hidden from the main inbox view.",
@@ -1176,22 +1060,9 @@
             },
             "output_schema": {
                 "type": "object",
-                "properties": {
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the email archiving operation"
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
-                    }
-                },
-                "required": [
-                    "result"
-                ]
+                "properties": {}
             }
         },
-
         "create_draft": {
             "display_name": "Create Draft",
             "description": "Create a new email draft or a draft reply to an existing email. For replies, provide thread_id and message_id - the recipient ('to'), subject, and threading headers will be automatically populated from the original message.",
@@ -1246,7 +1117,10 @@
                     "body_format": {
                         "type": "string",
                         "description": "Format of the email body content. When set to 'html', the body parameter will be treated as HTML content. When set to 'text' (default), the body will be sent as plain text.",
-                        "enum": ["text", "html"],
+                        "enum": [
+                            "text",
+                            "html"
+                        ],
                         "default": "text"
                     },
                     "files": {
@@ -1268,7 +1142,11 @@
                                     "description": "The file content encoded as base64"
                                 }
                             },
-                            "required": ["name", "contentType", "content"]
+                            "required": [
+                                "name",
+                                "contentType",
+                                "content"
+                            ]
                         }
                     }
                 },
@@ -1300,23 +1178,13 @@
                                 }
                             }
                         }
-                    },
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the draft creation operation"
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
                     }
                 },
                 "required": [
-                    "draft",
-                    "result"
+                    "draft"
                 ]
             }
         },
-
         "update_draft": {
             "display_name": "Update Draft",
             "description": "Update an existing email draft with new content, recipients, or attachments. Automatically preserves thread context for reply drafts - the threadId and threading headers (In-Reply-To, References) are maintained so the draft remains associated with its original conversation.",
@@ -1367,7 +1235,10 @@
                     "body_format": {
                         "type": "string",
                         "description": "Format of the email body content. When set to 'html', the body parameter will be treated as HTML content. When set to 'text' (default), the body will be sent as plain text.",
-                        "enum": ["text", "html"],
+                        "enum": [
+                            "text",
+                            "html"
+                        ],
                         "default": "text"
                     },
                     "files": {
@@ -1389,7 +1260,11 @@
                                     "description": "The file content encoded as base64"
                                 }
                             },
-                            "required": ["name", "contentType", "content"]
+                            "required": [
+                                "name",
+                                "contentType",
+                                "content"
+                            ]
                         }
                     }
                 },
@@ -1423,23 +1298,13 @@
                                 }
                             }
                         }
-                    },
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the draft update operation"
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
                     }
                 },
                 "required": [
-                    "draft",
-                    "result"
+                    "draft"
                 ]
             }
         },
-
         "list_drafts": {
             "display_name": "List Drafts",
             "description": "List all drafts in the user's mailbox with pagination support",
@@ -1511,23 +1376,13 @@
                     "resultSizeEstimate": {
                         "type": "integer",
                         "description": "Estimated total number of drafts"
-                    },
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the list operation"
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
                     }
                 },
                 "required": [
-                    "drafts",
-                    "result"
+                    "drafts"
                 ]
             }
         },
-
         "get_draft": {
             "display_name": "Get Draft",
             "description": "Retrieve a specific draft by ID with full content details",
@@ -1546,7 +1401,12 @@
                     "format": {
                         "type": "string",
                         "description": "The format to return the draft message in",
-                        "enum": ["minimal", "full", "raw", "metadata"],
+                        "enum": [
+                            "minimal",
+                            "full",
+                            "raw",
+                            "metadata"
+                        ],
                         "default": "full"
                     }
                 },
@@ -1632,26 +1492,20 @@
                                     "description": "The file content encoded as base64"
                                 }
                             },
-                            "required": ["name", "contentType", "content"]
+                            "required": [
+                                "name",
+                                "contentType",
+                                "content"
+                            ]
                         }
-                    },
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the get operation"
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
                     }
                 },
                 "required": [
                     "draft",
-                    "files",
-                    "result"
+                    "files"
                 ]
             }
         },
-
         "send_draft": {
             "display_name": "Send Draft",
             "description": "Send an existing draft to its recipients. The draft will be automatically deleted after sending.",
@@ -1688,23 +1542,13 @@
                                 "description": "The thread ID of the sent message"
                             }
                         }
-                    },
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the send operation"
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
                     }
                 },
                 "required": [
-                    "message",
-                    "result"
+                    "message"
                 ]
             }
         },
-
         "delete_draft": {
             "display_name": "Delete Draft",
             "description": "Permanently delete a draft from the user's mailbox",
@@ -1727,20 +1571,8 @@
             },
             "output_schema": {
                 "type": "object",
-                "properties": {
-                    "result": {
-                        "type": "boolean",
-                        "description": "The result of the delete operation"
-                    },
-                    "error": {
-                        "type": "string",
-                        "description": "Error message if the action failed"
-                    }
-                },
-                "required": [
-                    "result"
-                ]
+                "properties": {}
             }
         }
     }
-}
\ No newline at end of file
+}
diff --git a/gmail/gmail.py b/gmail/gmail.py
index 7a82589a..07b4b2b3 100644
--- a/gmail/gmail.py
+++ b/gmail/gmail.py
@@ -1,4 +1,4 @@
-from autohive_integrations_sdk import Integration, ExecutionContext, ActionHandler, ActionResult
+from autohive_integrations_sdk import Integration, ExecutionContext, ActionHandler, ActionResult, ActionError
 
 from typing import Dict, Any
 from email.mime.text import MIMEText
@@ -169,7 +169,7 @@ def build_credentials(context: ExecutionContext):
         Google credentials object
     """
     # Extract access token from context.auth.credentials
-    access_token = context.auth["credentials"]["access_token"]
+    access_token = context.auth.get("credentials", {}).get("access_token", "")
 
     creds = Credentials(token=access_token, token_uri="https://oauth2.googleapis.com/token")  # nosec B106
 
@@ -359,10 +359,10 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
             request = service.users().messages().batchModify(userId=user_id, body=body)
             request.execute()
 
-            return ActionResult(data={"result": True}, cost_usd=0.0)
+            return ActionResult(data={}, cost_usd=0.0)
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
 
 
 @gmail.action("mark_emails_as_read")
@@ -378,10 +378,10 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
             request = service.users().messages().batchModify(userId=user_id, body=body)
             request.execute()
 
-            return ActionResult(data={"result": True}, cost_usd=0.0)
+            return ActionResult(data={}, cost_usd=0.0)
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
 
 
 @gmail.action("get_user_info")
@@ -402,13 +402,12 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
                         "threads_total": result["threadsTotal"],
                         "history_id": result["historyId"],
                     },
-                    "result": True,
                 },
                 cost_usd=0.0,
             )
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
 
 
 @gmail.action("read_email")
@@ -430,10 +429,10 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
                 service, user_id, message_data["id"], message_data["payload"]
             )
 
-            return ActionResult(data={"email": email_object, "files": extracted_files, "result": True}, cost_usd=0.0)
+            return ActionResult(data={"email": email_object, "files": extracted_files}, cost_usd=0.0)
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
 
 
 @gmail.action("send_email")
@@ -452,10 +451,10 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
             request = service.users().messages().send(userId=user_id, body=message)
             response = request.execute()
 
-            return ActionResult(data={"id": response.get("id", ""), "result": True}, cost_usd=0.0)
+            return ActionResult(data={"id": response.get("id", "")}, cost_usd=0.0)
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
 
     def _create_raw_email(self, inputs: Dict[str, Any]) -> str:
         """Create base64 encoded email message."""
@@ -546,10 +545,10 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
             request = service.users().messages().send(userId=user_id, body=message_payload)
             response = request.execute()
 
-            return ActionResult(data={"id": response.get("id", ""), "result": True}, cost_usd=0.0)
+            return ActionResult(data={"id": response.get("id", "")}, cost_usd=0.0)
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
 
 
 @gmail.action("read_inbox")
@@ -586,7 +585,7 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
                 inbox_emails.append(GmailMessageParser.parse_message_with_snippet(email_with_id))
 
             # Prepare response with pagination support
-            response = {"emails": inbox_emails, "result": True}
+            response = {"emails": inbox_emails}
 
             # Add nextPageToken if present in Gmail API response
             if "nextPageToken" in messages:
@@ -595,7 +594,7 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
             return ActionResult(data=response, cost_usd=0.0)
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
 
 
 @gmail.action("read_all_mail")
@@ -635,7 +634,7 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
                 all_emails.append(GmailMessageParser.parse_message_with_snippet(email_with_id))
 
             # Prepare response with pagination support
-            response = {"emails": all_emails, "result": True}
+            response = {"emails": all_emails}
 
             # Add nextPageToken if present in Gmail API response
             if "nextPageToken" in messages:
@@ -644,7 +643,7 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
             return ActionResult(data=response, cost_usd=0.0)
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
 
 
 @gmail.action("list_labels")
@@ -668,10 +667,10 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
                 elif label_type == "system":
                     labels = [label for label in labels if label.get("type") == "system"]
 
-            return ActionResult(data={"labels": labels, "result": True}, cost_usd=0.0)
+            return ActionResult(data={"labels": labels}, cost_usd=0.0)
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
 
 
 @gmail.action("list_emails_by_label")
@@ -723,7 +722,7 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
                 emails.append(GmailMessageParser.parse_message_with_snippet(email_with_id))
 
             # Prepare response with pagination support
-            response = {"emails": emails, "result": True}
+            response = {"emails": emails}
 
             # Add nextPageToken if present in Gmail API response
             if "nextPageToken" in messages:
@@ -732,7 +731,7 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
             return ActionResult(data=response, cost_usd=0.0)
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
 
 
 @gmail.action("add_labels_to_emails")
@@ -749,10 +748,10 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
             request = service.users().messages().batchModify(userId=user_id, body=body)
             request.execute()
 
-            return ActionResult(data={"result": True}, cost_usd=0.0)
+            return ActionResult(data={}, cost_usd=0.0)
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
 
 
 @gmail.action("remove_labels_from_emails")
@@ -769,10 +768,10 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
             request = service.users().messages().batchModify(userId=user_id, body=body)
             request.execute()
 
-            return ActionResult(data={"result": True}, cost_usd=0.0)
+            return ActionResult(data={}, cost_usd=0.0)
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
 
 
 @gmail.action("create_label")
@@ -811,13 +810,12 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
                         "messageListVisibility": created_label.get("messageListVisibility", "show"),
                         "labelListVisibility": created_label.get("labelListVisibility", "labelShow"),
                     },
-                    "result": True,
                 },
                 cost_usd=0.0,
             )
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
 
 
 @gmail.action("get_thread_emails")
@@ -852,10 +850,10 @@ def parse_date_for_sorting(email):
 
             thread_emails.sort(key=parse_date_for_sorting)
 
-            return ActionResult(data={"thread_id": thread_id, "emails": thread_emails, "result": True}, cost_usd=0.0)
+            return ActionResult(data={"thread_id": thread_id, "emails": thread_emails}, cost_usd=0.0)
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
 
 
 @gmail.action("archive_emails")
@@ -871,10 +869,10 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
             request = service.users().messages().batchModify(userId=user_id, body=body)
             request.execute()
 
-            return ActionResult(data={"result": True}, cost_usd=0.0)
+            return ActionResult(data={}, cost_usd=0.0)
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
 
 
 @gmail.action("create_draft")
@@ -958,13 +956,12 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
                             "threadId": response.get("message", {}).get("threadId", ""),
                         },
                     },
-                    "result": True,
                 },
                 cost_usd=0.0,
             )
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
 
     def _create_raw_email(self, inputs: Dict[str, Any], message_id_header: str = None, references: str = None) -> str:
         """Create base64 encoded email message for draft."""
@@ -1067,13 +1064,12 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
                             "threadId": response.get("message", {}).get("threadId", ""),
                         },
                     },
-                    "result": True,
                 },
                 cost_usd=0.0,
             )
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
 
     def _create_raw_email(self, inputs: Dict[str, Any], message_id_header: str = None, references: str = None) -> str:
         """Create base64 encoded email message for draft."""
@@ -1157,7 +1153,7 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
             drafts = response.get("drafts", [])
 
             # Prepare response with pagination support
-            result = {"drafts": drafts, "result": True}
+            result = {"drafts": drafts}
 
             # Add pagination info if present
             if "nextPageToken" in response:
@@ -1169,7 +1165,7 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
             return ActionResult(data=result, cost_usd=0.0)
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
 
 
 @gmail.action("get_draft")
@@ -1223,10 +1219,10 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
                         service, user_id, message_data["id"], message_data["payload"]
                     )
 
-            return ActionResult(data={"draft": draft_info, "files": extracted_files, "result": True}, cost_usd=0.0)
+            return ActionResult(data={"draft": draft_info, "files": extracted_files}, cost_usd=0.0)
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
 
 
 @gmail.action("send_draft")
@@ -1245,13 +1241,12 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
             return ActionResult(
                 data={
                     "message": {"id": response.get("id", ""), "threadId": response.get("threadId", "")},
-                    "result": True,
                 },
                 cost_usd=0.0,
             )
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
 
 
 @gmail.action("delete_draft")
@@ -1266,7 +1261,7 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
             request = service.users().drafts().delete(userId=user_id, id=draft_id)
             request.execute()
 
-            return ActionResult(data={"result": True}, cost_usd=0.0)
+            return ActionResult(data={}, cost_usd=0.0)
 
         except Exception as e:
-            return ActionResult(data={"error": str(e)}, cost_usd=0.0)
+            return ActionError(message=str(e))
diff --git a/gmail/requirements.txt b/gmail/requirements.txt
index ff5185cc..f6e6ab4b 100644
--- a/gmail/requirements.txt
+++ b/gmail/requirements.txt
@@ -1,4 +1,4 @@
-autohive-integrations-sdk~=1.0.2
+autohive-integrations-sdk~=2.0.0
 google-api-python-client
 google-auth-httplib2
 google-auth-oauthlib

From 6475b607850e59bae53ca18b9f4eacb5ac4cb52c Mon Sep 17 00:00:00 2001
From: Kai Koenig <kai@ventego-creative.co.nz>
Date: Wed, 13 May 2026 13:09:47 +1200
Subject: [PATCH 2/7] chore(gmail): replace tests scaffolding with conftest.py

Removes the legacy `tests/context.py` shim and the placeholder
`test_gmail.py`, replaces them with a `tests/conftest.py` that
matches the current writing-unit-tests skill conventions:

  * sys.path setup so test files can use plain `from gmail import gmail`
  * mock_context fixture override pre-loaded with the
    PlatformOauth2 envelope Gmail expects, so every test in this
    directory inherits credentials of the right shape

Refs #324
---
 gmail/tests/conftest.py   | 26 ++++++++++++++++++++++++++
 gmail/tests/context.py    |  5 -----
 gmail/tests/test_gmail.py |  6 ------
 3 files changed, 26 insertions(+), 11 deletions(-)
 create mode 100644 gmail/tests/conftest.py
 delete mode 100644 gmail/tests/context.py
 delete mode 100644 gmail/tests/test_gmail.py

diff --git a/gmail/tests/conftest.py b/gmail/tests/conftest.py
new file mode 100644
index 00000000..9c49aad3
--- /dev/null
+++ b/gmail/tests/conftest.py
@@ -0,0 +1,26 @@
+import os
+import sys
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+# Make gmail.py importable as a top-level module.
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+
+@pytest.fixture
+def mock_context():
+    """Mock ExecutionContext pre-loaded with the platform-OAuth shape Gmail expects.
+
+    Gmail uses platform OAuth (config.auth.type == "platform") so the SDK wraps
+    the access token in {"auth_type": "PlatformOauth2", "credentials": {...}}.
+    """
+    ctx = MagicMock(name="ExecutionContext")
+    # gmail uses googleapiclient directly (not context.fetch), but unit tests
+    # still receive an AsyncMock for fetch so the standard fixture contract holds.
+    ctx.fetch = AsyncMock(name="fetch")
+    ctx.auth = {
+        "auth_type": "PlatformOauth2",
+        "credentials": {"access_token": "test_access_token"},  # nosec B105
+    }
+    return ctx
diff --git a/gmail/tests/context.py b/gmail/tests/context.py
deleted file mode 100644
index 27343b77..00000000
--- a/gmail/tests/context.py
+++ /dev/null
@@ -1,5 +0,0 @@
-import os
-import sys
-
-sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
-from gmail import gmail  # noqa: F401
diff --git a/gmail/tests/test_gmail.py b/gmail/tests/test_gmail.py
deleted file mode 100644
index 77e0900d..00000000
--- a/gmail/tests/test_gmail.py
+++ /dev/null
@@ -1,6 +0,0 @@
-import context  # noqa: F401
-
-
-def test_placeholder():
-    """Placeholder test — replace with real tests."""
-    pass

From 91730468e085a30aac19183d1c8cbb56c7c121d3 Mon Sep 17 00:00:00 2001
From: Kai Koenig <kai@ventego-creative.co.nz>
Date: Wed, 13 May 2026 13:19:45 +1200
Subject: [PATCH 3/7] test(gmail): add unit test suite covering all 21 actions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds gmail/tests/test_gmail_unit.py with 56 tests covering the full
integration surface:

  * 7 helper tests for create_email_message:
    - plain text body, plain text + attachments
    - HTML body sanitisation (script tags stripped, javascript:
      protocol blocked, allowed tags preserved)
    - multipart/alternative structure with text+html parts
    - multipart/mixed structure for HTML + attachments

  * 1 service-build test (verifies hardened auth lookup does not
    KeyError on missing access_token)

  * 48 action tests across all 21 actions:
    - mark_emails_as_read, mark_emails_as_unread, archive_emails
    - get_user_info, read_email
    - read_inbox (default scope, unread scope -> Gmail q filter,
      pagination round-trip)
    - read_all_mail
    - send_email (text, HTML sanitised, exception path)
    - reply_to_thread (with original message header lookup)
    - list_labels, create_label
    - add_labels_to_emails, remove_labels_from_emails
    - list_emails_by_label
    - get_thread_emails
    - create_draft (new draft + reply-mode with thread/message id)
    - update_draft, list_drafts, get_draft, send_draft, delete_draft

Each action gets at minimum:
  * Happy path (verifies result.type == ResultType.ACTION + key data)
  * Exception path (verifies result.type == ResultType.ACTION_ERROR
    + the original error message is preserved on the ActionError)
  * Request-shape verification where it adds value (label add/remove
    body, query filters, threading IDs)

Mock pattern note: Gmail uses googleapiclient.discovery.build directly
rather than context.fetch, so the standard mock_context.fetch fixture
is not the right tool. Tests use `patch("gmail.gmail.build")` to
inject a MagicMock service that mimics the chained
service.users().messages().<verb>().execute() pattern.

Validation:
  ✅ 56 tests pass
  ✅ ruff check / ruff format (with tooling ruff.toml) — clean
  ✅ validate_integration.py — 0 errors
  ✅ check_code.py — passed

Refs #324
---
 gmail/tests/test_gmail_unit.py | 861 +++++++++++++++++++++++++++++++++
 1 file changed, 861 insertions(+)
 create mode 100644 gmail/tests/test_gmail_unit.py

diff --git a/gmail/tests/test_gmail_unit.py b/gmail/tests/test_gmail_unit.py
new file mode 100644
index 00000000..f9e896c0
--- /dev/null
+++ b/gmail/tests/test_gmail_unit.py
@@ -0,0 +1,861 @@
+"""Unit tests for the Gmail integration.
+
+Gmail uses Google's googleapiclient (`googleapiclient.discovery.build`)
+directly rather than the SDK's `context.fetch`, so these tests mock
+the `build` call to return a configured MagicMock service.
+"""
+
+import base64
+from unittest.mock import MagicMock, patch
+
+import pytest
+from autohive_integrations_sdk import FetchResponse  # noqa: F401  (kept for SDK 2.0 contract)
+from autohive_integrations_sdk.integration import ResultType
+
+from gmail.gmail import gmail, create_email_message
+
+pytestmark = pytest.mark.unit
+
+
+# ============================================================
+#  Helpers
+# ============================================================
+
+
+def _make_service():
+    """Build a fresh MagicMock that mimics the Google service chain."""
+    return MagicMock(name="GmailService")
+
+
+def _patched_service():
+    """Context manager: patches gmail.gmail.build to return a fresh mock service."""
+    return patch("gmail.gmail.build")
+
+
+def _decoded_text(msg):
+    """Walk a MIME message and return the concatenated decoded body text."""
+    chunks = []
+    if msg.is_multipart():
+        for part in msg.walk():
+            if part.get_content_maintype() == "multipart":
+                continue
+            payload = part.get_payload(decode=True)
+            if payload:
+                chunks.append(payload.decode("utf-8", errors="replace"))
+    else:
+        payload = msg.get_payload(decode=True)
+        if payload:
+            chunks.append(payload.decode("utf-8", errors="replace"))
+    return "\n".join(chunks)
+
+
+# ============================================================
+#  Module-level helper tests
+# ============================================================
+
+
+class TestCreateEmailMessage:
+    """Tests for the create_email_message helper."""
+
+    def test_plain_text_body(self):
+        msg = create_email_message("Hello world", files=None, is_html=False)
+        # Plain-text path returns a MIMEText, not multipart, when no files
+        assert msg.get_content_type() == "text/plain"
+        assert "Hello world" in _decoded_text(msg)
+
+    def test_plain_text_with_attachments_is_multipart(self):
+        files = [
+            {
+                "name": "test.txt",
+                "contentType": "text/plain",
+                "content": base64.b64encode(b"file contents").decode(),
+            }
+        ]
+        msg = create_email_message("Body", files=files, is_html=False)
+        assert msg.is_multipart()
+        # First part is the body, second is the attachment
+        parts = msg.get_payload()
+        assert len(parts) == 2
+
+    def test_html_body_sanitises_script_tag(self):
+        body = "<p>Safe</p><script>alert(1)</script><p>Also safe</p>"
+        msg = create_email_message(body, files=None, is_html=True)
+        rendered = _decoded_text(msg)
+        assert "<script>" not in rendered
+        assert "Safe" in rendered
+
+    def test_html_body_strips_disallowed_protocol(self):
+        body = '<a href="javascript:alert(1)">click</a>'
+        msg = create_email_message(body, files=None, is_html=True)
+        rendered = _decoded_text(msg)
+        assert "javascript:" not in rendered
+
+    def test_html_body_keeps_allowed_tags(self):
+        body = "<p><strong>Bold</strong> and <em>italic</em></p>"
+        msg = create_email_message(body, files=None, is_html=True)
+        rendered = _decoded_text(msg)
+        assert "<strong>" in rendered
+        assert "<em>" in rendered
+
+    def test_html_body_includes_plain_text_alternative(self):
+        body = "<p>HTML body</p>"
+        msg = create_email_message(body, files=None, is_html=True)
+        # Multipart/alternative with text + html
+        assert msg.is_multipart()
+        content_types = [p.get_content_type() for p in msg.walk() if p.get_content_type() != "multipart/alternative"]
+        assert "text/plain" in content_types
+        assert "text/html" in content_types
+
+    def test_html_body_with_attachments_is_mixed_multipart(self):
+        files = [
+            {
+                "name": "a.pdf",
+                "contentType": "application/pdf",
+                "content": base64.b64encode(b"PDFDATA").decode(),
+            }
+        ]
+        msg = create_email_message("<p>Hello</p>", files=files, is_html=True)
+        # Outer container is multipart/mixed; should walk into alternative + attachment
+        assert msg.get_content_type() == "multipart/mixed"
+
+
+# ============================================================
+#  Auth & service-build tests
+# ============================================================
+
+
+class TestBuildGmailService:
+    """Tests for build_credentials / build_gmail_service via build patching."""
+
+    @pytest.mark.asyncio
+    async def test_missing_token_does_not_crash(self, mock_context):
+        """A missing access_token must not raise KeyError thanks to the
+        hardened lookup; instead the upstream Gmail call fails and is
+        returned as ActionError."""
+        mock_context.auth = {}  # no credentials
+        with _patched_service() as mock_build:
+            mock_build.side_effect = Exception("Invalid credentials")
+            result = await gmail.execute_action("get_user_info", {"user_id": "me"}, mock_context)
+        assert result.type == ResultType.ACTION_ERROR
+
+
+# ============================================================
+#  Mark / Archive actions (void success)
+# ============================================================
+
+
+class TestMarkEmailsAsRead:
+    @pytest.mark.asyncio
+    async def test_happy_path_returns_empty_data(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().messages().batchModify().execute.return_value = None
+            result = await gmail.execute_action(
+                "mark_emails_as_read", {"user_id": "me", "ids": ["m1", "m2"]}, mock_context
+            )
+        assert result.type == ResultType.ACTION
+        assert result.result.data == {}
+
+    @pytest.mark.asyncio
+    async def test_request_uses_remove_unread_label(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            await gmail.execute_action("mark_emails_as_read", {"user_id": "me", "ids": ["m1"]}, mock_context)
+        call = service.users().messages().batchModify.call_args
+        assert call.kwargs["userId"] == "me"
+        assert call.kwargs["body"]["removeLabelIds"] == ["UNREAD"]
+        assert call.kwargs["body"]["addLabelIds"] == []
+        assert call.kwargs["body"]["ids"] == ["m1"]
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().messages().batchModify().execute.side_effect = Exception("HTTP 500")
+            result = await gmail.execute_action("mark_emails_as_read", {"user_id": "me", "ids": ["m1"]}, mock_context)
+        assert result.type == ResultType.ACTION_ERROR
+        assert "HTTP 500" in result.result.message
+
+
+class TestMarkEmailsAsUnread:
+    @pytest.mark.asyncio
+    async def test_request_uses_add_unread_label(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            result = await gmail.execute_action("mark_emails_as_unread", {"user_id": "me", "ids": ["m1"]}, mock_context)
+        assert result.type == ResultType.ACTION
+        call = service.users().messages().batchModify.call_args
+        assert call.kwargs["body"]["addLabelIds"] == ["UNREAD"]
+        assert call.kwargs["body"]["removeLabelIds"] == []
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().messages().batchModify().execute.side_effect = Exception("boom")
+            result = await gmail.execute_action("mark_emails_as_unread", {"user_id": "me", "ids": ["m1"]}, mock_context)
+        assert result.type == ResultType.ACTION_ERROR
+
+
+class TestArchiveEmails:
+    @pytest.mark.asyncio
+    async def test_request_removes_inbox_label(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            result = await gmail.execute_action("archive_emails", {"user_id": "me", "ids": ["m1", "m2"]}, mock_context)
+        assert result.type == ResultType.ACTION
+        call = service.users().messages().batchModify.call_args
+        assert call.kwargs["body"]["removeLabelIds"] == ["INBOX"]
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().messages().batchModify().execute.side_effect = Exception("nope")
+            result = await gmail.execute_action("archive_emails", {"user_id": "me", "ids": ["m1"]}, mock_context)
+        assert result.type == ResultType.ACTION_ERROR
+
+
+# ============================================================
+#  Profile & read actions
+# ============================================================
+
+
+class TestGetUserInfo:
+    @pytest.mark.asyncio
+    async def test_returns_profile_fields(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().getProfile().execute.return_value = {
+                "emailAddress": "kai@example.com",
+                "messagesTotal": 42,
+                "threadsTotal": 17,
+                "historyId": "12345",
+            }
+            result = await gmail.execute_action("get_user_info", {"user_id": "me"}, mock_context)
+        assert result.type == ResultType.ACTION
+        info = result.result.data["user_info"]
+        assert info["email_address"] == "kai@example.com"
+        assert info["messages_total"] == 42
+        assert info["history_id"] == "12345"
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().getProfile().execute.side_effect = Exception("auth failed")
+            result = await gmail.execute_action("get_user_info", {"user_id": "me"}, mock_context)
+        assert result.type == ResultType.ACTION_ERROR
+        assert "auth failed" in result.result.message
+
+
+def _sample_message(msg_id="m1", thread_id="t1", subject="Hello", body="Body text"):
+    """Build a minimal Gmail API message payload."""
+    return {
+        "id": msg_id,
+        "threadId": thread_id,
+        "labelIds": ["INBOX", "UNREAD"],
+        "snippet": "snippet",
+        "internalDate": "1700000000000",
+        "payload": {
+            "headers": [
+                {"name": "From", "value": "sender@example.com"},
+                {"name": "To", "value": "me@example.com"},
+                {"name": "Subject", "value": subject},
+                {"name": "Date", "value": "Mon, 1 Jan 2024 10:00:00 +0000"},
+            ],
+            "mimeType": "text/plain",
+            "body": {"data": base64.urlsafe_b64encode(body.encode()).decode()},
+            "parts": [],
+        },
+    }
+
+
+class TestReadEmail:
+    @pytest.mark.asyncio
+    async def test_returns_email_object(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().messages().get().execute.return_value = _sample_message()
+            result = await gmail.execute_action("read_email", {"user_id": "me", "email_id": "m1"}, mock_context)
+        assert result.type == ResultType.ACTION
+        assert "email" in result.result.data
+        assert "files" in result.result.data
+        assert result.result.data["email"]["id"] == "m1"
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().messages().get().execute.side_effect = Exception("not found")
+            result = await gmail.execute_action("read_email", {"user_id": "me", "email_id": "missing"}, mock_context)
+        assert result.type == ResultType.ACTION_ERROR
+
+
+class TestReadInbox:
+    @pytest.mark.asyncio
+    async def test_returns_emails_list(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().messages().list().execute.return_value = {"messages": [{"id": "m1"}, {"id": "m2"}]}
+            service.users().messages().get().execute.side_effect = [
+                _sample_message(msg_id="m1"),
+                _sample_message(msg_id="m2"),
+            ]
+            result = await gmail.execute_action("read_inbox", {"user_id": "me", "scope": "all"}, mock_context)
+        assert result.type == ResultType.ACTION
+        assert "emails" in result.result.data
+        assert len(result.result.data["emails"]) == 2
+
+    @pytest.mark.asyncio
+    async def test_unread_scope_uses_query_filter(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().messages().list().execute.return_value = {"messages": []}
+            await gmail.execute_action("read_inbox", {"user_id": "me", "scope": "unread"}, mock_context)
+        # Gmail uses the `q` query param ('is:unread in:inbox') rather than
+        # the labelIds endpoint to filter unread inbox messages.
+        call = service.users().messages().list.call_args
+        assert "is:unread" in call.kwargs["q"]
+        assert "in:inbox" in call.kwargs["q"]
+
+    @pytest.mark.asyncio
+    async def test_next_page_token_propagated(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().messages().list().execute.return_value = {
+                "messages": [],
+                "nextPageToken": "token-abc",
+            }
+            result = await gmail.execute_action("read_inbox", {"user_id": "me", "scope": "all"}, mock_context)
+        assert result.result.data["nextPageToken"] == "token-abc"
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().messages().list().execute.side_effect = Exception("rate limited")
+            result = await gmail.execute_action("read_inbox", {"user_id": "me", "scope": "all"}, mock_context)
+        assert result.type == ResultType.ACTION_ERROR
+
+
+class TestReadAllMail:
+    @pytest.mark.asyncio
+    async def test_returns_emails_list(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().messages().list().execute.return_value = {"messages": [{"id": "m1"}]}
+            service.users().messages().get().execute.return_value = _sample_message()
+            result = await gmail.execute_action("read_all_mail", {"user_id": "me", "scope": "all"}, mock_context)
+        assert result.type == ResultType.ACTION
+        assert len(result.result.data["emails"]) == 1
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().messages().list().execute.side_effect = Exception("error")
+            result = await gmail.execute_action("read_all_mail", {"user_id": "me", "scope": "all"}, mock_context)
+        assert result.type == ResultType.ACTION_ERROR
+
+
+# ============================================================
+#  Send / reply actions
+# ============================================================
+
+
+class TestSendEmail:
+    @pytest.mark.asyncio
+    async def test_returns_message_id_on_success(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().messages().send().execute.return_value = {"id": "sent-1"}
+            result = await gmail.execute_action(
+                "send_email",
+                {"to": ["bob@example.com"], "subject": "Hi", "body": "Hello"},
+                mock_context,
+            )
+        assert result.type == ResultType.ACTION
+        assert result.result.data["id"] == "sent-1"
+
+    @pytest.mark.asyncio
+    async def test_html_body_sanitised(self, mock_context):
+        import email
+
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().messages().send().execute.return_value = {"id": "sent-1"}
+            await gmail.execute_action(
+                "send_email",
+                {
+                    "to": ["bob@example.com"],
+                    "subject": "Hi",
+                    "body": "<script>alert(1)</script><p>Safe</p>",
+                    "body_format": "html",
+                },
+                mock_context,
+            )
+        # Decode the raw email payload sent to Gmail and walk its parts
+        call = service.users().messages().send.call_args
+        raw_b64 = call.kwargs["body"]["raw"]
+        raw_bytes = base64.urlsafe_b64decode(raw_b64.encode())
+        msg = email.message_from_bytes(raw_bytes)
+        rendered = _decoded_text(msg)
+        assert "<script>" not in rendered
+        assert "Safe" in rendered
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().messages().send().execute.side_effect = Exception("rejected")
+            result = await gmail.execute_action(
+                "send_email",
+                {"to": ["bob@example.com"], "subject": "Hi", "body": "Hello"},
+                mock_context,
+            )
+        assert result.type == ResultType.ACTION_ERROR
+
+
+class TestReplyToThread:
+    @pytest.mark.asyncio
+    async def test_returns_id_on_success(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            # First the original message is fetched for headers
+            service.users().messages().get().execute.return_value = _sample_message()
+            service.users().messages().send().execute.return_value = {"id": "reply-1"}
+            result = await gmail.execute_action(
+                "reply_to_thread",
+                {
+                    "thread_id": "t1",
+                    "message_id": "m1",
+                    "body": "Reply body",
+                    "to": [],
+                    "cc": [],
+                },
+                mock_context,
+            )
+        assert result.type == ResultType.ACTION
+        assert result.result.data["id"] == "reply-1"
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().messages().get().execute.side_effect = Exception("bad thread")
+            result = await gmail.execute_action(
+                "reply_to_thread",
+                {
+                    "thread_id": "t1",
+                    "message_id": "m1",
+                    "body": "Reply",
+                    "to": [],
+                    "cc": [],
+                },
+                mock_context,
+            )
+        assert result.type == ResultType.ACTION_ERROR
+
+
+# ============================================================
+#  Label actions
+# ============================================================
+
+
+class TestListLabels:
+    @pytest.mark.asyncio
+    async def test_returns_labels_list(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().labels().list().execute.return_value = {
+                "labels": [
+                    {"id": "INBOX", "name": "INBOX", "type": "system"},
+                    {"id": "Label_1", "name": "MyLabel", "type": "user"},
+                ]
+            }
+            result = await gmail.execute_action("list_labels", {"user_id": "me"}, mock_context)
+        assert result.type == ResultType.ACTION
+        assert len(result.result.data["labels"]) == 2
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().labels().list().execute.side_effect = Exception("boom")
+            result = await gmail.execute_action("list_labels", {"user_id": "me"}, mock_context)
+        assert result.type == ResultType.ACTION_ERROR
+
+
+class TestCreateLabel:
+    @pytest.mark.asyncio
+    async def test_returns_created_label(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().labels().create().execute.return_value = {
+                "id": "Label_99",
+                "name": "Project X",
+                "type": "user",
+                "messageListVisibility": "show",
+                "labelListVisibility": "labelShow",
+            }
+            result = await gmail.execute_action("create_label", {"user_id": "me", "name": "Project X"}, mock_context)
+        assert result.type == ResultType.ACTION
+        assert result.result.data["label"]["id"] == "Label_99"
+        assert result.result.data["label"]["name"] == "Project X"
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().labels().create().execute.side_effect = Exception("dup")
+            result = await gmail.execute_action("create_label", {"user_id": "me", "name": "X"}, mock_context)
+        assert result.type == ResultType.ACTION_ERROR
+
+
+class TestAddLabelsToEmails:
+    @pytest.mark.asyncio
+    async def test_request_adds_labels(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            result = await gmail.execute_action(
+                "add_labels_to_emails",
+                {"user_id": "me", "message_ids": ["m1"], "label_ids": ["Label_1"]},
+                mock_context,
+            )
+        assert result.type == ResultType.ACTION
+        call = service.users().messages().batchModify.call_args
+        assert call.kwargs["body"]["addLabelIds"] == ["Label_1"]
+        assert call.kwargs["body"]["removeLabelIds"] == []
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().messages().batchModify().execute.side_effect = Exception("err")
+            result = await gmail.execute_action(
+                "add_labels_to_emails",
+                {"user_id": "me", "message_ids": ["m1"], "label_ids": ["L1"]},
+                mock_context,
+            )
+        assert result.type == ResultType.ACTION_ERROR
+
+
+class TestRemoveLabelsFromEmails:
+    @pytest.mark.asyncio
+    async def test_request_removes_labels(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            result = await gmail.execute_action(
+                "remove_labels_from_emails",
+                {"user_id": "me", "message_ids": ["m1"], "label_ids": ["Label_1"]},
+                mock_context,
+            )
+        assert result.type == ResultType.ACTION
+        call = service.users().messages().batchModify.call_args
+        assert call.kwargs["body"]["removeLabelIds"] == ["Label_1"]
+        assert call.kwargs["body"]["addLabelIds"] == []
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().messages().batchModify().execute.side_effect = Exception("err")
+            result = await gmail.execute_action(
+                "remove_labels_from_emails",
+                {"user_id": "me", "message_ids": ["m1"], "label_ids": ["L1"]},
+                mock_context,
+            )
+        assert result.type == ResultType.ACTION_ERROR
+
+
+class TestListEmailsByLabel:
+    @pytest.mark.asyncio
+    async def test_returns_emails_for_label(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().messages().list().execute.return_value = {"messages": [{"id": "m1"}]}
+            service.users().messages().get().execute.return_value = _sample_message()
+            result = await gmail.execute_action(
+                "list_emails_by_label",
+                {"user_id": "me", "label_names": ["MyLabel"]},
+                mock_context,
+            )
+        assert result.type == ResultType.ACTION
+        assert len(result.result.data["emails"]) == 1
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().messages().list().execute.side_effect = Exception("bad label")
+            result = await gmail.execute_action(
+                "list_emails_by_label",
+                {"user_id": "me", "label_names": ["MyLabel"]},
+                mock_context,
+            )
+        assert result.type == ResultType.ACTION_ERROR
+
+
+# ============================================================
+#  Thread actions
+# ============================================================
+
+
+class TestGetThreadEmails:
+    @pytest.mark.asyncio
+    async def test_returns_thread_emails(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().threads().get().execute.return_value = {
+                "id": "t1",
+                "messages": [_sample_message(msg_id="m1"), _sample_message(msg_id="m2")],
+            }
+            result = await gmail.execute_action("get_thread_emails", {"user_id": "me", "thread_id": "t1"}, mock_context)
+        assert result.type == ResultType.ACTION
+        assert result.result.data["thread_id"] == "t1"
+        assert len(result.result.data["emails"]) == 2
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().threads().get().execute.side_effect = Exception("not found")
+            result = await gmail.execute_action("get_thread_emails", {"user_id": "me", "thread_id": "t1"}, mock_context)
+        assert result.type == ResultType.ACTION_ERROR
+
+
+# ============================================================
+#  Draft actions
+# ============================================================
+
+
+class TestCreateDraft:
+    @pytest.mark.asyncio
+    async def test_returns_draft_id_on_success(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().getProfile().execute.return_value = {"emailAddress": "me@example.com"}
+            service.users().drafts().create().execute.return_value = {
+                "id": "draft-1",
+                "message": {"id": "msg-1", "threadId": "thr-1"},
+            }
+            result = await gmail.execute_action(
+                "create_draft",
+                {"to": ["bob@example.com"], "subject": "Draft", "body": "hi"},
+                mock_context,
+            )
+        assert result.type == ResultType.ACTION
+        assert result.result.data["draft"]["id"] == "draft-1"
+
+    @pytest.mark.asyncio
+    async def test_reply_mode_pulls_original_message_headers(self, mock_context):
+        """When thread_id + message_id are passed, the draft is created as a
+        reply and the original message is fetched to derive the recipient/subject."""
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().getProfile().execute.return_value = {"emailAddress": "me@example.com"}
+            service.users().messages().get().execute.return_value = _sample_message()
+            service.users().drafts().create().execute.return_value = {
+                "id": "draft-2",
+                "message": {"id": "msg-2", "threadId": "t1"},
+            }
+            result = await gmail.execute_action(
+                "create_draft",
+                {"thread_id": "t1", "message_id": "m1", "body": "Reply draft"},
+                mock_context,
+            )
+        assert result.type == ResultType.ACTION
+        # Verify drafts().create was called with a threadId
+        call = service.users().drafts().create.call_args
+        assert call.kwargs["body"]["message"]["threadId"] == "t1"
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().drafts().create().execute.side_effect = Exception("err")
+            result = await gmail.execute_action(
+                "create_draft",
+                {"to": ["bob@example.com"], "subject": "S", "body": "B"},
+                mock_context,
+            )
+        assert result.type == ResultType.ACTION_ERROR
+
+
+class TestUpdateDraft:
+    @pytest.mark.asyncio
+    async def test_returns_updated_draft(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().getProfile().execute.return_value = {"emailAddress": "me@example.com"}
+            service.users().drafts().get().execute.return_value = {
+                "id": "draft-1",
+                "message": {"threadId": "thr-1", "payload": {"headers": []}},
+            }
+            service.users().drafts().update().execute.return_value = {
+                "id": "draft-1",
+                "message": {"id": "msg-1", "threadId": "thr-1"},
+            }
+            result = await gmail.execute_action(
+                "update_draft",
+                {"draft_id": "draft-1", "to": ["x@example.com"], "subject": "S", "body": "B"},
+                mock_context,
+            )
+        assert result.type == ResultType.ACTION
+        assert result.result.data["draft"]["id"] == "draft-1"
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().drafts().get().execute.side_effect = Exception("missing")
+            result = await gmail.execute_action(
+                "update_draft",
+                {"draft_id": "x", "to": ["x@example.com"], "subject": "S", "body": "B"},
+                mock_context,
+            )
+        assert result.type == ResultType.ACTION_ERROR
+
+
+class TestListDrafts:
+    @pytest.mark.asyncio
+    async def test_returns_drafts_list(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().drafts().list().execute.return_value = {
+                "drafts": [{"id": "d1", "message": {"id": "m1", "threadId": "t1"}}]
+            }
+            result = await gmail.execute_action("list_drafts", {"user_id": "me"}, mock_context)
+        assert result.type == ResultType.ACTION
+        assert "drafts" in result.result.data
+
+    @pytest.mark.asyncio
+    async def test_next_page_token_propagated(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().drafts().list().execute.return_value = {
+                "drafts": [],
+                "nextPageToken": "tok",
+            }
+            result = await gmail.execute_action("list_drafts", {"user_id": "me"}, mock_context)
+        assert result.result.data["nextPageToken"] == "tok"
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().drafts().list().execute.side_effect = Exception("err")
+            result = await gmail.execute_action("list_drafts", {"user_id": "me"}, mock_context)
+        assert result.type == ResultType.ACTION_ERROR
+
+
+class TestGetDraft:
+    @pytest.mark.asyncio
+    async def test_returns_draft(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().drafts().get().execute.return_value = {
+                "id": "draft-1",
+                "message": _sample_message(),
+            }
+            result = await gmail.execute_action("get_draft", {"user_id": "me", "draft_id": "draft-1"}, mock_context)
+        assert result.type == ResultType.ACTION
+        assert "draft" in result.result.data
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().drafts().get().execute.side_effect = Exception("missing")
+            result = await gmail.execute_action("get_draft", {"user_id": "me", "draft_id": "x"}, mock_context)
+        assert result.type == ResultType.ACTION_ERROR
+
+
+class TestSendDraft:
+    @pytest.mark.asyncio
+    async def test_returns_sent_message(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().drafts().send().execute.return_value = {
+                "id": "msg-sent",
+                "threadId": "t1",
+            }
+            result = await gmail.execute_action("send_draft", {"user_id": "me", "draft_id": "draft-1"}, mock_context)
+        assert result.type == ResultType.ACTION
+        assert result.result.data["message"]["id"] == "msg-sent"
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().drafts().send().execute.side_effect = Exception("rejected")
+            result = await gmail.execute_action("send_draft", {"user_id": "me", "draft_id": "d"}, mock_context)
+        assert result.type == ResultType.ACTION_ERROR
+
+
+class TestDeleteDraft:
+    @pytest.mark.asyncio
+    async def test_returns_empty_data_on_success(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().drafts().delete().execute.return_value = None
+            result = await gmail.execute_action("delete_draft", {"user_id": "me", "draft_id": "draft-1"}, mock_context)
+        assert result.type == ResultType.ACTION
+        assert result.result.data == {}
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_action_error(self, mock_context):
+        with _patched_service() as mock_build:
+            service = _make_service()
+            mock_build.return_value = service
+            service.users().drafts().delete().execute.side_effect = Exception("not found")
+            result = await gmail.execute_action("delete_draft", {"user_id": "me", "draft_id": "x"}, mock_context)
+        assert result.type == ResultType.ACTION_ERROR

From cebb3f69c652c6196c95e37a95dfc93feb7074f8 Mon Sep 17 00:00:00 2001
From: Kai Koenig <kai@ventego-creative.co.nz>
Date: Wed, 13 May 2026 13:25:01 +1200
Subject: [PATCH 4/7] test(gmail): add integration test suite with destructive
 lifecycle coverage
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 8 read-only tests (profile, labels, inbox/all-mail, drafts, threads)
- 5 destructive lifecycle tests (label CRUD, send/archive, draft CRUD,
  send-from-draft, reply-to-thread) — all marked @pytest.mark.destructive
  with explicit docstrings describing what is created/modified
- Uses live_context fixture (PlatformOauth2 envelope) — gmail uses
  googleapiclient directly, not context.fetch
- Supports GMAIL_TEST_THREAD_ID / GMAIL_TEST_MESSAGE_ID env overrides;
  otherwise picks most-recent inbox message dynamically
- .env.example documents GMAIL_ACCESS_TOKEN and optional overrides
---
 .env.example                          |   9 +
 gmail/tests/test_gmail_integration.py | 495 ++++++++++++++++++++++++++
 2 files changed, 504 insertions(+)
 create mode 100644 gmail/tests/test_gmail_integration.py

diff --git a/.env.example b/.env.example
index 0e830576..6e3bac6d 100644
--- a/.env.example
+++ b/.env.example
@@ -18,6 +18,15 @@
 # -- ClickUp --
 # CLICKUP_ACCESS_TOKEN=
 
+# -- Gmail --
+# Required for read-only and destructive integration tests.
+# Token must have the https://www.googleapis.com/auth/gmail.modify scope.
+# GMAIL_ACCESS_TOKEN=
+# Optional — pin to a specific thread/message for the reply test.
+# Otherwise the test picks the most-recent inbox message dynamically.
+# GMAIL_TEST_THREAD_ID=
+# GMAIL_TEST_MESSAGE_ID=
+
 # -- Freshdesk --
 # FRESHDESK_API_KEY=
 # FRESHDESK_DOMAIN=
diff --git a/gmail/tests/test_gmail_integration.py b/gmail/tests/test_gmail_integration.py
new file mode 100644
index 00000000..44da906e
--- /dev/null
+++ b/gmail/tests/test_gmail_integration.py
@@ -0,0 +1,495 @@
+"""End-to-end integration tests for the Gmail integration.
+
+These tests call the real Gmail API and require a valid OAuth 2.0 access
+token (with the `https://www.googleapis.com/auth/gmail.modify` scope)
+set in the GMAIL_ACCESS_TOKEN environment variable (via .env or export).
+
+Optional env vars (override dynamic test data):
+    GMAIL_TEST_THREAD_ID   — thread id for reply / thread-read tests
+    GMAIL_TEST_MESSAGE_ID  — message id for reply tests
+
+Run with:
+
+    # Read-only tests only — safe, no mailbox mutation
+    pytest gmail/tests/test_gmail_integration.py -m "integration and not destructive"
+
+    # Destructive lifecycle tests — sends real email to yourself,
+    # creates and deletes a real label, creates and deletes a real
+    # draft, etc.
+    pytest gmail/tests/test_gmail_integration.py -m "integration and destructive"
+
+Never runs in CI — the default pytest marker filter (-m unit) excludes
+these, and the file naming (test_*_integration.py) is not matched by
+python_files.
+
+This integration uses Google's googleapiclient (not context.fetch), so
+the live_context fixture follows Variant 4 from the
+writing-integration-tests skill: inject the credential envelope and let
+the upstream Google SDK handle networking.
+"""
+
+import os
+
+import pytest
+from autohive_integrations_sdk.integration import ResultType
+
+from gmail.gmail import gmail
+
+pytestmark = pytest.mark.integration
+
+
+# Optional env-var overrides for fixture data.
+TEST_THREAD_ID = os.environ.get("GMAIL_TEST_THREAD_ID", "")
+TEST_MESSAGE_ID = os.environ.get("GMAIL_TEST_MESSAGE_ID", "")
+
+
+@pytest.fixture
+def live_context(env_credentials, make_context):
+    """Live context wired with a real Gmail OAuth access token.
+
+    Variant 4 (external Python SDK): no `real_fetch` wrapper needed —
+    gmail.py uses googleapiclient directly. We just shape the auth
+    envelope the way the SDK's platform-OAuth path would, and the
+    integration's `build_credentials` reads the access token out of it.
+    """
+    token = env_credentials("GMAIL_ACCESS_TOKEN")
+    if not token:
+        pytest.skip("GMAIL_ACCESS_TOKEN not set — skipping Gmail integration tests")
+    return make_context(
+        auth={
+            "auth_type": "PlatformOauth2",
+            "credentials": {"access_token": token},
+        }
+    )
+
+
+# ============================================================
+#  Read-Only Tests
+#  Safe to run repeatedly — no mailbox mutation.
+# ============================================================
+
+
+class TestGetUserInfo:
+    """Verifies the authenticated user's profile is retrievable."""
+
+    @pytest.mark.asyncio
+    async def test_returns_profile(self, live_context):
+        result = await gmail.execute_action("get_user_info", {"user_id": "me"}, live_context)
+        assert result.type == ResultType.ACTION
+        info = result.result.data["user_info"]
+        assert "email_address" in info
+        assert "@" in info["email_address"]
+        assert isinstance(info["messages_total"], int)
+
+
+class TestListLabels:
+    """Lists the authenticated user's mailbox labels (read-only)."""
+
+    @pytest.mark.asyncio
+    async def test_returns_labels(self, live_context):
+        result = await gmail.execute_action("list_labels", {"user_id": "me"}, live_context)
+        assert result.type == ResultType.ACTION
+        labels = result.result.data["labels"]
+        assert isinstance(labels, list)
+        # Every Gmail account has the system INBOX label
+        names = {label.get("name") for label in labels}
+        assert "INBOX" in names
+
+
+class TestReadInbox:
+    """Lists inbox messages with read/unread filtering and pagination."""
+
+    @pytest.mark.asyncio
+    async def test_default_scope_returns_emails(self, live_context):
+        result = await gmail.execute_action("read_inbox", {"user_id": "me", "scope": "all"}, live_context)
+        assert result.type == ResultType.ACTION
+        assert "emails" in result.result.data
+        assert isinstance(result.result.data["emails"], list)
+
+    @pytest.mark.asyncio
+    async def test_unread_scope_returns_emails_or_empty(self, live_context):
+        result = await gmail.execute_action("read_inbox", {"user_id": "me", "scope": "unread"}, live_context)
+        assert result.type == ResultType.ACTION
+        # May be empty if the inbox has no unread messages — both states are valid
+        assert isinstance(result.result.data["emails"], list)
+
+    @pytest.mark.asyncio
+    async def test_next_page_token_chained(self, live_context):
+        first = await gmail.execute_action("read_inbox", {"user_id": "me", "scope": "all"}, live_context)
+        token = first.result.data.get("nextPageToken")
+        if not token:
+            pytest.skip("Inbox fits in one page — pagination chain not exercised")
+        second = await gmail.execute_action(
+            "read_inbox", {"user_id": "me", "scope": "all", "pageToken": token}, live_context
+        )
+        assert second.type == ResultType.ACTION
+
+
+class TestReadAllMail:
+    """Lists messages across the entire mailbox."""
+
+    @pytest.mark.asyncio
+    async def test_returns_emails(self, live_context):
+        result = await gmail.execute_action("read_all_mail", {"user_id": "me", "scope": "all"}, live_context)
+        assert result.type == ResultType.ACTION
+        assert isinstance(result.result.data["emails"], list)
+
+
+class TestReadEmailChained:
+    """Reads a real message — picks the first inbox message dynamically
+    (or uses GMAIL_TEST_MESSAGE_ID if set)."""
+
+    @pytest.mark.asyncio
+    async def test_returns_email_object(self, live_context):
+        message_id = TEST_MESSAGE_ID
+        if not message_id:
+            inbox = await gmail.execute_action("read_inbox", {"user_id": "me", "scope": "all"}, live_context)
+            emails = inbox.result.data.get("emails", [])
+            if not emails:
+                pytest.skip("Inbox is empty — cannot exercise read_email")
+            message_id = emails[0]["id"]
+
+        result = await gmail.execute_action("read_email", {"user_id": "me", "email_id": message_id}, live_context)
+        assert result.type == ResultType.ACTION
+        assert result.result.data["email"]["id"] == message_id
+        assert "files" in result.result.data
+
+
+class TestGetThreadEmailsChained:
+    """Reads a thread — picks one dynamically (or uses GMAIL_TEST_THREAD_ID
+    if set)."""
+
+    @pytest.mark.asyncio
+    async def test_returns_thread_emails(self, live_context):
+        thread_id = TEST_THREAD_ID
+        if not thread_id:
+            inbox = await gmail.execute_action("read_inbox", {"user_id": "me", "scope": "all"}, live_context)
+            emails = inbox.result.data.get("emails", [])
+            if not emails:
+                pytest.skip("Inbox is empty — cannot exercise get_thread_emails")
+            thread_id = emails[0].get("threadId") or emails[0].get("thread_id")
+            if not thread_id:
+                pytest.skip("First inbox email has no thread_id field")
+
+        result = await gmail.execute_action(
+            "get_thread_emails", {"user_id": "me", "thread_id": thread_id}, live_context
+        )
+        assert result.type == ResultType.ACTION
+        assert result.result.data["thread_id"] == thread_id
+        assert isinstance(result.result.data["emails"], list)
+
+
+class TestListDrafts:
+    """Lists existing drafts — safe even if there are none."""
+
+    @pytest.mark.asyncio
+    async def test_returns_drafts_list(self, live_context):
+        result = await gmail.execute_action("list_drafts", {"user_id": "me"}, live_context)
+        assert result.type == ResultType.ACTION
+        assert "drafts" in result.result.data
+
+
+class TestListEmailsByLabelChained:
+    """Lists emails for a label that we know exists (INBOX)."""
+
+    @pytest.mark.asyncio
+    async def test_returns_inbox_emails(self, live_context):
+        result = await gmail.execute_action(
+            "list_emails_by_label",
+            {"user_id": "me", "label_names": ["INBOX"]},
+            live_context,
+        )
+        assert result.type == ResultType.ACTION
+        assert isinstance(result.result.data["emails"], list)
+
+
+# ============================================================
+#  Destructive Tests (Write Operations)
+#
+#  These tests CREATE, UPDATE, or DELETE real data in the
+#  authenticated user's Gmail account. They are clearly named
+#  with "Lifecycle" in the class name and a docstring describing
+#  exactly what gets created and what gets cleaned up.
+#
+#  Run only with:
+#      pytest -m "integration and destructive"
+# ============================================================
+
+
+@pytest.mark.destructive
+class TestLabelLifecycle:
+    """LIFECYCLE: creates a real label in the user's mailbox, applies it
+    to the most-recent inbox message, removes it, then deletes the label.
+
+    What is created: 1 user-defined label (named "AH integration test
+    {pid}"). What is mutated: 1 message gains and then loses one label.
+    Cleanup: the label is deleted via the Gmail API at the end. The
+    message itself is left in place; only the label association is
+    reverted.
+    """
+
+    @pytest.mark.asyncio
+    async def test_full_lifecycle(self, live_context):
+        label_name = f"AH integration test {os.getpid()}"
+
+        # 1. Pick a real message id to apply the label to
+        inbox = await gmail.execute_action("read_inbox", {"user_id": "me", "scope": "all"}, live_context)
+        emails = inbox.result.data.get("emails", [])
+        if not emails:
+            pytest.skip("Inbox is empty — cannot exercise label lifecycle")
+        message_id = emails[0]["id"]
+
+        # 2. Create the label
+        create_result = await gmail.execute_action("create_label", {"user_id": "me", "name": label_name}, live_context)
+        assert create_result.type == ResultType.ACTION, create_result
+        label_id = create_result.result.data["label"]["id"]
+
+        try:
+            # 3. Apply the label to the message
+            add_result = await gmail.execute_action(
+                "add_labels_to_emails",
+                {"user_id": "me", "message_ids": [message_id], "label_ids": [label_id]},
+                live_context,
+            )
+            assert add_result.type == ResultType.ACTION
+
+            # 4. Verify the label appears when listing by it
+            list_by_label = await gmail.execute_action(
+                "list_emails_by_label",
+                {"user_id": "me", "label_names": [label_name]},
+                live_context,
+            )
+            assert list_by_label.type == ResultType.ACTION
+
+            # 5. Remove the label from the message
+            remove_result = await gmail.execute_action(
+                "remove_labels_from_emails",
+                {"user_id": "me", "message_ids": [message_id], "label_ids": [label_id]},
+                live_context,
+            )
+            assert remove_result.type == ResultType.ACTION
+        finally:
+            # 6. Cleanup: delete the label via the Google client directly
+            # (no public delete-label action in this integration)
+            from gmail.gmail import build_gmail_service
+
+            service = build_gmail_service(live_context)
+            try:
+                service.users().labels().delete(userId="me", id=label_id).execute()
+            except Exception as cleanup_err:
+                # Best-effort cleanup — leave the label if cleanup fails
+                print(f"Label cleanup failed for {label_id}: {cleanup_err}")
+
+
+@pytest.mark.destructive
+class TestSendEmailLifecycle:
+    """LIFECYCLE: sends a real email FROM and TO the authenticated user
+    (so it lands back in the same inbox), then exercises the read/unread
+    state transitions on it, then archives it.
+
+    What is created: 1 outbound email + 1 inbound email (the same
+    message, both sent and received by the same account). Subject line
+    includes the test PID for traceability so you can find/delete it
+    later: "[AH integration test {pid}] gmail integration self-test".
+    Cleanup: the inbound copy is archived (removed from the INBOX
+    label); it remains in All Mail and can be permanently deleted from
+    the Gmail UI if desired.
+    """
+
+    @pytest.mark.asyncio
+    async def test_send_and_archive(self, live_context):
+        # Get the authenticated user's address so we can send to ourselves
+        profile = await gmail.execute_action("get_user_info", {"user_id": "me"}, live_context)
+        my_address = profile.result.data["user_info"]["email_address"]
+
+        subject = f"[AH integration test {os.getpid()}] gmail integration self-test"
+
+        # 1. Send
+        send_result = await gmail.execute_action(
+            "send_email",
+            {
+                "to": [my_address],
+                "subject": subject,
+                "body": "This message was sent by the gmail integration test suite. Safe to delete.",
+            },
+            live_context,
+        )
+        assert send_result.type == ResultType.ACTION, send_result
+        sent_message_id = send_result.result.data["id"]
+        assert sent_message_id
+
+        # 2. Mark unread → read (round-trip on the just-sent message)
+        unread_result = await gmail.execute_action(
+            "mark_emails_as_unread",
+            {"user_id": "me", "ids": [sent_message_id]},
+            live_context,
+        )
+        assert unread_result.type == ResultType.ACTION
+
+        read_result = await gmail.execute_action(
+            "mark_emails_as_read",
+            {"user_id": "me", "ids": [sent_message_id]},
+            live_context,
+        )
+        assert read_result.type == ResultType.ACTION
+
+        # 3. Cleanup: archive (remove from inbox)
+        archive_result = await gmail.execute_action(
+            "archive_emails",
+            {"user_id": "me", "ids": [sent_message_id]},
+            live_context,
+        )
+        assert archive_result.type == ResultType.ACTION
+
+
+@pytest.mark.destructive
+class TestDraftLifecycle:
+    """LIFECYCLE: creates a real draft, updates it, fetches it back, and
+    deletes it.
+
+    What is created: 1 draft (subject "[AH integration test {pid}]
+    draft lifecycle test"). Cleanup: the draft is deleted at the end.
+    The draft is NEVER sent in this test — see TestSendDraftLifecycle
+    for that.
+    """
+
+    @pytest.mark.asyncio
+    async def test_create_update_get_delete(self, live_context):
+        subject = f"[AH integration test {os.getpid()}] draft lifecycle test"
+
+        # 1. Create draft
+        create_result = await gmail.execute_action(
+            "create_draft",
+            {
+                "to": ["self-test@example.com"],
+                "subject": subject,
+                "body": "Initial draft body",
+            },
+            live_context,
+        )
+        assert create_result.type == ResultType.ACTION, create_result
+        draft_id = create_result.result.data["draft"]["id"]
+        assert draft_id
+
+        try:
+            # 2. Update draft
+            update_result = await gmail.execute_action(
+                "update_draft",
+                {
+                    "draft_id": draft_id,
+                    "to": ["self-test@example.com"],
+                    "subject": subject,
+                    "body": "Updated draft body",
+                },
+                live_context,
+            )
+            assert update_result.type == ResultType.ACTION
+
+            # 3. Get draft back
+            get_result = await gmail.execute_action("get_draft", {"user_id": "me", "draft_id": draft_id}, live_context)
+            assert get_result.type == ResultType.ACTION
+            assert "draft" in get_result.result.data
+        finally:
+            # 4. Cleanup: delete draft (always runs, even if assertions failed)
+            delete_result = await gmail.execute_action(
+                "delete_draft", {"user_id": "me", "draft_id": draft_id}, live_context
+            )
+            assert delete_result.type == ResultType.ACTION
+
+
+@pytest.mark.destructive
+class TestSendDraftLifecycle:
+    """LIFECYCLE: creates a real draft addressed to the authenticated
+    user, then sends it (so a real email is delivered back to the same
+    inbox), then archives the resulting message.
+
+    What is created: 1 draft (briefly), 1 outbound + 1 inbound email
+    (same message). Subject includes the test PID for traceability:
+    "[AH integration test {pid}] send-draft lifecycle test". Cleanup:
+    the inbound copy is archived. Permanent deletion is left to the
+    user.
+    """
+
+    @pytest.mark.asyncio
+    async def test_create_send_archive(self, live_context):
+        profile = await gmail.execute_action("get_user_info", {"user_id": "me"}, live_context)
+        my_address = profile.result.data["user_info"]["email_address"]
+
+        subject = f"[AH integration test {os.getpid()}] send-draft lifecycle test"
+
+        # 1. Create draft
+        create_result = await gmail.execute_action(
+            "create_draft",
+            {"to": [my_address], "subject": subject, "body": "Sent via draft lifecycle test."},
+            live_context,
+        )
+        assert create_result.type == ResultType.ACTION, create_result
+        draft_id = create_result.result.data["draft"]["id"]
+
+        # 2. Send the draft
+        send_result = await gmail.execute_action("send_draft", {"user_id": "me", "draft_id": draft_id}, live_context)
+        assert send_result.type == ResultType.ACTION, send_result
+        sent_message_id = send_result.result.data["message"]["id"]
+
+        # 3. Cleanup: archive the resulting message
+        archive_result = await gmail.execute_action(
+            "archive_emails",
+            {"user_id": "me", "ids": [sent_message_id]},
+            live_context,
+        )
+        assert archive_result.type == ResultType.ACTION
+
+
+@pytest.mark.destructive
+class TestReplyToThreadLifecycle:
+    """LIFECYCLE: replies to an existing thread in the user's inbox.
+    Picks the most-recent inbox message dynamically unless
+    GMAIL_TEST_THREAD_ID and GMAIL_TEST_MESSAGE_ID are both set.
+
+    What is created: 1 outbound email (a reply on an existing thread).
+    The reply body clearly identifies it as a test message. Cleanup:
+    the resulting message is archived. The original thread is left
+    intact apart from the new reply within it.
+    """
+
+    @pytest.mark.asyncio
+    async def test_reply_and_archive(self, live_context):
+        thread_id = TEST_THREAD_ID
+        message_id = TEST_MESSAGE_ID
+
+        if not (thread_id and message_id):
+            inbox = await gmail.execute_action("read_inbox", {"user_id": "me", "scope": "all"}, live_context)
+            emails = inbox.result.data.get("emails", [])
+            if not emails:
+                pytest.skip("Inbox is empty — cannot exercise reply_to_thread")
+            first = emails[0]
+            thread_id = first.get("threadId") or first.get("thread_id")
+            message_id = first["id"]
+            if not thread_id:
+                pytest.skip("Most recent inbox email has no thread_id")
+
+        reply_result = await gmail.execute_action(
+            "reply_to_thread",
+            {
+                "thread_id": thread_id,
+                "message_id": message_id,
+                "body": (
+                    f"AH integration test reply (pid {os.getpid()}). "
+                    "This message was sent automatically by the gmail "
+                    "integration test suite. Safe to delete."
+                ),
+                "to": [],
+                "cc": [],
+            },
+            live_context,
+        )
+        assert reply_result.type == ResultType.ACTION, reply_result
+        reply_message_id = reply_result.result.data["id"]
+
+        # Cleanup: archive the reply we just sent
+        archive_result = await gmail.execute_action(
+            "archive_emails",
+            {"user_id": "me", "ids": [reply_message_id]},
+            live_context,
+        )
+        assert archive_result.type == ResultType.ACTION

From b9693769aca2c45318ab2dc13e268e91be1001a2 Mon Sep 17 00:00:00 2001
From: Kai Koenig <kai@ventego-creative.co.nz>
Date: Wed, 13 May 2026 13:39:48 +1200
Subject: [PATCH 5/7] test(gmail): drop unused FetchResponse import from unit
 tests

Addresses code-quality bot feedback on PR #325. Gmail uses
googleapiclient directly, so FetchResponse is never referenced.
---
 gmail/tests/test_gmail_unit.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/gmail/tests/test_gmail_unit.py b/gmail/tests/test_gmail_unit.py
index f9e896c0..5554be9c 100644
--- a/gmail/tests/test_gmail_unit.py
+++ b/gmail/tests/test_gmail_unit.py
@@ -9,7 +9,6 @@
 from unittest.mock import MagicMock, patch
 
 import pytest
-from autohive_integrations_sdk import FetchResponse  # noqa: F401  (kept for SDK 2.0 contract)
 from autohive_integrations_sdk.integration import ResultType
 
 from gmail.gmail import gmail, create_email_message

From a9aa88844383cabfa03507573246df3da5f9a776 Mon Sep 17 00:00:00 2001
From: Kai Koenig <kai@ventego-creative.co.nz>
Date: Wed, 13 May 2026 13:42:17 +1200
Subject: [PATCH 6/7] test(gmail): drop incorrect sys.path manipulation in
 conftest

Addresses Codex review on PR #325. Prepending the gmail/ integration
dir to sys.path could shadow the gmail package with the gmail.py
module file, breaking 'from gmail.gmail import ...'. The repo-root
conftest.py already puts the workspace root on sys.path and patches
Integration.load() from the caller frame, so no per-integration
sys.path tweaking is needed.
---
 gmail/tests/conftest.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/gmail/tests/conftest.py b/gmail/tests/conftest.py
index 9c49aad3..5bfea540 100644
--- a/gmail/tests/conftest.py
+++ b/gmail/tests/conftest.py
@@ -1,11 +1,11 @@
-import os
-import sys
 from unittest.mock import AsyncMock, MagicMock
 
 import pytest
 
-# Make gmail.py importable as a top-level module.
-sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+# Note: the repo-root conftest.py puts the workspace root on sys.path and
+# monkeypatches Integration.load() to resolve config.json from the caller
+# frame, so `from gmail.gmail import gmail` resolves to the gmail/ package
+# without any extra path manipulation here.
 
 
 @pytest.fixture

From 7bd4fa335d48b81953e4d2bb45e35a7cb6fcab29 Mon Sep 17 00:00:00 2001
From: Kai Koenig <kai@ventego-creative.co.nz>
Date: Wed, 13 May 2026 13:54:19 +1200
Subject: [PATCH 7/7] refactor(gmail): extract shared build_raw_email helper
 and fix string-recipient bug

Addresses Codex review on PR #325.

- New module-level build_raw_email() consolidates raw RFC822 payload
  construction previously duplicated across SendEmail, ReplyToThread,
  CreateDraft, and UpdateDraft (3 near-identical _create_raw_email
  methods plus an inline block in ReplyToThread).
- Fixes a latent bug in ReplyToThread that assumed 'to' and 'cc' were
  always lists. With a string value, recipients.extend(inputs['to']) /
  ', '.join(inputs['cc']) silently character-split the address into
  per-letter recipients, producing malformed headers. The new helper
  routes both forms through _normalize_addresses so a string is always
  treated as a single recipient.
- Helper accepts extra_to (used by ReplyToThread to prepend the
  original sender), subject_override (for 'Re: ...'), and
  in_reply_to/references for threading. Callers compute the final
  References string so each existing behavior (append vs pass-through)
  is preserved verbatim.
- Adds a TestBuildRawEmail unit test class covering the regression
  (string vs list recipients), extra_to prepending, subject override,
  the 'me' From sentinel, and threading header behavior.
---
 gmail/gmail.py                 | 284 +++++++++++++--------------------
 gmail/tests/test_gmail_unit.py |  99 +++++++++++-
 2 files changed, 211 insertions(+), 172 deletions(-)

diff --git a/gmail/gmail.py b/gmail/gmail.py
index 07b4b2b3..8d05fad8 100644
--- a/gmail/gmail.py
+++ b/gmail/gmail.py
@@ -1,6 +1,6 @@
 from autohive_integrations_sdk import Integration, ExecutionContext, ActionHandler, ActionResult, ActionError
 
-from typing import Dict, Any
+from typing import Dict, Any, List, Optional
 from email.mime.text import MIMEText
 from email.mime.multipart import MIMEMultipart
 from email.mime.base import MIMEBase
@@ -159,6 +159,86 @@ def create_email_message(body: str, files: list = None, is_html: bool = False) -
     return message
 
 
+def _normalize_addresses(value) -> str:
+    """Accept either a string or a list of strings and return a comma-joined header value.
+
+    Inputs from the platform may arrive as either a single recipient string
+    or a list of recipient strings. Treating a string as a list (e.g. via
+    ``", ".join(value)``) silently splits it into individual characters and
+    produces malformed headers, so always normalize through this helper.
+    """
+    if isinstance(value, list):
+        return ", ".join(value)
+    return str(value)
+
+
+def build_raw_email(
+    inputs: Dict[str, Any],
+    *,
+    extra_to: Optional[List[str]] = None,
+    subject_override: Optional[str] = None,
+    in_reply_to: Optional[str] = None,
+    references: Optional[str] = None,
+) -> str:
+    """Build a base64url-encoded RFC822 email payload from action inputs.
+
+    Shared by SendEmail, ReplyToThread, CreateDraft, and UpdateDraft so that
+    recipient handling, HTML/text body selection, attachments, and threading
+    headers stay consistent.
+
+    Args:
+        inputs: Action input dict. Recognized keys: body, body_format, files,
+            from, to, cc, bcc, subject. ``to``/``cc``/``bcc`` may each be a
+            string or list of strings.
+        extra_to: Optional list of addresses to prepend to the To header
+            (used by ReplyToThread to include the original sender).
+        subject_override: Optional subject string that wins over
+            ``inputs["subject"]`` (used by ReplyToThread for ``Re: ...``).
+        in_reply_to: Optional ``In-Reply-To`` header value.
+        references: Optional ``References`` header value. Falls back to
+            ``in_reply_to`` when only the latter is provided.
+    """
+    body_format = inputs.get("body_format", "text")
+    is_html = body_format == "html"
+    input_files = inputs.get("files", [])
+    body = inputs.get("body", "")
+    message = create_email_message(body, input_files, is_html)
+
+    # From — skip the "me" sentinel used by SendEmail
+    sender = inputs.get("from")
+    if sender and sender != "me":
+        message["from"] = sender
+
+    # To — combine optional extra_to with caller-supplied to (string or list)
+    recipients: List[str] = []
+    if extra_to:
+        recipients.extend(extra_to)
+    to_value = inputs.get("to")
+    if to_value:
+        if isinstance(to_value, list):
+            recipients.extend(to_value)
+        else:
+            recipients.append(to_value)
+    if recipients:
+        message["to"] = ", ".join(recipients)
+
+    if inputs.get("cc"):
+        message["cc"] = _normalize_addresses(inputs["cc"])
+    if inputs.get("bcc"):
+        message["bcc"] = _normalize_addresses(inputs["bcc"])
+
+    if subject_override is not None:
+        message["subject"] = subject_override
+    elif inputs.get("subject"):
+        message["subject"] = inputs["subject"]
+
+    if in_reply_to:
+        message["In-Reply-To"] = in_reply_to
+        message["References"] = references if references else in_reply_to
+
+    return base64.urlsafe_b64encode(message.as_bytes()).decode()
+
+
 def build_credentials(context: ExecutionContext):
     """Build Google credentials from ExecutionContext.
 
@@ -445,7 +525,7 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
             user_id = "me"
 
             # Create the email message
-            message = {"raw": self._create_raw_email(inputs)}
+            message = {"raw": build_raw_email(inputs)}
 
             # Send the email using Gmail API
             request = service.users().messages().send(userId=user_id, body=message)
@@ -456,38 +536,6 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
         except Exception as e:
             return ActionError(message=str(e))
 
-    def _create_raw_email(self, inputs: Dict[str, Any]) -> str:
-        """Create base64 encoded email message."""
-        # Determine if HTML formatting is requested
-        body_format = inputs.get("body_format", "text")
-        is_html = body_format == "html"
-
-        # Create message with optional files and HTML support
-        input_files = inputs.get("files", [])
-        message = create_email_message(inputs["body"], input_files, is_html)
-
-        # Handle multiple recipients in 'to' field
-        if isinstance(inputs["to"], list):
-            message["to"] = ", ".join(inputs["to"])
-        else:
-            message["to"] = inputs["to"]
-
-        # Handle CC recipients if present
-        if "cc" in inputs:
-            if isinstance(inputs["cc"], list):
-                message["cc"] = ", ".join(inputs["cc"])
-            else:
-                message["cc"] = inputs["cc"]
-
-        message["subject"] = inputs["subject"]
-
-        # Add from if provided
-        if "from" in inputs and inputs["from"] != "me":
-            message["from"] = inputs["from"]
-
-        # Encode the message
-        return base64.urlsafe_b64encode(message.as_bytes()).decode()
-
 
 @gmail.action("reply_to_thread")
 class ReplyToThread(ActionHandler):
@@ -497,7 +545,6 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
             user_id = inputs.get("user_id", "me")
             thread_id = inputs["thread_id"]
             message_id = inputs["message_id"]
-            body = inputs["body"]
 
             # Fetch the original message to get headers
             original_request = service.users().messages().get(userId=user_id, id=message_id)
@@ -510,36 +557,21 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
             message_id_header = GmailMessageParser.get_header_value(headers, "Message-ID")
             references = GmailMessageParser.get_header_value(headers, "References")
 
-            # Determine if HTML formatting is requested
-            body_format = inputs.get("body_format", "text")
-            is_html = body_format == "html"
-
-            # Create message with optional files and HTML support
-            input_files = inputs.get("files", [])
-            message = create_email_message(body, input_files, is_html)
-
-            # Set recipients
-            recipients = [original_from]
-            if "to" in inputs and inputs["to"]:
-                recipients.extend(inputs["to"])
-            message["to"] = ", ".join(recipients)
-
-            # Add CC if provided
-            if "cc" in inputs and inputs["cc"]:
-                message["cc"] = ", ".join(inputs["cc"])
-
-            message["subject"] = (
-                f"Re: {original_subject}" if not original_subject.startswith("Re:") else original_subject
-            )
-
-            # Add threading headers
-            message["In-Reply-To"] = message_id_header
-            # Combine existing references with the new message ID
+            # Build the reply: prepend the original sender to To, set "Re: ..."
+            # subject, and append the new message id to the existing References
+            # chain so the thread keeps a complete reply history.
             new_references = f"{references} {message_id_header}" if references else message_id_header
-            message["References"] = new_references
+            subject_override = f"Re: {original_subject}" if not original_subject.startswith("Re:") else original_subject
+            raw = build_raw_email(
+                inputs,
+                extra_to=[original_from],
+                subject_override=subject_override,
+                in_reply_to=message_id_header,
+                references=new_references,
+            )
 
             # Add thread ID to keep messages grouped
-            message_payload = {"raw": base64.urlsafe_b64encode(message.as_bytes()).decode(), "threadId": thread_id}
+            message_payload = {"raw": raw, "threadId": thread_id}
 
             # Send the reply
             request = service.users().messages().send(userId=user_id, body=message_payload)
@@ -933,14 +965,20 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
                     else:
                         inputs["subject"] = f"Re: {original_subject}"
 
-                # Create the draft reply message with threading headers
+                # Create the draft reply message with threading headers.
+                # Append the new message id to the existing References chain.
+                combined_references = f"{references} {message_id_header}" if references else message_id_header
                 draft_message = {
-                    "raw": self._create_raw_email(inputs, message_id_header, references),
+                    "raw": build_raw_email(
+                        inputs,
+                        in_reply_to=message_id_header,
+                        references=combined_references,
+                    ),
                     "threadId": thread_id,
                 }
             else:
                 # Create a new draft (not a reply)
-                draft_message = {"raw": self._create_raw_email(inputs)}
+                draft_message = {"raw": build_raw_email(inputs)}
 
             # Create the draft using Gmail API
             draft_body = {"message": draft_message}
@@ -963,58 +1001,6 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
         except Exception as e:
             return ActionError(message=str(e))
 
-    def _create_raw_email(self, inputs: Dict[str, Any], message_id_header: str = None, references: str = None) -> str:
-        """Create base64 encoded email message for draft."""
-        # Determine if HTML formatting is requested
-        body_format = inputs.get("body_format", "text")
-        is_html = body_format == "html"
-
-        # Create message with optional files and HTML support
-        input_files = inputs.get("files", [])
-        body = inputs.get("body", "")
-        message = create_email_message(body, input_files, is_html)
-
-        # Add From header (REQUIRED for drafts to display properly in Gmail)
-        if "from" in inputs and inputs["from"]:
-            message["from"] = inputs["from"]
-
-        # Add reply headers for proper threading if provided
-        if message_id_header:
-            message["In-Reply-To"] = message_id_header
-            # Combine existing references with the new message ID
-            if references:
-                message["References"] = f"{references} {message_id_header}"
-            else:
-                message["References"] = message_id_header
-
-        # Handle recipients
-        if "to" in inputs and inputs["to"]:
-            if isinstance(inputs["to"], list):
-                message["to"] = ", ".join(inputs["to"])
-            else:
-                message["to"] = inputs["to"]
-
-        # Handle CC recipients if present
-        if "cc" in inputs and inputs["cc"]:
-            if isinstance(inputs["cc"], list):
-                message["cc"] = ", ".join(inputs["cc"])
-            else:
-                message["cc"] = inputs["cc"]
-
-        # Handle BCC recipients if present
-        if "bcc" in inputs and inputs["bcc"]:
-            if isinstance(inputs["bcc"], list):
-                message["bcc"] = ", ".join(inputs["bcc"])
-            else:
-                message["bcc"] = inputs["bcc"]
-
-        # Set subject
-        if "subject" in inputs and inputs["subject"]:
-            message["subject"] = inputs["subject"]
-
-        # Encode the message
-        return base64.urlsafe_b64encode(message.as_bytes()).decode()
-
 
 @gmail.action("update_draft")
 class UpdateDraft(ActionHandler):
@@ -1043,8 +1029,16 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
                 elif header["name"] == "References":
                     references = header["value"]
 
-            # Create the updated email message with threading headers if this was a reply
-            draft_message = {"raw": self._create_raw_email(inputs, message_id_header, references)}
+            # Create the updated email message with threading headers if this
+            # was a reply. The existing draft's References header already
+            # contains the full chain, so pass it through verbatim.
+            draft_message = {
+                "raw": build_raw_email(
+                    inputs,
+                    in_reply_to=message_id_header,
+                    references=references,
+                )
+            }
 
             # Preserve threadId if the draft was part of a thread
             if existing_thread_id:
@@ -1071,58 +1065,6 @@ async def execute(self, inputs: Dict[str, Any], context: ExecutionContext):
         except Exception as e:
             return ActionError(message=str(e))
 
-    def _create_raw_email(self, inputs: Dict[str, Any], message_id_header: str = None, references: str = None) -> str:
-        """Create base64 encoded email message for draft."""
-        # Determine if HTML formatting is requested
-        body_format = inputs.get("body_format", "text")
-        is_html = body_format == "html"
-
-        # Create message with optional files and HTML support
-        input_files = inputs.get("files", [])
-        body = inputs.get("body", "")
-        message = create_email_message(body, input_files, is_html)
-
-        # Add From header (REQUIRED for drafts to display properly in Gmail)
-        if "from" in inputs and inputs["from"]:
-            message["from"] = inputs["from"]
-
-        # Add reply headers for proper threading if provided (preserved from existing draft)
-        if message_id_header:
-            message["In-Reply-To"] = message_id_header
-            # Combine existing references with the message ID
-            if references:
-                message["References"] = references
-            else:
-                message["References"] = message_id_header
-
-        # Handle recipients
-        if "to" in inputs and inputs["to"]:
-            if isinstance(inputs["to"], list):
-                message["to"] = ", ".join(inputs["to"])
-            else:
-                message["to"] = inputs["to"]
-
-        # Handle CC recipients if present
-        if "cc" in inputs and inputs["cc"]:
-            if isinstance(inputs["cc"], list):
-                message["cc"] = ", ".join(inputs["cc"])
-            else:
-                message["cc"] = inputs["cc"]
-
-        # Handle BCC recipients if present
-        if "bcc" in inputs and inputs["bcc"]:
-            if isinstance(inputs["bcc"], list):
-                message["bcc"] = ", ".join(inputs["bcc"])
-            else:
-                message["bcc"] = inputs["bcc"]
-
-        # Set subject
-        if "subject" in inputs and inputs["subject"]:
-            message["subject"] = inputs["subject"]
-
-        # Encode the message
-        return base64.urlsafe_b64encode(message.as_bytes()).decode()
-
 
 @gmail.action("list_drafts")
 class ListDrafts(ActionHandler):
diff --git a/gmail/tests/test_gmail_unit.py b/gmail/tests/test_gmail_unit.py
index 5554be9c..dbe1563b 100644
--- a/gmail/tests/test_gmail_unit.py
+++ b/gmail/tests/test_gmail_unit.py
@@ -11,7 +11,7 @@
 import pytest
 from autohive_integrations_sdk.integration import ResultType
 
-from gmail.gmail import gmail, create_email_message
+from gmail.gmail import gmail, create_email_message, build_raw_email
 
 pytestmark = pytest.mark.unit
 
@@ -118,6 +118,103 @@ def test_html_body_with_attachments_is_mixed_multipart(self):
         assert msg.get_content_type() == "multipart/mixed"
 
 
+def _decode_raw(raw_b64):
+    """Decode a base64url-encoded RFC822 payload into an email.Message."""
+    import email
+
+    return email.message_from_bytes(base64.urlsafe_b64decode(raw_b64.encode()))
+
+
+class TestBuildRawEmail:
+    """Tests for the shared build_raw_email helper.
+
+    Exercises the helper directly (not through the SDK envelope) so that
+    we can cover string-vs-list normalization without tripping the
+    config.json input_schema, which constrains some actions to arrays.
+    """
+
+    def test_string_recipients_are_not_character_split(self):
+        """Regression: passing 'to'/'cc'/'bcc' as a single string used to
+        be treated as an iterable of single characters by the inline
+        ReplyToThread builder, producing malformed headers like
+        'b, o, b, @, e, x, ...'. Both forms must produce a clean header."""
+        msg = _decode_raw(
+            build_raw_email(
+                {
+                    "to": "alice@example.com",
+                    "cc": "carol@example.com",
+                    "bcc": "dan@example.com",
+                    "subject": "Hi",
+                    "body": "hello",
+                },
+            )
+        )
+        assert msg["to"] == "alice@example.com"
+        assert msg["cc"] == "carol@example.com"
+        assert msg["bcc"] == "dan@example.com"
+
+    def test_list_recipients_are_comma_joined(self):
+        msg = _decode_raw(
+            build_raw_email(
+                {
+                    "to": ["alice@example.com", "bob@example.com"],
+                    "cc": ["carol@example.com", "dan@example.com"],
+                    "subject": "Hi",
+                    "body": "hello",
+                },
+            )
+        )
+        assert msg["to"] == "alice@example.com, bob@example.com"
+        assert msg["cc"] == "carol@example.com, dan@example.com"
+
+    def test_extra_to_is_prepended(self):
+        """ReplyToThread uses extra_to to put the original sender first."""
+        msg = _decode_raw(
+            build_raw_email(
+                {"to": ["bob@example.com"], "subject": "x", "body": "y"},
+                extra_to=["original@example.com"],
+            )
+        )
+        assert msg["to"] == "original@example.com, bob@example.com"
+
+    def test_subject_override_wins(self):
+        msg = _decode_raw(
+            build_raw_email(
+                {"to": "x@example.com", "subject": "ignored", "body": "b"},
+                subject_override="Re: real",
+            )
+        )
+        assert msg["subject"] == "Re: real"
+
+    def test_from_me_sentinel_is_skipped(self):
+        msg = _decode_raw(
+            build_raw_email(
+                {"to": "x@example.com", "subject": "s", "body": "b", "from": "me"},
+            )
+        )
+        assert msg["from"] is None
+
+    def test_threading_headers_default_references_to_in_reply_to(self):
+        msg = _decode_raw(
+            build_raw_email(
+                {"to": "x@example.com", "subject": "s", "body": "b"},
+                in_reply_to="<msg-id@example.com>",
+            )
+        )
+        assert msg["In-Reply-To"] == "<msg-id@example.com>"
+        assert msg["References"] == "<msg-id@example.com>"
+
+    def test_threading_headers_pass_references_through(self):
+        msg = _decode_raw(
+            build_raw_email(
+                {"to": "x@example.com", "subject": "s", "body": "b"},
+                in_reply_to="<new@example.com>",
+                references="<old@example.com> <new@example.com>",
+            )
+        )
+        assert msg["References"] == "<old@example.com> <new@example.com>"
+
+
 # ============================================================
 #  Auth & service-build tests
 # ============================================================