n8n-nodes-gmail-custom 0.2.1 → 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');
 
@@ -161,19 +166,19 @@ async function buildMimeMessage(options) {
 		.replace(/=+$/, '');
 }
 
-async function getOrRefreshAccessToken(ctx, credentials, fromEmail) {
-	const cacheKey = `${credentials.email}:${fromEmail}`;
+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(credentials.privateKey);
+	const privateKey = formatPrivateKey(privateKeyRaw);
 	const now = Math.floor(Date.now() / 1000);
 
 	let jwt;
 	const payload = {
-		iss: credentials.email,
+		iss: serviceAccountEmail,
 		scope: 'https://mail.google.com/',
 		aud: 'https://oauth2.googleapis.com/token',
 		exp: now + 3600,
@@ -230,13 +235,25 @@ class GmailCustom {
 			},
 			inputs: ['main'],
 			outputs: ['main'],
-			credentials: [
+			properties: [
 				{
-					name: 'googleApi',
+					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',
 				},
-			],
-			properties: [
 				{
 					displayName: 'From Email',
 					name: 'fromEmail',
@@ -343,6 +360,33 @@ class GmailCustom {
 							default: '',
 							description: 'The email address that the reply message is sent to',
 						},
+						{
+							displayName: 'Sender Name',
+							name: 'senderName',
+							type: 'string',
+							default: '',
+							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',
+						},
 					],
 				},
 			],
@@ -360,6 +404,8 @@ class GmailCustom {
 		for (let i = 0; i < items.length; i++) {
 			try {
 				const item = items[i];
+				const serviceAccountEmail = this.getNodeParameter('serviceAccountEmail', i, '');
+				const privateKey = this.getNodeParameter('privateKey', i, '');
 				const fromEmail = this.getNodeParameter('fromEmail', i, '');
 				const sendTo = this.getNodeParameter('sendTo', i, '');
 				const subject = this.getNodeParameter('subject', i, '');
@@ -375,6 +421,22 @@ class GmailCustom {
 				let cc = options.ccList || '';
 				let bcc = options.bccList || '';
 				let replyTo = options.replyTo || '';
+				const senderName = options.senderName || '';
+
+				let fromHeader = fromEmail;
+				if (senderName) {
+					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 = '';
@@ -387,8 +449,7 @@ class GmailCustom {
 					bodyText = message;
 				}
 
-				const credentials = await this.getCredentials('googleApi');
-				const accessToken = await getOrRefreshAccessToken(this, credentials, fromEmail);
+				const accessToken = await getOrRefreshAccessToken(this, serviceAccountEmail, privateKey, fromEmail);
 
 				let attachments = [];
 				if (options.attachmentsUi && options.attachmentsUi.attachmentsBinary) {
@@ -414,7 +475,7 @@ class GmailCustom {
 				}
 
 				const base64UrlMessage = await buildMimeMessage({
-					from: fromEmail,
+					from: fromHeader,
 					to: sendTo,
 					cc,
 					bcc,
@@ -423,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.2.1",
+	"version": "0.4.0",
 	"description": "Custom Gmail node for n8n with token caching and 429 retry",
 	"keywords": [
 		"n8n-community-node-package",