SFTP Messages

The /messages folder enables bulk message delivery via SFTP using CSV files and Handlebars templates. Messages are sent through the merchant's configured messaging products based on recipient address type and message content.

⚠️
Transactional Messages Only
Promotional messaging is not permitted. All messages must be transactional in nature.

Message Delivery Logic

The system dynamically determines the appropriate delivery method based on multiple factors including recipient type, message content, available products, and delivery preferences. The delivery logic is continuously updated to optimize message delivery and comply with regulatory requirements.

Common factors include:

Recipient address type: Email addresses use email messaging products, phone numbers use SMS/MMS/RCS.
Message content: Large messages automatically use MMS instead of SMS
Attachments: Phone numbers with attachments use MMS delivery
Product availability: Messages are only sent if the required messaging product is configured
Opt-out status: Messages are not delivered to opted-out addresses

Examples (not exhaustive):

Email address without email product → No message sent
Phone number with attachment → MMS delivery
Large message content → MMS instead of SMS
Opted-out recipient → Message blocked

Templates

Templates are written in Handlebars and support dynamic content through:

Variable interpolation: {{firstName}}, {{orderNumber}}
String manipulation: Format and transform text
Conditional logic: {{#if condition}}...{{/if}}
Merchant profile access: {{profile.friendlyName}} (automatically available)

📘
Template Creation Required
Contact [email protected] to create templates. Due to regulatory requirements, template creation is not self-service.

CSV File Format

Upload CSV files to the /messages folder. Use dot notation for nested objects and arrays.

Required Columns

Column	Description	Example
`to`	Recipient address (email/phone)	`[email protected]`
`template`	Template identifier	`order-confirmation`

Optional Columns

Column	Description	Example
`context.fieldName`	Template variables	`context.firstName`
`metadata.key`	Custom metadata	`metadata.campaign`
`attachments.0.name`	Attachment filename	`attachments.0.name`
`attachments.0.type`	MIME type	`attachments.0.type`
`attachments.0.url`	Download URL	`attachments.0.url`

Data Structure

Context Variables

Provide template variables using dot notation:

context.firstName,context.lastName,context.orderNumber,context.amount
John,Doe,ORD-12345,99.99

Metadata

Attach custom data to messages for ETL and reporting:

metadata.campaign,metadata.source,metadata.userId
summer-sale,import,user-123

Attachments

Specify file attachments using array notation (starting at 0):

attachments.0.name,attachments.0.type,attachments.0.url,attachments.1.name,attachments.1.type,attachments.1.url
invoice.pdf,application/pdf,https://example.com/invoice.pdf,receipt.pdf,application/pdf,https://example.com/receipt.pdf

Examples

Basic Message

to,template,context.firstName,context.orderNumber,context.amount
[email protected],order-confirmation,John,ORD-12345,99.99
[email protected],order-confirmation,Jane,ORD-12346,149.99

With Metadata

to,template,context.firstName,context.productName,metadata.campaign,metadata.source
[email protected],product-notification,Alice,Widget Pro,summer-sale,import
[email protected],product-notification,Bob,Widget Lite,summer-sale,import

With Attachments

to,template,context.firstName,attachments.0.name,attachments.0.type,attachments.0.url
[email protected],invoice-sent,John,invoice-123.pdf,application/pdf,https://example.com/invoices/invoice-123.pdf