File Format - Outreach Templated Email
Outreach Templated Email File Format
The Outreach Templated Email file allows integrators to send email messages that use a pre-configured template through Tulip’s Outreach system. Templates are configured in Admin Console and support replacement terms (dynamic variables) that are populated at processing time using the provided context entities.
The first line of an Outreach Templated Email CSV file must be the header row. Each subsequent row creates a separate outreach job.
File Prefix: TOTE
Feature Gate: The environment must have outreach-plus enabled; otherwise, the file will fail to upload any records successfully.
Spec
The following table shows the accepted CSV columns for the Outreach Templated Email entity.
| CSV Header | Data Type | Required | Description |
|---|---|---|---|
Template ID | string | Yes | Template UUID or External ID |
Employee ID | string | Yes | Employee UUID or External ID — required if template has employee replacement terms, or if From is not provided |
Customer ID | string | Yes | Customer UUID or External ID — required if template has customer replacement terms, or if To is not provided |
Store ID | string | Yes | Store UUID or External ID — required if template has store replacement terms |
To | string | Yes | Recipient email address override. If left blank, the system resolves the address from the Customer ID. |
From | string | Yes | Sender email address override. If left blank, the system resolves the address from the Employee ID or template/configuration defaults. |
Campaign ID | string | No | Links the dispatch to a campaign |
Expiry Date | string | No | Expiration time in UTC ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). If the message has not been dispatched by this date, it will be marked as Expired. |
Start Date | string | No | Scheduled send time in UTC ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). If in the future, the message is held until this time. |
Sender and Recipient Resolution
For templated files, the To and From fields can be left blank. If not provided, the system resolves them from the context entities:
Recipient (To) fallback logic:
- If
Tois provided, use it directly - If not provided, get the customer’s primary email address
- If no primary is set and multiple exist, use the one with the most recent
date_created - If the customer has no email address, the request fails
Sender (From) fallback logic:
- If
Fromis provided, use it directly - If not provided, use the employee’s email address
- If the employee has no email address, fall back to the template’s configured sender
- Final fallback: use the default sender from the Outreach Configuration (
emailDefaultSender)
Sender Name (From Name) fallback logic:
- Employee’s display name (full name)
- Template’s configured sender name
Replacement Terms
If a template contains replacement terms (e.g., {{employeename}}, {{customerfirstname}}, {{storename}}), the corresponding context entity must be provided. The template content is populated at the time the file is processed — the final resolved content is stored on the job record.
Important Notes
- All dates must be in UTC ISO 8601 format (
YYYY-MM-DDTHH:mm:ssZ). - If
ToorFromare left blank, the system resolves addresses from the Customer/Employee IDs. - Each CSV row creates a separate outreach job.
- Success/failure can be monitored in Admin Console under Outreach Jobs.
- A successfully processed row means the job has been accepted for sending. It does not guarantee delivery.
- Template replacement terms are resolved when the file is processed, not when the message is sent.
Outreach Templated Email CSV Example
See the following Outreach Templated Email CSV sample file.