File Format - Outreach Templated SMS

Outreach Templated SMS File Format

The Outreach Templated SMS file allows integrators to send SMS 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 SMS CSV file must be the header row. Each subsequent row creates a separate outreach job.

File Prefix: TOTS

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 SMS entity.

CSV HeaderData TypeRequiredDescription
Template IDstringYesTemplate UUID or External ID
Employee IDstringYesEmployee UUID or External ID — required if template has employee replacement terms, or if From is not provided
Customer IDstringYesCustomer UUID or External ID — required if template has customer replacement terms, or if To is not provided
Store IDstringYesStore UUID or External ID — required if template has store replacement terms
TostringYesRecipient phone number override (E.164 format). If left blank, the system resolves the address from the Customer ID.
FromstringYesSender phone number override. If left blank, the system resolves the address from the Employee ID or template/configuration defaults.
Campaign IDstringNoLinks the dispatch to a campaign
Expiry DatestringNoExpiration 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 DatestringNoScheduled 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:

  1. If To is provided, use it directly
  2. If not provided, get the customer’s primary phone number
  3. If no primary is set and multiple exist, use the one with the most recent date_created
  4. If the customer has no phone number, the request fails

Sender (From) fallback logic:

  1. If From is provided, use it directly
  2. If not provided, use the employee’s phone number
  3. If the employee has no phone number, fall back to the template’s configured sender
  4. Final fallback: use the default sender from the Outreach Configuration (textMessageDefaultSender)

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).
  • Phone numbers must include country code (e.g., +12267903132).
  • If To or From are 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 SMS CSV Example

See the following Outreach Templated SMS CSV sample file.

Outreach Templated SMS Sample 1

← File Format - Inventory
[DEPRECATED] File Format - Employee →