From now on you won’t be able to create new sendouts with this feature. Instead, make magic using Journeys for fully automated communication flows.
Until 2023 Q1 you will still be able to update your content versions in existing automations.
The feature will be shut down in 2023 Q2.
Symplify Batch trigger enables organizations to automatically send a specific trigger based on the recipients transferred in a text file.
Here is a scenario that explains the basics of Symplify Batch trigger:
If your business needs to send email or SMS to a specific group of recipients on a regular basis, you can use Symplify Batch transactional to send these messages.
Batch transactionals can both be used by FTP file transfer (up next) and web service (rest API).
When a file is sent to Symplify a job will automatically send messages to the recipients in the file.
The solution contains support of version handling that makes it really easy to update the delivery that will be sent.
Setup overview for FTP file transfer
The setup of a Symplify Batch trigger consists of five parts:
- Symplify supplies a FTP or sFTP1 account and login information.
- A Symplify account administrator supplies user login information to Symplify.
- Create a trigger in Symplify for either an email or a SMS. This is done on Transactional > Create new. Information about the different steps is found here.
- Create a file according to the file format specifications described in this document.
- Set up a scheduled job that connects a specific filename with a specific trigger and also handles the scheduling on how often the system will look for a new file.
Please read this article about selecting fields to be included in the file.
File format
Data uploaded to Symplify for import must conform to the following specifications:
- Data must be sent as an unformatted plain text file.
- You must not surround data fields in quotes or double quotes.
- The first row in the file will be used as a mapping matrix to insert the file data into the correct property* in Symplify.
- New line must be represented by ASCII compatible characters (i.e. LF, CR or CR+LF). **
- The only allowed ASCII control chars are horizontal tab, space, carriage return and line feed.
- Column header names may only contain ASCII alphanumeric characters (A-Z a-z 0-9), e.g. no space or underscore.
- Mobile numbers must start with 00[country code] or +[country code], e.g. 0046 or +46 (where 46 is country code for Sweden).
- Allowed file extensions are .txt and .csv (+.zip if compressed).
- The file encoding should be UTF-8
- The file must be structured in a table format so that each line represents a table row with fields separated by a tab delimiter.
- The file must not include byte order mark (BOM).
* To map the correct column header in the file to a property in Symplify see to that correct information is entered in the mapping filed in Symplify. You can get a property and file header overview for your existing properties in Symplify on Account settings > (Audience) Recipient attributes.
** Each row in the file will generate one message.
Calendar and time fields
Date and time values are organized from the most to the least significant: year, month, day, hour, minute, second, and fraction of second.
Each date and time value has a fixed number of digits that must be padded with leading zeros.
Representations can be done in one of two formats: a basic format with a minimal number of separators or an extended format with separators added to enhance human readability. The separator used between date values (year, month and day) is the hyphen, while the colon is used as the separator between time values (hours, minutes, and seconds).
The time zone used in Symplify is Central European Time (CET).
Calendar dates
Symplify uses all-numeric data notation [yyyy]-[MM]-[dd]. A four-digit year [yyyy] is used to avoid the year 2000 problem. [MM] indicates a two-digit month of the year, 01 through 12. [dd] indicates a two-digit day of that month, 01 through 31.
For example, “the 5th of April 2014” is represented as “2014-04-05”.
Time
Symplify uses the 24-hour clock system. The accepted format is [hh]:[mm]:[ss].
It is acceptable to omit lower order time elements for reduced accuracy.
Date and time examples
2013-04-05 13:37
2014-12-11 20:00:00
Example layouts
Here is a simple example file layout with three columns (id, name and email address). The first row is a header row and indicates how the file is organized. The delimiter chosen for this layout is tab.
OriginalID<tab>firstname<tab>emailaddress
001<tab>paul<tab>paul.simon@example.com
002<tab>aretha<tab>a.franklin@example.com
003<tab>bruce<tab>the_boss@example.com
004<tab>madonna<tab>queen@example.com
Server details
You can use both sFTP and FTP protocols on their standard ports with the credentials obtained from Symplify support. The internet hostname of our file server is storage.carmamail.com
If you have any questions regarding the different file transfer methods please contact Symplify support.
We recommend our clients to use sFTP since this will encrypt the data when transferred to Symplify.
Import setup in Symplify
To get the trigger job running you need to, in Symplify, enter information about the trigger, when Symplify should look for a new file and where the file is to be found. This setting is called Scheduled job.
Please note that the trigger email must be created before you can complete your scheduled job.
Creating Scheduled jobs
The trigger job settings are found in Symplify: Account settings > (Integrations) Scheduled jobs.
You will then get an overview of all your current Schedule jobs. To create a new job click on the button Create new trigger job in the right upper corner.
Enter the name you want to give the specific job. The trigger you select is the one that will be sent when the Scheduled job is executed.
Schedule
In the dropdown you can choose what specific time you wish the job to run or if you wish the job to run in a specific interval. You can set a time slot (e.g. between 12.00-14.00 every day) or an interval (e.g. every 30 minutes).
If you want Symplify to search for a file on specific days you select the days you wish the Schedule job to run*. It is also possible to see the next five events by clicking the arrow by next runs.
* if no days are selected the schedule job will run every day.
PLEASE NOTE! Only one file will be processed each scheduled job.
File settings
The last setting you need to enter is where Schedule job will find the file: path, username and password information to the FTP.
The filename should be a fixes name, for example welcomemailSE.csv. Enter the name and path in the field “Filename format”. If you save the file in the root of your FTP account you don’t need to type any path except the filename. If you save the file in a subfolder enter the exact path to the file: welcometrigger/welcomemailSE.csv.
Use the supplied login credentials to connect to the server and upload the file to the root of your home folder. Allowed characters for file names are “A–Z 0–9 – _”.
As soon as a Schedule job is started it will rename the file to filename.archive.timestamp (timestamp is when the job started), example welcomemailSE.csv.archive.[timestamp].
Now you can check the progress of your job.
Setup overview for API file transfer
Readers are assumed to have some familiarity with Symplify's graphical interface and experience with the REST API. If not, please read this article for API overview.
Workflow
In order to start a job you will need to prepare a couple of things in Symplify.
A transactional must be created. It’s recommended to send this delivery to a test list manually to verify deliverability before any Jobs are started.
A list of type Normal must exist.
You must also prepare you recipient data. Please read the List import section in the main REST API documentation and familiarize yourself with how Imports are handled by Symplify.
To start a new Job a POST request with details specifying the Jobs delivery and list is sent.
POST <server>/rest/<customerId>/jobs/generation/fixed
{
"type": "TRIGGER",
"id": 234
}
Valid type values are:
- TRIGGER
The Id the JSON object will be interpreted as one of the delivery types above.
Symplify will process your request and respond with a confirmation that a new Job have been created. The response will look something like this.
{
"id":7202,
"campaignId":336858,(the ID of the active delivery in the trigger)
"listId":22265, (the ID of the list connected to the trigger)
"contentUploaded":false,
"feedback":[
{
"feedback":"WAITING_FOR_CONTENT",
"severity":"SEVERITY_INFO",
"timestamp":1441374310577
}]
}
Now it’s time to upload you recipient data. To construct the URL for this request you will need the Id value from the previous response.
POST <server>/rest/<customerId>/jobs/generation/fixed/<id>/recipients/automapping
The request must be sent with recipient specified as text/csv, tab separated with the first row containing column headers. It is highly recommended that before any data is sent to Symplify that mappings are prepared and reviewed in the Recipient attributes part of the Symplify web interface.
OriginalID<tab>firstname<tab>emailaddress
001<tab>paul<tab>paul.simon@example.com
002<tab>aretha<tab>a.franklin@example.com
003<tab>bruce<tab>the_boss@example.com
004<tab>madonna<tab>queen@example.com
After this request is completed generation of messages is automatically started. Progress of the job is shown in the feedback part in the response. To help you keep track of a Jobs progress requests can made to the following recourse. It will respond with a collection of feedback entries in the same manner as previous requests.
GET <server>/rest/<customerId>/jobs/generation/fixed/<id>
Raw HTTP examples
Request 1
POST http://<server>/rest/487/jobs/generation/fixed HTTP/1.1
Host: test.carmamail.com
Content-Length: 59
Authorization: Basic XXXX
Accept: application/json
{
"type": "TRIGGER",
"id": 234
}
Response 1
HTTP/1.1 200 OK
Content-Type: application/json
Server: Microsoft-IIS/7.5
X-Powered-By: ARR/2.5
X-Powered-By: ASP.NET
Date: Fri, 04 Sep 2015 13:45:10 GMT
Content-Length: 171
{"id":7202,"campaignId":336858,"listId":22265,"contentUploaded":false,"feedback":[{"feedback":"WAITING_FOR_CONTENT","severity":"SEVERITY_INFO","timestamp":1441374310577}]}
Request2
POST http://<server>/rest/487/jobs/generation/fixed/7202/recipients HTTP/1.1
Host: test.carmamail.com
Authorization: Basic XXX
Content-Type: text/csv;charset=UTF-8
Content-Length: 103
email originalid firstname
paul@example.com 1 paul
a.franklin@example.com 2 aretha
theboss@example.com 3 bruce
Response2
HTTP/1.1 200 OK
Content-Type: application/json
Server: Microsoft-IIS/7.5
X-Powered-By: ARR/2.5
X-Powered-By: ASP.NET
Date: Fri, 04 Sep 2015 13:57:47 GMT
Content-Length: 1124
{"id":7202,"campaignId":336858,"listId":22265,"contentUploaded":false,"feedback":[{"feedback":"WAITING_FOR_CONTENT","severity":"SEVERITY_INFO","timestamp":1441374310577},{"feedback":"UPLOADING_CONTENT","severity":"SEVERITY_INFO","timestamp":1441375034573},{"feedback":"UPLOADED_CONTENT","severity":"SEVERITY_INFO","timestamp":1441375034620},{"feedback":"STARTED_IMPORT","severity":"SEVERITY_INFO","timestamp":1441375067147}]}
Check progress of a Scheduled job
To see if your Scheduled job process is successful you can click on Feedback.
In Feedback it’s possible to follow the different steps and therefore see if your job runs successfully or if it’s failing, and if so, in which step the job failed.
Recipient status
The recipients in the file will be set as active on the current list when the job is completed.
Unsubscribed recipients will remain unsubscribed and therefore not receive any emails.
If a recipient have a hard bounced status no email will be sent.
Verifying the data
When the setup is completed you are responsible to verify that your data is represented correctly in Symplify. This can easily be done by exporting all property values from the list in Symplify and analyse it.