Messaging

Messages are Message records. Operations follow the standard QBO route pattern:

• /api/message/{operation} runs synchronously on the web server.
• /api/message/queue/{operation} queues the operation (for example on SQS) for an app server. Use it for bulk sends and mailbox polling.

Classes and fields

Type	Purpose
Message	One message, bound to a parent through Object / ObjectID. Key fields: Message (the subject), BodyText, BodyHTML, FromAddress, FromName, MessageTemplateID, ParentMessageID (thread), Priority, SecureDelivery, DateAdded.
MessageRecipient	One address on a message. Category is 0 To, 1 Cc, 2 Bcc, 3 ReplyTo. Tracks SentDate, ReceivedDate, and ReadDate.
MessageTemplate	Defaults for a kind of message: Subject, BodyHTML, BodyText, BodyXsltID, Method, FromAddress, FromName, and To/Cc/Bcc contacts or collections.
IMailOutbound	Sends email. Providers are named in MailOutbound configuration; the first is the default.
IMailInbound	Reads a mailbox. Configured per account in MailInbound, each with one or more IMailProcessor processors.

Generate and send from a template

GET /api/message/generate?Template=Status Update&Object=Contact&ObjectID=1&ToAddress=someone@example.com

generate creates the message from the template, merges data from the parent Object / ObjectID into the subject and body, adds the template’s default recipients, saves it, and sends it to any active recipients.

Parameter	Purpose
Template or MessageTemplateID	The message template, by name or ID.
Object, ObjectID	The parent record; its data is merged and the message is saved to it.
ToAddress, CcAddress, BccAddress, ReplyToAddress	Addresses to add (also accepted as To, Cc, Bcc, ReplyTo).
ToMethod, CcMethod, BccMethod, ReplyToMethod	A method signature returning Email or ContactID columns; each row becomes a recipient.
AttachmentID	One or more attachment IDs to send as email attachments.
Provider	The outbound provider to use, if not the default.
MergeSubstitution	false to send the subject and body without merging.

Other parameters are available to merge fields, so a caller can supply values that aren’t on the record. For a batch, queue it:

GET /api/message/queue/generate?Template=Status Update&Object=Contact&ObjectID=1

Related operations:

Operation	Saves	Sends
save	Yes	No
generate	Yes	Yes, if there are active recipients
saveemail	Yes	Yes
send	No	Yes. With an ID, re-sends an existing message, optionally to new addresses.

Create messages with a parent record

Messages can be created as a nested collection when saving a parent, using {Parent}_Messages_{index}_{Field}. For example, a workflow that creates an organization, its first contact, and a note in one call:

POST /api/decision/save?Template=Website Inquiry&Organization_Organization=Example Co&Organization_Contacts_0_FirstName=Maria&Organization_Contacts_0_Email=maria@example.com&Organization_Messages_0_Message=Pricing question&Organization_Messages_0_BodyText=Please send pricing.

Receive inbound email

GET /api/message/receive?Account=SupportInbox&MailKitLatest=true
GET /api/message/queue/receive?Account=SupportInbox&MailKitLatest=true

receive reads each configured Account (comma-separate several) and creates a Message for each new email, with a MessageRecipient for each To, Cc, and Bcc address and an Attachment for each file. An ObjectSubscription record per email ({Host}-{Account}-MailKit-Uid-{UniqueId}) prevents duplicates on later runs.

Parameter	Limits the search to
MailKitLatest=true	Emails newer than the last one imported for the account
HasEmail	Emails from, to, or copying an address
To, Cc, Bcc	Emails with that recipient
Sent, Delivered	Emails sent or delivered on a date or in a date range
Subject	Emails whose subject contains the text
Label	Gmail messages with that label

Receivers include ImapReceiver (IMAP), AzureReceiver (Exchange Online over IMAP with OAuth 2; the account password holds {tenantId}:{clientId}:{secretId}), and MicrosoftGraphReceiver.

Processors

Each account’s processors run in order. With MethodSignatureProcessor, the MessageStatement is a method signature (a bare statement name is treated as Message/{statement}):

• Returns rows: the message is saved with the first row’s values (for example Object, ObjectID, ParentMessageID, MessageTemplateID) and processing stops.
• Returns no rows: the next processor runs.
• Void or object operations: the operation runs and processing stops.

Message/BindByParentMessage?ID={MessageID}&ParentTemplate=Inbound Request&ChildTemplate=Inbound Reply

BindByParentMessage matches the newest earlier message whose subject (longer than SubjectLength, default 30) appears in the new subject, and returns its Object, ObjectID, and thread. ParentTemplate / ParentTemplateID is applied to new conversations and ChildTemplate / ChildTemplateID to replies.

Thread, track, and file

Operation	What it does
markread / markunread	Records or clears the current user’s read date on the messages in ID
listbyobject	Lists messages for an Object / ObjectID
search	Searches messages
saveaspdf	Renders the message (headers and body) as a PDF attachment on the message
classify	Calculates the score template ScoreTemplateID for each message in ID
watch	Imports text files from a file object (FileObject, Path, optional Pattern, Object, ObjectID, TemplateID, Statement, RemoveFile) as messages

GET /api/message/markread?ID=101,102
GET /api/message/saveaspdf?ID=101

Draft replies with AI

GET /api/message/airesponsedraft?ID=101&AgentName=Support
GET /api/message/airesponsesend?ID=101&AgentName=Support&IncludeRecipients=true

The AI agent named by AgentName receives the record’s data (the parent’s summary, or the message’s own if it has no parent) and the inbound body, and drafts an HTML reply. The reply is subject RE: {subject}, has the same Object / ObjectID, and is threaded through ParentMessageID. It’s addressed to the sender, or with IncludeRecipients=true, to the sender plus every original recipient.

Operation	Returns the draft	Saves	Sends
airesponsedraft	Yes	No	No
airesponsesave	Yes	Yes	No
airesponsesend	Yes	Yes	Yes

Parameters

The parameters shown are the commonly used ones. Check the operation’s method signature in source (paths listed under the page title) before relying on less common options.