Send batch transactional - file setup
Introduction
Carma Batch trigger enables organizations to automatically send a specific trigger based on the recipients transferred in a text file to Carma FTP or SFTP.
Here is a scenario that explains the basics of Carma Batch trigger:
If your business needs to send email or SMS to a specific group of recipients on a regular basis, you can use Carma Batch trigger to send these messages. Carma batch trigger solution can both be used by file transfer and web service (rest API).
When a file is sent to Carma a job will automatically send messages to the recipients in the file.
The trigger solution contains support of version handling that makes it really easy to update the email that will be sent.
Setup overview
The setup of a Carma Batch trigger consists of five parts.
1. Compost supplies a FTP or sFTP1 account and login information.
2. A Carma account administrator supplies user login information to Carma.
3. Create a trigger in Carma for either an email or a SMS. This is done on Transactional > Create new. Information about the different steps is found here.
4. Create a file according to the file format specifications described in this document.
5. 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.
Choosing fields to be included in the file
What data that should be included in the file depends on what data you wish to either be presented in the sending or what data should be used for segmenting the content of the send out. Select only data that is relevant to your email content and segmentation needs to minimize unnecessary export and import time.
In some cases it’s only necessary to import email addresses or phone numbers. One requirement is that the recipients in your import file are identified by an id. This can be a primary key from a database or anything else that uniquely identify each recipient. The result of this is that the simplest import file must at least contain two columns (id and email address/phone number).
When no suitable id for recipients can be found you can choose to identify recipients by their email address or phone number. This is an inferior method and by doing so recipients that change their email address or phone number will be treated as new recipients in the system.
To map the correct column header in the file to a property in Carma see to that correct information is entered in the mapping filed in Carma: Account settings > Profile attributes (below image). If a new column header is sent to Carma that hasn’t been added before, Carma will automatically create the new property.
File format
Data uploaded to Carma 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 Carma.
. Newline 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 Carma see to that correct information is entered in the mapping filed in Carma. You can get a property and file header overview for your existing properties in Carma on Account settings > Profile 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 Carma is Central European Time (CET).
Calendar dates
Carma 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
Carma 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.
Id <tab>name <tab>emailaddress
001 <tab>paul <tab>pm@compost.se
002 <tab>lars <tab>lh@compost.se
003 <tab>vegar <tab>vl@compost.se
004 <tab>tobbe <tab>th@compost.se
Server details
You can use both sFTP and FTP protocols on their standard ports with the credentials obtained from Carma 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 Carma support.
We recommend our clients to use sFTP since this will encrypt the data when transferred to Carma.
Import setup in Carma
To get the trigger job running you need to, in Carma, enter information about the trigger, when Carma 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.
Information about the different steps in a trigger setup is found in our Carma online FAQ.
Creating Scheduled jobs
The trigger job settings are found in Carma: Account settings > Scheduled jobs (> Create new trigger job).
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 wish 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 Carma 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].
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 Carma. This can easily be done by exporting all property values from the list in Carma and analyse it.