n8n-nodes-gmail-custom 0.3.0 → 0.4.0

package/README.md

@@ -1,32 +1,66 @@
 # n8n-nodes-gmail-custom
 
-Custom Gmail node for n8n with token caching and 429 retry.
+Self-contained n8n node for sending emails via Gmail API with a Google service account and domain-wide delegation.
 
-A drop-in replacement for the native Gmail v2 Send operation, optimized for service account usage with domain-wide delegation.
+No credential setup in n8n required — all parameters are inline, supports expressions.
 
 ## Features
 
-- Same UI as native Gmail Send (To, Subject, Email Type, Message, Options with CC/BCC/ReplyTo/Attachments)
-- **Token caching** — access token is reused across calls (1 auth call per hour instead of per email)
-- **429 retry** — automatic retry with exponential backoff when rate limited
-- **From Email inline** — specify the delegated user directly in the node (no need to set in credential)
-- No extra API calls (no GET /profile like the native node)
+- **Self-contained**: service account email + private key are node parameters (no n8n credential needed)
+- **Token caching**: access token reused for 58 minutes — only 1 oauth call per hour instead of per email
+- **Domain-wide delegation**: send as any user in your Workspace domain
+- **Sender name**: set a display name without extra API calls
+- **Optional custom Message-ID**: auto-generated `<uuid@domain>` or specify your own — included in output
+- **Attachments**: from binary data with graceful skip if missing
+- **HTML and plain text email support**
 
 ## Installation
 
-In n8n: **Settings → Community Nodes → Install** → Enter `n8n-nodes-gmail-custom`
+In n8n: **Settings → Community Nodes → Install** → `n8n-nodes-gmail-custom`
 
 ## Usage
 
 1. Add a **Gmail Custom** node to your workflow
-2. Select your **Google API** credential (service account)
-3. Fill in:
-   - **From Email**: the delegated user to send as (e.g. `segreteria.a@domain.com`)
-   - **To**: recipient(s)
-   - **Subject**: email subject
-   - **Email Type**: Text or HTML
-   - **Message**: email body
-4. Configure advanced Options as needed (CC, BCC, ReplyTo, Attachments)
+2. Fill in the required fields (supports expressions):
+
+| Field | Description | Example |
+|---|---|---|
+| Service Account Email | Your SA `client_email` | `sa-name@project.iam.gserviceaccount.com` |
+| Private Key | RSA private key (PEM, hidden) | Expression from a previous node |
+| From Email | The user to impersonate (DWD) | `sender@your-domain.com` |
+| To | Recipient(s), comma-separated | `recipient@example.com` |
+| Subject | Email subject | `Hello World` |
+| Email Type | `HTML` or `Text` | `HTML` |
+| Message | Email body | Your HTML or text |
+
+3. Configure **Options** as needed:
+   - **CC / BCC**: carbon copy recipients
+   - **Reply To**: reply-to address
+   - **Sender Name**: display name (e.g. `John Doe`)
+   - **Attachments**: binary data field names from previous nodes
+   - **Custom Message-ID**: enable and optionally specify a `Message-ID` header. Auto-generated as `<uuid@domain>` if left empty. Returned in the node output.
+
+## Output
+
+```json
+{
+  "id": "19ef486e4ed521e6",
+  "threadId": "19ef486e4ed521e6",
+  "labelIds": ["SENT"],
+  "messageId": "<generated-uuid@your-domain.com>"
+}
+```
+
+`messageId` is only present when the Custom Message-ID option is enabled.
+
+## How it works
+
+1. Signs a JWT with the service account private key
+2. Obtains an access token from `oauth2.googleapis.com/token` (cached)
+3. Builds a MIME email message
+4. Sends via `POST gmail.googleapis.com/gmail/v1/users/me/messages/send`
+
+Per email sent: **1 Gmail API call** (token is cached for 1 hour).
 
 ## License
 

package/nodes/GmailCustom/GmailCustom.node.js

@@ -51,6 +51,10 @@ async function buildMimeMessage(options) {
 			mailOptions.html = options.htmlBody;
 		}
 
+		if (options.messageId) {
+			mailOptions.messageId = options.messageId;
+		}
+
 		if (options.attachments && options.attachments.length > 0) {
 			mailOptions.attachments = options.attachments.map((att) => ({
 				filename: att.fileName || 'attachment',
@@ -89,6 +93,7 @@ async function buildMimeMessage(options) {
 	if (cc) lines.push(`CC: ${cc}`);
 	if (bcc) lines.push(`BCC: ${bcc}`);
 	if (replyTo) lines.push(`Reply-To: ${replyTo}`);
+	if (options.messageId) lines.push(`Message-ID: ${options.messageId}`);
 	lines.push(`Subject: ${subject}`);
 	lines.push('MIME-Version: 1.0');
 
@@ -363,6 +368,25 @@ class GmailCustom {
 							placeholder: 'e.g. John Doe',
 							description: 'Name shown as the sender in recipients\' inboxes',
 						},
+						{
+							displayName: 'Custom Message-ID',
+							name: 'enableMessageId',
+							type: 'boolean',
+							default: false,
+							description: 'Whether to set a custom Message-ID header (auto-generated if not specified)',
+						},
+						{
+							displayName: 'Message-ID Value',
+							name: 'customMessageId',
+							type: 'string',
+							default: '',
+							displayOptions: {
+								show: {
+									enableMessageId: [true],
+								},
+							},
+							description: 'Leave empty to auto-generate a unique Message-ID',
+						},
 					],
 				},
 			],
@@ -404,6 +428,16 @@ class GmailCustom {
 					fromHeader = `${senderName} <${fromEmail}>`;
 				}
 
+				let messageId = null;
+				if (options.enableMessageId) {
+					if (options.customMessageId) {
+						messageId = options.customMessageId;
+					} else {
+						const domain = fromEmail.includes('@') ? fromEmail.split('@')[1] : 'localhost';
+						messageId = `<${crypto.randomUUID()}@${domain}>`;
+					}
+				}
+
 				let bodyText = message;
 				let bodyHtml = '';
 
@@ -450,22 +484,27 @@ class GmailCustom {
 					textBody: bodyText,
 					htmlBody: bodyHtml,
 					attachments,
+					messageId,
 				});
 
 				const sendResponse = await this.helpers.httpRequest({
-						method: 'POST',
-						url: 'https://gmail.googleapis.com/gmail/v1/users/me/messages/send',
-						headers: {
-							Authorization: `Bearer ${accessToken}`,
-							'Content-Type': 'application/json',
-						},
-						body: { raw: base64UrlMessage },
-					});
+					method: 'POST',
+					url: 'https://gmail.googleapis.com/gmail/v1/users/me/messages/send',
+					headers: {
+						Authorization: `Bearer ${accessToken}`,
+						'Content-Type': 'application/json',
+					},
+					body: { raw: base64UrlMessage },
+				});
 
-					returnData.push({
-						json: sendResponse,
-						pairedItem: { item: i },
-					});
+				const result = { ...sendResponse };
+				if (messageId) {
+					result.messageId = messageId;
+				}
+				returnData.push({
+					json: result,
+					pairedItem: { item: i },
+				});
 
 			} catch (error) {
 				let continueOnFail = false;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "n8n-nodes-gmail-custom",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "Custom Gmail node for n8n with token caching and 429 retry",
 	"keywords": [
 		"n8n-community-node-package",