Carma send campaign - file setup
Introduction
Carma Send Campaign enables organizations to automatically send a specific delivery based on the recipients transferred in a file to Carma FTP or sFTP.
A Carma user creates a campaign draft in Carma. A selection in your CRM system is made on recipients who should receive the specific campaign from Carma. The file with the recipients is then transferred from the CRM system to Carma. Based on the filename Carma will send the campaign to the recipients in the file. The filename should contain three parameters (deliveryID; ListID; Sendtime) for Carma to be able to understand what to do with the file.
Setup overview
The setup of a Send Campaign consists of four parts.
1. Compost supplies this document and FTP or sFTP1 login information.
2. Carma Send Campaign is setup on the account to monitor the FTP or sFTP for Send Campaign files.
3. A campaign draft is created in Carma.
4. You create a file according to the file format specifications described in this document and also follow the specific filename pattern.
* Carma also support Secure Copy over SSH. This file transfer method provides greater security.
PLEASE NOTE! We recommend that you use Carma REST API to get the correct delivery and ListID into the file name.
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).
If 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.
PLEASE NOTE! Don’t start an upload of a new file until the previous file has been renamed since this will risk that you overwrite a file that hasn’t yet been processed by Schedule imports.
Collection fields
To reduce the number of fields it’s sometimes convenient to merge a collection of properties to a single field. This can greatly reduce the time spent creating filters and managing properties in Carma.
To create a Collection field you will have to select a new set of delimiters that’s different from your normal field separator. The data is written to the Collection field delimited by this new separator according to the following specifications:
. Each value in the Collection field must start with the Collection field start delimiter
. Each value in the Collection field must end with the Collection end field delimiter
We recommend using curly brackets, parentheses or angled brackets as delimiters. See section “Example layouts” for more information.
Please note that data in a collection field can with great benefit be used for segmentation but is not suited to be presented with placeholders in an email since you have several values.
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>bruce@example.com
002 <tab>lars <tab>ladygaga@example.com
003 <tab>vegar <tab>paul.simon@example.com
004 <tab>tobbe <tab>etta_j@example.com
The example below is a layout using Collection fields with tab as field delimiter and curly brackets as collection delimiter.
Id name categories email
123 pm {clothing}{kitchen} bruce@example.com
345 lh {games}{music}{home} ladygaga@example.com
678 vl {health}{music}{movies} paul.simon@example.com
910 th {games}{clothing}{kids} etta_j@example.com
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.
File upload
Use the supplied login credentials to connect to the server and upload the file to the suitable subfolder of your home folder. If there is a risk that a file is uploaded at the same time as the send campaign / Batchtrigger run we recommend that you use a temporary filename or a separat upload folder to avoid that the job start before the file is completely uploaded. As soon as the file is completely uploaded to the FTP you then change the name or folder to ensure that the job will read the file.
Allowed characters for file names:
A–Z 0–9 – _
Naming convention: senddelivery_<deliveryid>_<ListID>_<Sendtime>.txt
DeliveryID = The ID that identifies as the specific mail that will be sent.
ListID = The ID that identifies the list the recipients will be imported to
Sendtime = the time set will schedule the sending (yyyyMMddhhmmss).
Example:
senddelivery_12345_2345_20130601143000.txt
(Delivery ID 12345 will be sent 2013-06-01 14:30.00 and the recipients in the file will be imported to list 2345.)
PLEASE NOTE! You can’t upload a file where date/time has passed, the campaign will not be sent then.
As soon as a Schedule job is started it will rename the file to filename.archive.timestamp (timestamp is when the import started), example senddelivery_12345_2345_20130601143000.txt.archive.[timestamp].
Send Campaign job setup in Carma
To get the job running you need to, in Carma, enter information about the job, when the import should run and where Carma will find the file. This setting is called Scheduled job and is to be found in Carma: Account settings > Scheduled jobs (> create new send job).
Since a campaign job isn’t connected to a specific file, but sends a campaign based on the information in the file name, you can manage all your Send Campaigns in the same job.
Creating Schedule jobs
The Send Campaign jobs are found in Carma: Account settings > Scheduled jobs (> Create new send job).
You will then get an overview of all your current Schedule jobs. To create a new job click on the button “Create new schedule job” in the right upper corner.
Enter the name you wish to give the specific job.
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 specific time (e.g. 03.30 every night) or an interval (e.g. every 15 minutes):
For example, if you want your Schedule job to run every day at 14:05:
If you want Carma to search for a file on specific days you select the days you wish the Schedule job to run*. Clicking the arrow by next runs you will see the next five events.
* If no days are selected the schedule job will run every day.
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.
Carma will connect to the FTP and at every scheduling search for a file starting with senddelivery (complete file name: senddelivery_<deliveryid>_<ListID>_<Sendtime>.txt as mentioned on File upload).
To speed up the import process it is possible to compress the import files with ZIP.
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.
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.