n8n-nodes-gmail-custom 0.3.0 → 0.5.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

@@ -1,28 +1,5 @@
 const crypto = require('crypto');
-
-let jwtLib;
-try { jwtLib = require('jsonwebtoken'); } catch (e) {}
-
-const TOKEN_CACHE = {};
-
-function formatPrivateKey(privateKey) {
-	if (privateKey.includes('\\n')) {
-		return privateKey.replace(/\\n/g, '\n');
-	}
-	return privateKey;
-}
-
-function base64UrlEncode(str) {
-	return Buffer.from(str)
-		.toString('base64')
-		.replace(/=/g, '')
-		.replace(/\+/g, '-')
-		.replace(/\//g, '_');
-}
-
-function base64urlEscape(base64) {
-	return base64.replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
-}
+const { getOrRefreshAccessToken } = require('./utils');
 
 function generateBoundary() {
 	return '----=_Part_' + crypto.randomBytes(16).toString('hex');
@@ -51,6 +28,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 +70,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');
 
@@ -161,58 +143,6 @@ async function buildMimeMessage(options) {
 		.replace(/=+$/, '');
 }
 
-async function getOrRefreshAccessToken(ctx, serviceAccountEmail, privateKeyRaw, fromEmail) {
-	const cacheKey = `${serviceAccountEmail}:${fromEmail}`;
-	let token = TOKEN_CACHE[cacheKey];
-	if (token && token.expiresAt > Date.now()) {
-		return token.accessToken;
-	}
-
-	const privateKey = formatPrivateKey(privateKeyRaw);
-	const now = Math.floor(Date.now() / 1000);
-
-	let jwt;
-	const payload = {
-		iss: serviceAccountEmail,
-		scope: 'https://mail.google.com/',
-		aud: 'https://oauth2.googleapis.com/token',
-		exp: now + 3600,
-		iat: now,
-		sub: fromEmail,
-	};
-
-	if (jwtLib) {
-		jwt = jwtLib.sign(payload, privateKey, {
-			algorithm: 'RS256',
-			header: { kid: privateKey, typ: 'JWT', alg: 'RS256' },
-		});
-	} else {
-		const header = { alg: 'RS256', typ: 'JWT', kid: privateKey };
-		const signatureInput = base64UrlEncode(JSON.stringify(header)) + '.' + base64UrlEncode(JSON.stringify(payload));
-		const signer = crypto.createSign('RSA-SHA256');
-		signer.update(signatureInput);
-		const sig = signer.sign(privateKey);
-		jwt = signatureInput + '.' + base64urlEscape(sig.toString('base64'));
-	}
-
-	const response = await ctx.helpers.httpRequest({
-		method: 'POST',
-		url: 'https://oauth2.googleapis.com/token',
-		headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-		body: new URLSearchParams({
-			grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
-			assertion: jwt,
-		}).toString(),
-	});
-
-	TOKEN_CACHE[cacheKey] = {
-		accessToken: response.access_token,
-		expiresAt: Date.now() + 3500 * 1000,
-	};
-
-	return response.access_token;
-}
-
 class GmailCustom {
 
 	constructor() {
@@ -363,6 +293,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 +353,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 +409,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/nodes/GmailCustom/GmailTriggerCustom.node.js

@@ -0,0 +1,285 @@
+const { getOrRefreshAccessToken } = require('./utils');
+
+class GmailTriggerCustom {
+	constructor() {
+		this.description = {
+			displayName: 'Gmail Trigger Custom',
+			name: 'gmailTriggerCustom',
+			icon: 'fa:envelope',
+			group: ['trigger'],
+			version: 1,
+			subtitle: 'Gmail Trigger',
+			description: 'Fetches emails from Gmail on polling intervals with token caching',
+			defaults: { name: 'Gmail Trigger Custom' },
+			polling: true,
+			inputs: [],
+			outputs: ['main'],
+			properties: [
+				{
+					displayName: 'Service Account Email',
+					name: 'serviceAccountEmail',
+					type: 'string',
+					default: '',
+					required: true,
+					placeholder: 'sa-name@project.iam.gserviceaccount.com',
+					description: 'The service account client_email (issuer for JWT)',
+				},
+				{
+					displayName: 'Private Key',
+					name: 'privateKey',
+					type: 'string',
+					typeOptions: { password: true },
+					default: '',
+					required: true,
+					description: 'The service account RSA private key in PEM format',
+				},
+				{
+					displayName: 'Delegated Email',
+					name: 'delegatedEmail',
+					type: 'string',
+					default: '',
+					required: true,
+					placeholder: 'user@domain.com',
+					description: 'The Gmail mailbox to access (user to impersonate via domain-wide delegation)',
+				},
+				{
+					displayName: 'Simplify',
+					name: 'simple',
+					type: 'boolean',
+					default: true,
+					description: 'Whether to return a simplified version of the response instead of the raw data',
+				},
+				{
+					displayName: 'Filters',
+					name: 'filters',
+					type: 'collection',
+					placeholder: 'Add Filter',
+					default: {},
+					options: [
+						{
+							displayName: 'Include Spam and Trash',
+							name: 'includeSpamTrash',
+							type: 'boolean',
+							default: false,
+							description: 'Whether to include messages from SPAM and TRASH in the results',
+						},
+						{
+							displayName: 'Include Drafts',
+							name: 'includeDrafts',
+							type: 'boolean',
+							default: false,
+							description: 'Whether to include email drafts in the results',
+						},
+						{
+							displayName: 'Label Names or IDs',
+							name: 'labelIds',
+							type: 'string',
+							default: '',
+							description: 'Comma-separated label IDs to filter',
+						},
+						{
+							displayName: 'Search',
+							name: 'q',
+							type: 'string',
+							default: '',
+							placeholder: 'has:attachment',
+							description: 'Gmail search query. See <a href="https://support.google.com/mail/answer/7190">Gmail search syntax</a>.',
+						},
+						{
+							displayName: 'Read Status',
+							name: 'readStatus',
+							type: 'options',
+							default: 'unread',
+							options: [
+								{ name: 'Unread and read emails', value: 'both' },
+								{ name: 'Unread emails only', value: 'unread' },
+								{ name: 'Read emails only', value: 'read' },
+							],
+						},
+						{
+							displayName: 'Sender',
+							name: 'sender',
+							type: 'string',
+							default: '',
+							hint: 'Enter an email or part of a sender name',
+						},
+					],
+				},
+			],
+		};
+	}
+
+	async poll() {
+		const webhookName = 'default';
+		const workflowStaticData = this.getWorkflowStaticData('node') || {};
+		if (!workflowStaticData[webhookName]) {
+			workflowStaticData[webhookName] = {};
+		}
+		const nodeStaticData = workflowStaticData[webhookName];
+
+		const now = Math.floor(Date.now() / 1000);
+
+		if (this.getMode() !== 'manual') {
+			nodeStaticData.lastTimeChecked = nodeStaticData.lastTimeChecked || now;
+		}
+		const startDate = nodeStaticData.lastTimeChecked || now;
+
+		const serviceAccountEmail = this.getNodeParameter('serviceAccountEmail', 0) || '';
+		const privateKey = this.getNodeParameter('privateKey', 0) || '';
+		const delegatedEmail = this.getNodeParameter('delegatedEmail', 0) || '';
+		const simple = this.getNodeParameter('simple', 0);
+		const filters = this.getNodeParameter('filters', 0, {});
+
+		const accessToken = await getOrRefreshAccessToken(this, serviceAccountEmail, privateKey, delegatedEmail);
+
+		const responseData = [];
+		const allFetchedMessages = [];
+
+		const getEmailDateAsSeconds = (email) => {
+			let date;
+			if (email.internalDate) {
+				date = Math.floor(parseInt(email.internalDate, 10) / 1000);
+			}
+			if (!date || isNaN(date)) {
+				return startDate;
+			}
+			return date;
+		};
+
+		const fetchAndProcessMessage = async (messageId, fetchQs) => {
+			const fullMessage = await this.helpers.httpRequest({
+				method: 'GET',
+				url: `https://gmail.googleapis.com/gmail/v1/users/me/messages/${messageId}`,
+				headers: { Authorization: `Bearer ${accessToken}` },
+				qs: fetchQs,
+			});
+
+			allFetchedMessages.push({
+				id: fullMessage.id,
+				date: getEmailDateAsSeconds(fullMessage),
+			});
+
+			if (!filters.includeDrafts && fullMessage.labelIds && fullMessage.labelIds.includes('DRAFT')) {
+				return;
+			}
+			if (fullMessage.labelIds && fullMessage.labelIds.includes('SENT') && !fullMessage.labelIds.includes('INBOX')) {
+				return;
+			}
+
+			if (simple) {
+				responseData.push({ json: fullMessage });
+			} else {
+				responseData.push({ json: fullMessage });
+			}
+		};
+
+		try {
+			const qs = {};
+			const parts = [];
+
+			if (!simple) {
+				qs.format = 'raw';
+			} else {
+				qs.format = 'metadata';
+				qs.metadataHeaders = ['From', 'To', 'Cc', 'Bcc', 'Subject'];
+			}
+
+			if (this.getMode() !== 'manual') {
+				parts.push(`after:${startDate}`);
+			}
+
+			if (filters.includeSpamTrash) {
+				parts.push('in:anywhere');
+			} else {
+				parts.push('-in:spam -in:trash');
+			}
+
+			if (filters.readStatus === 'unread') {
+				parts.push('is:unread');
+			} else if (filters.readStatus === 'read') {
+				parts.push('is:read');
+			}
+
+			if (filters.sender) {
+				parts.push(`from:${filters.sender}`);
+			}
+
+			if (filters.labelIds) {
+				for (const labelId of filters.labelIds.split(',')) {
+					parts.push(`label:${labelId.trim()}`);
+				}
+			}
+
+			if (filters.q) {
+				parts.push(filters.q);
+			}
+
+			parts.push('-in:scheduled');
+
+			qs.q = parts.join(' ');
+
+			if (this.getMode() === 'manual') {
+				qs.maxResults = 1;
+			}
+
+			const messagesResponse = await this.helpers.httpRequest({
+				method: 'GET',
+				url: 'https://gmail.googleapis.com/gmail/v1/users/me/messages',
+				headers: { Authorization: `Bearer ${accessToken}` },
+				qs,
+			});
+
+			const messages = messagesResponse.messages || [];
+
+			if (!messages.length && !allFetchedMessages.length) {
+				return null;
+			}
+
+			const possibleDuplicates = new Set(nodeStaticData.possibleDuplicates || []);
+			const filteredMessages = possibleDuplicates.size > 0
+				? messages.filter((m) => !possibleDuplicates.has(m.id))
+				: messages;
+
+			if (!filteredMessages.length && !allFetchedMessages.length) {
+				return null;
+			}
+
+			const fetchQs = {};
+			if (!simple) {
+				fetchQs.format = 'raw';
+			} else {
+				fetchQs.format = 'metadata';
+				fetchQs.metadataHeaders = ['From', 'To', 'Cc', 'Bcc', 'Subject'];
+			}
+
+			for (const message of filteredMessages) {
+				await fetchAndProcessMessage(message.id, fetchQs);
+			}
+		} catch (error) {
+			if (this.getMode() === 'manual' || !nodeStaticData.lastTimeChecked) {
+				throw error;
+			}
+			try {
+				this.logger.error(`Gmail Trigger Custom poll error: ${error.message}`);
+			} catch (e) {}
+		}
+
+		if (!allFetchedMessages.length) {
+			return null;
+		}
+
+		const lastEmailDate = allFetchedMessages.reduce(
+			(last, m) => (m.date > last ? m.date : last), 0,
+		);
+
+		nodeStaticData.possibleDuplicates = allFetchedMessages.map((m) => m.id);
+		nodeStaticData.lastTimeChecked = Math.max(lastEmailDate || startDate, startDate);
+
+		return responseData.length > 0 ? [responseData] : null;
+	}
+}
+
+module.exports = {
+	nodeTypes: [GmailTriggerCustom],
+	GmailTriggerCustom,
+};

package/nodes/GmailCustom/utils.js

@@ -0,0 +1,90 @@
+const crypto = require('crypto');
+
+let jwtLib;
+try { jwtLib = require('jsonwebtoken'); } catch (e) {}
+
+const TOKEN_CACHE = {};
+
+function formatPrivateKey(privateKey) {
+	if (privateKey.includes('\\n')) {
+		return privateKey.replace(/\\n/g, '\n');
+	}
+	return privateKey;
+}
+
+function base64UrlEncode(str) {
+	return Buffer.from(str)
+		.toString('base64')
+		.replace(/=/g, '')
+		.replace(/\+/g, '-')
+		.replace(/\//g, '_');
+}
+
+function base64urlEscape(base64) {
+	return base64.replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+
+async function getOrRefreshAccessToken(ctx, serviceAccountEmail, privateKeyRaw, delegatedEmail) {
+	const cacheKey = `${serviceAccountEmail}:${delegatedEmail}`;
+	let token = TOKEN_CACHE[cacheKey];
+	if (token && token.expiresAt > Date.now()) {
+		return token.accessToken;
+	}
+
+	const privateKey = formatPrivateKey(privateKeyRaw);
+	const now = Math.floor(Date.now() / 1000);
+
+	let jwt;
+	const payload = {
+		iss: serviceAccountEmail,
+		scope: 'https://mail.google.com/',
+		aud: 'https://oauth2.googleapis.com/token',
+		exp: now + 3600,
+		iat: now,
+		sub: delegatedEmail,
+	};
+
+	if (jwtLib) {
+		jwt = jwtLib.sign(payload, privateKey, {
+			algorithm: 'RS256',
+			header: { kid: privateKey, typ: 'JWT', alg: 'RS256' },
+		});
+	} else {
+		const header = { alg: 'RS256', typ: 'JWT', kid: privateKey };
+		const signatureInput = base64UrlEncode(JSON.stringify(header)) + '.' + base64UrlEncode(JSON.stringify(payload));
+		const signer = crypto.createSign('RSA-SHA256');
+		signer.update(signatureInput);
+		const sig = signer.sign(privateKey);
+		jwt = signatureInput + '.' + base64urlEscape(sig.toString('base64'));
+	}
+
+	const response = await ctx.helpers.httpRequest({
+		method: 'POST',
+		url: 'https://oauth2.googleapis.com/token',
+		headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+		body: new URLSearchParams({
+			grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+			assertion: jwt,
+		}).toString(),
+	});
+
+	TOKEN_CACHE[cacheKey] = {
+		accessToken: response.access_token,
+		expiresAt: Date.now() + 3500 * 1000,
+	};
+
+	return response.access_token;
+}
+
+function clearTokenCache(serviceAccountEmail, delegatedEmail) {
+	delete TOKEN_CACHE[`${serviceAccountEmail}:${delegatedEmail}`];
+}
+
+module.exports = {
+	formatPrivateKey,
+	base64UrlEncode,
+	base64urlEscape,
+	getOrRefreshAccessToken,
+	clearTokenCache,
+	TOKEN_CACHE,
+};

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "n8n-nodes-gmail-custom",
-	"version": "0.3.0",
-	"description": "Custom Gmail node for n8n with token caching and 429 retry",
+	"version": "0.5.0",
+	"description": "Custom Gmail nodes for n8n with token caching — Send and Trigger, self-contained credentials",
 	"keywords": [
 		"n8n-community-node-package",
 		"n8n",
@@ -19,7 +19,8 @@
 		"n8nNodesApiVersion": 1,
 		"credentials": [],
 		"nodes": [
-			"nodes/GmailCustom/GmailCustom.node.js"
+			"nodes/GmailCustom/GmailCustom.node.js",
+			"nodes/GmailCustom/GmailTriggerCustom.node.js"
 		]
 	}
 }