A message is used to record correspondence you have with a specific business. Use the message record to add an email message to an existing customer, contact, or opportunity record. After an email message has been added to a record, any related emails are automatically attached to the same record as well as to any recipients of the original email.

The message record is defined in the generalComm (communication) XSD.

For information about adding an email message to a record in the NetSuite user interface, see Sending Email from Records.


Adding letters, PDFs, or faxes through SOAP web services is not supported.

Supported Operations

add | addList | delete | deleteList | get | getDeleted | getList | getSavedSearch | getSelectValue | search |


You can also use the asynchronous equivalents of SOAP web services list operations. For information about asynchronous operations, see SOAP Web Services Asynchronous Operations. For more information about request processing, see Synchronous Versus Asynchronous Request Processing.

Field Definitions

The SOAP Schema Browser includes definitions for all body fields, sublist fields, search filters, and search joins available to this record. For details, see the SOAP Schema Browser’s message reference page.


For information on using the SOAP Schema Browser, see SOAP Schema Browser.

Usage Notes

Message RecordRef Fields

Message recordref fields cannot be referred to by externalId.

Email Fields May Be Required

The following Email fields are required if the From or Attach to entity records do not have an email address specified. If you attempt to create a message without both of these fields specified, the request fails with a message about missing mandatory fields.


Label in UI



(From) Email Address

A string that includes the email address of the person writing the email. This email address is displayed as the From address in the email message that is sent to the recipient.


(To) Email Address

A string that includes the email address of the person receiving the email. This email address is the address to which the email message is sent..

Using the BCC and CC Fields on the Message Record

The bcc and cc fields represent the list of secondary email addresses associated with the message. These are string fields that accept a space deliminated list of email addresses. For endpoints prior to 2009.2, invalid email addresses in the bcc and cc fields do not result in errors. For the 2009.2 and later endpoints, invalid email addresses in the bcc and cc fields return Invalid Field Value errors.

Using the dateTime Field on the Message Record

The dateTime field is only included in 2009.2 and earlier endpoints. It contains the same value as the messageDate field, but in a different date format. If you use an endpoint later than 2009.2, use messageDate rather than the obsolete dateTime field.

Working with Attachments

You cannot update an attachment in the context of a message, but you can do so through an update operation on the file record. File records represent files that are stored in the NetSuite File Cabinet. Use the file record to define email attachments sent or received via the messages record. For additional usage notes on working with the file record, see File.

The file record is defined in the docFileCab (fileCabinet) XSD.


The schema has a data type of xsd:base64Binary which is mapped to a byte array in .NET and Axis (Java). On the client side we only need to pass a text or binary file as a byte array with no further base64 encoding. Therefore, do NOT Base64 Encode the file before sending it to Axis or .NET as these layers will do so themselves.

For example:

Storing Attachments

To maintain uniqueness for each file attachment, when attachments are stored in NetSuite two levels of sub-folders are automatically created for the Attachments Sent and Attachments Received respectively.

If the incoming field of the message record is set to false, the attachment is saved in the Attachments Sent folder. If the incoming filed is set to true, the attachment is saved in the Attachments Received folder.

The folder structure being generated is as follows:

For example:

A user is using auto email reply capture feature. They send a message to their contact John Smith from within the application. When the contact replies to the message they also attach a file to the message. When the message is created in NetSuite (through the auto reply capture feature) it is saved to a sub-folder that is created when the attachment is saved. The path to the sub-folder is as follows:

file cabinet > attachments received > Attachments Received > John Smith > 20050620_Message_525 > File.doc.


If an attachment is being stored with an extension that does not match the actual file type (for example a .txt file as a .exe file), the file is listed in NetSuite as other text or other binary but this is a label — there is no logical effect on the file.

Adding Messages

The following is a basic sample that shows how to add a message record.

SOAP Request

<preferences xmlns="">
<add xmlns="">
<record xsi:type="q1:Message" xmlns:q1="">
<q1:author internalId="-5" type="employee" />
<q1:recipient internalId="-5" type="employee" />
<q1:subject>-- subject goes here --</q1:subject>
<q1:message>This is a sample message</q1:message>
<q1:activity internalId="39" type="calendarEvent" />


SOAP Response

<ns1:documentInfo xmlns:ns1="">
<addResponse xmlns="">
<ns2:status isSuccess="true" xmlns:ns2="" />
<baseRef internalId="46" type="message" xsi:type="ns3:RecordRef"
xmlns:ns3="" />



          private void addMessage()

Message msg = new Message();

RecordRef activityref = new RecordRef();
activityref.internalId = "39";
activityref.type = RecordType.calendarEvent;
activityref.typeSpecified = true;
msg.activity = activityref;

RecordRef authorref = new RecordRef();
authorref.internalId = "-5";
authorref.type = RecordType.employee;
authorref.typeSpecified = true; = authorref;

RecordRef recipientref = new RecordRef();
recipientref.internalId = "-5";
recipientref.type = RecordType.employee;
recipientref.typeSpecified = true;
msg.recipient = recipientref;

DateTime searchDate = new DateTime();
searchDate = DateTime.Now;
searchDate = DateTime.Parse(searchDate.ToString("dd/MM/yyyy"));
msg.messageDate = searchDate;
msg.messageDateSpecified = true;

msg.subject = "-- subject goes here --";
msg.message = "This is a sample message";
msg.incoming = true;

WriteResponse writeRes = _service.add(msg);
if (writeRes.status.isSuccess)
_out.writeLn("\nThe message " + msg.internalId + " has been added successfully");


Related Topics

How to Use the SOAP Web Services Records Help
SOAP Web Services Supported Records
SOAP Schema Browser
SuiteTalk SOAP Web Services Platform Overview

General Notices