Sending Communications from a Workflow
Overview
You can trigger a communication to a gaiia entity — such as an account, user, or commercial account — directly from a workflow using a custom communication template. When this step runs, gaiia checks the entity's communication preferences, picks the right channel (email, SMS, or both), and hands the message off for delivery automatically.
In this article, we'll be covering how to set up a workflow step that sends a communication, what each input controls, and how to interpret the response.
Understand how it works
Before sending anything, gaiia performs a series of checks:
It looks up the entity you specified and retrieves its communication preferences, including which channels are enabled and what language it uses.
It finds the template you referenced and checks whether a variation exists for the entity's language.
It confirms that at least one enabled template variation matches a channel the entity has turned on (email or SMS).
It verifies that the necessary contact information (email address or phone number) is on file for the channels being used.
If all checks pass, gaiia passes the message to the notification service and records a delivery history entry.
A successful response means the message was accepted for delivery — not that it has been delivered yet. Whether the message ultimately reaches the recipient is tracked separately in notification history and is not reflected in the workflow step's response.
If any check fails, the step returns an error code and no message is sent. The workflow continues normally — these are expected outcomes, not failures that stop execution.
Set it up
Add a gaiia GraphQL node to your workflow. The node has two input sections: Query and Variables. Use the Query section for the mutation itself and the Variables section to pass in dynamic values from your gaiia data.
The mutation accepts the following inputs:
Entity — the GlobalID of the entity receiving the communication. Supported types: Account, CommercialAccount, PropertyGroup, PropertyGroupManager, User. Archived entities are treated as not found.
Template — the GlobalID of the custom communication template to use. You can use a system template instead, with
fromSystemCommunicationTemplateSlugand the template's slug.Importance (optional) — delivery priority. HIGH for prioritized delivery, DEFAULT for standard. Omitting this defaults to standard. Set it inside
metadata.Description (optional) — a free-text label attached to the delivery record, up to 1,000 characters. Useful for identifying what triggered the send when reviewing communication history. Set it inside
metadata.Document attachments (optional) — documents to attach to the email, set inside
metadataasdocumentAttachments. See Generate and email a document.Variables (optional) — custom merge tags to use in the template, added to the common merge tags.
Example
Here is a working example of how you'd send communications using the gaiia GraphQL API node, assuming the workflow has a Manual trigger on an object.
You can copy the following into the Query and Variables sections of the node. Update the values in the Variables section to match your workflow's data.
Query
mutation SendCommunication($entityId: GlobalID!, $templateId: GlobalID!) {
sendCommunication(
input: {entity: {id: $entityId}, template: {fromCustomCommunicationTemplateId: {templateId: $templateId}}}
) {
errors {
message
code
}
}
}Variables
const inputFunction: NodeStateFunction = ({ secrets, state, utils, variables }) => {
return {
entityId: state.objectId,
templateId: 'custom_communication_template_vRe9UrXSw5Yj6v6jsAc5VG'
};
};A successful response returns an empty errors array, indicating the message was accepted for delivery. If a pre-flight check fails, one error object is returned with a code and message — and no message is sent.
Generate and email a document
A workflow can turn one of your custom document templates into a PDF and email it to the account in two steps. Use two gaiia GraphQL nodes, one after the other.
A. Generate the document
The createDocumentFromTemplate mutation renders a custom document template as a PDF, adds it to the entity's Documents tab and returns the new document's ID.
Entity: the GlobalID of an Account, CommercialAccount or PropertyGroup.
Template ID: the GlobalID of a custom document template, shown in the template's side panel. The document is rendered in the entity's language, or in your default language when the template has no version in the entity's language.
Name (optional): the document's name, up to 255 characters. It defaults to the file name set on the template, and
.pdfis added when missing.Variables (optional): custom merge tags to use in the document.
mutation CreateDocument($entityId: GlobalID!, $templateId: GlobalID!) {
createDocumentFromTemplate(input: {entity: {id: $entityId}, templateId: $templateId}) {
documentId
errors {
message
code
}
}
}The mutation can return these error codes: ENTITY_NOT_FOUND, TEMPLATE_NOT_FOUND (the template doesn't exist or isn't a document template), NO_TEMPLATE_VARIATION_FOR_LANGUAGE, TEMPLATE_RENDER_FAILED and DOCUMENT_CREATION_FAILED.
B. Email the document
In the next node, pass the returned documentId to sendCommunication in metadata.documentAttachments. If the first node is named create-document, the ID is available as state.steps['create-document'].output.createDocumentFromTemplate.documentId.
mutation SendCommunication($entityId: GlobalID!, $templateId: GlobalID!, $documentId: GlobalID!) {
sendCommunication(
input: {entity: {id: $entityId}, template: {fromCustomCommunicationTemplateId: {templateId: $templateId}}, metadata: {documentAttachments: [{documentId: $documentId}]}}
) {
errors {
message
code
}
}
}Attachments follow these rules:
You can attach up to 10 documents, totaling at most 10 MB.
Each document must be linked to the entity receiving the communication.
Attachments are sent by email only. A communication that goes out by email and SMS attaches the documents to the email. A communication that would only go out by SMS is refused with ATTACHMENTS_REQUIRE_EMAIL, and nothing is sent.
Understand error responses
When a pre-flight check fails, the response includes one of the following error codes. These do not throw an exception or stop workflow execution — the step resolves normally and returns the error in the errors field.
ENTITY_NOT_FOUND — The entity GlobalID doesn't match any active record, or the entity has been archived.
TEMPLATE_NOT_FOUND — The template GlobalID doesn't match any custom template available in that environment.
NO_TEMPLATE_VARIATION_ENABLED — The template exists, but no enabled variation is available for the entity's language. Check that a variation has been created and enabled for that language in your template configuration.
NO_MATCHING_ENTITY_PREFERENCE_FOR_CHANNELS — The entity has disabled all channels (email and SMS) that have an enabled template variation. At least one of the entity's enabled channels must match an available variation.
NO_CONTACT_INFO — The entity has a channel enabled, but no corresponding contact information on file (no email address for email, no phone number for SMS).
DOCUMENT_NOT_FOUND — A document in
documentAttachmentsdoesn't exist.DOCUMENT_NOT_LINKED_TO_ENTITY — A document in
documentAttachmentsisn't linked to the entity receiving the communication.ATTACHMENTS_REQUIRE_EMAIL — Documents were attached, but the communication wouldn't be sent by email.
ATTACHMENTS_TOO_LARGE — The attached documents total more than 10 MB.
EMAIL_TOO_LARGE — The email is too large, usually because its template embeds images instead of hosting them.
TEMPLATE_RENDER_FAILED — The template couldn't be rendered, usually because of an invalid merge tag.
We recommend reading the errors field in your workflow output to handle these cases explicitly — for example, by branching to a fallback step using a Condition node when an error code is present.
