message/send

Send a new email from the authenticated Gmail account.

When to Use

Automated customer onboarding: Trigger a welcome email immediately after a new user registration event completes in the workflow.
Invoice delivery: Send a PDF invoice attachment to a customer after payment confirmation is received from the billing system.
Password reset emails: Dispatch transactional reset links from the authenticated Gmail account as part of a security workflow.
Order shipment notifications: Notify customers with tracking details when an order status changes to "shipped" in the fulfillment system.
Scheduled newsletter dispatch: Send a weekly digest or newsletter to a subscriber list compiled from a CRM data source.

Configuration

Connection

Field	Type	Description
`credentialId`	Guid required	OAuth2 credential ID from the BizFirst Credentials Manager. Requires `gmail.send` scope.

Operation Fields

Field	Type	Default	Description
`sendTo`	string required	—	Recipient email address. Supports expressions. Use comma-separated values for multiple recipients (prefer `ccList`/`bccList` for secondary recipients).
`subject`	string required	—	Email subject line. Supports expressions.
`message`	string required	—	Email body content. HTML or plain text depending on `emailType`.
`emailType`	enum optional	`html`	Content type: `html` or `text`. Use `html` for rich formatted emails.
`senderName`	string optional	—	Display name for the sender (e.g. "BizFirst Support"). Appears in the recipient's inbox as the sender name.
`replyTo`	string optional	—	Reply-To email address. When set, replies go to this address instead of the sender.
`ccList`	string optional	—	Comma-separated CC recipient email addresses.
`bccList`	string optional	—	Comma-separated BCC recipient email addresses. Recipients are hidden from each other.
`attachmentBinaryFields`	string[] optional	—	Array of binary field names from previous node outputs to attach. Each referenced field must contain binary data (file content).
`appendAttribution`	bool optional	`false`	When `true`, appends a "Sent via BizFirstAI" attribution footer to the email body.

Sample Configuration

{
  "nodeType": "Gmail",
  "operation": "message/send",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "sendTo": "{{customer.email}}",
  "subject": "Welcome to {{company.name}}!",
  "message": "<h2>Welcome, {{customer.firstName}}!</h2><p>Your account is ready.</p>",
  "emailType": "html",
  "senderName": "BizFirst Onboarding",
  "replyTo": "support@bizfirstai.com",
  "ccList": "manager@bizfirstai.com",
  "attachmentBinaryFields": ["welcomePackPdf"],
  "appendAttribution": false
}

Validation Errors

Error	Cause	Resolution
`MISSING_FIELD: sendTo`	`sendTo` is empty or not provided	Ensure the recipient email field resolves to a non-empty string at runtime
`MISSING_FIELD: subject`	`subject` is empty or not provided	Provide a subject line; use a fallback expression if dynamic
`MISSING_FIELD: message`	Email body is empty	Ensure the message field resolves to non-empty content
`INVALID_CREDENTIAL`	`credentialId` not found or OAuth token expired	Re-authenticate the credential in BizFirst Credentials Manager
`QUOTA_EXCEEDED`	Daily send limit reached (500 personal / 2000 Workspace)	Wait for quota reset or switch to a Google Workspace account
`INVALID_EMAIL: sendTo`	Malformed email address in recipient field	Validate email format before passing to the node

Output

Success Port

On successful send, the node emits the following fields on the success output port:

Field	Type	Description
`messageId`	string	Unique Gmail message ID of the sent email
`threadId`	string	Thread ID the message was added to
`labelIds`	string[]	Labels applied to the message at send time (e.g. `["SENT"]`)
`status`	string	Execution status: `success`
`errorCode`	string	Empty on success

Error Port

On failure, the node routes to the error port with status: "error", errorCode, and errorMessage fields. Use a CatchBlock node downstream to handle errors gracefully.

Sample Output

{
  "messageId": "18e4a2f9d3c0b1a7",
  "threadId": "18e4a2f9d3c0b1a7",
  "labelIds": ["SENT"],
  "status": "success",
  "errorCode": ""
}

Expression Reference

Expression	Resolves To	Example Use
`{{customer.email}}`	Recipient email from upstream data	`sendTo` field
`{{customer.firstName}}`	Customer first name for personalization	`message` body
`{{order.id}}`	Order identifier for subject line	`subject` field
`{{invoice.pdfBinary}}`	Binary PDF data from upstream node	`attachmentBinaryFields`
`{{$now \| dateFormat:'YYYY-MM-DD'}}`	Current date formatted	Dynamic subject or body date

Node Policies & GuardRails

Policy	Rule
Credential Storage	Store OAuth credentials in BizFirst Credentials Manager — never hardcode tokens in workflow configuration
Daily Send Limit	Personal Gmail: 500 messages/day; Google Workspace: 2,000/day — implement rate limiting in high-volume workflows
PII Protection	Do not log email body content in workflow execution history — messages may contain PII
Quota Management	message.send costs 100 Gmail API quota units — monitor usage against the 250 units/user/second ceiling
Test Isolation	Test send workflows with a dedicated Gmail test account before connecting a production inbox
Attachment Safety	Validate attachment binary fields are non-empty before invoking; empty binary fields cause send failures

Examples

Example 1: Customer Welcome Email with Attachment

After a new customer record is created in the CRM, send a branded welcome email with a PDF guide attached.

{
  "nodeType": "Gmail",
  "operation": "message/send",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "sendTo": "{{crm.newCustomer.email}}",
  "subject": "Welcome to BizFirst — Your Getting Started Guide",
  "message": "<h2>Hi {{crm.newCustomer.name}},</h2><p>Welcome aboard! Find your Getting Started Guide attached.</p>",
  "emailType": "html",
  "senderName": "BizFirst Team",
  "attachmentBinaryFields": ["gettingStartedPdf"]
}

Example 2: Invoice Delivery on Payment Confirmation

After a Stripe payment webhook triggers and the invoice PDF is generated, send the invoice to the customer.

{
  "nodeType": "Gmail",
  "operation": "message/send",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "sendTo": "{{payment.customerEmail}}",
  "subject": "Invoice #{{invoice.number}} — Payment Confirmed",
  "message": "<p>Thank you for your payment of <strong>{{invoice.amount}}</strong>. Your invoice is attached.</p>",
  "emailType": "html",
  "bccList": "billing-archive@bizfirstai.com",
  "attachmentBinaryFields": ["invoicePdfBinary"]
}

Example 3: Weekly Newsletter Dispatch

A ScheduledTrigger fires every Monday, compiles a newsletter from a CMS data source, and sends it to a subscriber list.

{
  "nodeType": "Gmail",
  "operation": "message/send",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "sendTo": "{{subscriber.email}}",
  "subject": "BizFirst Weekly — {{$now | dateFormat:'MMMM D, YYYY'}}",
  "message": "{{newsletter.htmlContent}}",
  "emailType": "html",
  "senderName": "BizFirst Newsletter",
  "replyTo": "newsletter@bizfirstai.com"
}