How to Capture NetSuite Transaction Email Threads Using SuiteScript?

To ensure proper email threading and association with NetSuite records when sending emails programmatically, it is crucial to correctly configure the parameters for the SuiteScript email API. The N/email.send SuiteScript 2.x API is the current best practice for this functionality.

The N/email.send function requires an options JavaScript object to define its parameters. A very specific combination of these parameters is required to trigger email threading and record association:

• author: This parameter must be an employee internal ID.
• recipients: This parameter can be a customer record internal ID, a contact internal ID, or an email address directly.
• subject: The subject line of the email.
• body: The main content of the email.
• relatedRecords: This object is critical for associating the email with NetSuite records. For transactions, it should contain transactionId: transactionId. For customers or contacts, use entityId: entityId.
• attachments: An array of file.File objects to be attached.
• cc: An array of internal IDs or email addresses for carbon copy recipients.
• bcc: An array of internal IDs or email addresses for blind carbon copy recipients.

The following SuiteScript 2.x code demonstrates how to send an email and associate it with a transaction:

javascript
// Assuming 'email' module is loaded (e.g., via define(['N/email'], function(email) { ... }))
var SCRIPT_AUTHOR_ID = '786014'; // Employee Record Internal ID
var emailAuthor = SCRIPT_AUTHOR_ID;
var transactionId = 'YOUR_TRANSACTION_ID'; // Placeholder for actual transaction ID
var customerId = 'YOUR_CUSTOMER_ID';     // Placeholder for actual customer ID or email address
var emailSubject = 'YOUR_EMAIL_SUBJECT';
var emailBody = 'YOUR_EMAIL_BODY';
var emailAttachment = null; // Or an array of file.File objects

email.send({
    author: emailAuthor,
    recipients: customerId, // Can be an internal ID or an email address
    subject: emailSubject,
    body: emailBody,
    relatedRecords: {
        transactionId: transactionId
        // For associating with a customer/contact directly, use entityId: customerId
    },
    attachments: emailAttachment ? [emailAttachment] : null,
    cc: null, // Or an array of recipient IDs/emails
    bcc: null // Or an array of recipient IDs/emails
});

By default, the designated author of an email sent via SuiteScript does not receive a copy in their personal inbox, as NetSuite assumes the author initiated the communication. To ensure the author receives a copy, their email address can be included in the cc parameter of the N/email.send options object:

javascript
// Example of including the author's email in CC
email.send({
    author: emailAuthor,
    recipients: customerId,
    subject: emailSubject,
    body: emailBody,
    cc: ['author@email.com'], // Include author's email address here
    relatedRecords: {
        transactionId: transactionId
    }
    // ... other parameters like attachments, bcc
});

Behavior related to CC recipients and 'reply all' functionality may vary depending on email client configurations and specific NetSuite settings, and should be tested in your environment.

When configured correctly, emails sent using N/email.send will be captured and threaded on the associated transaction, customer, and employee records within NetSuite, providing a comprehensive communication history.