Symplify Send Campaign enables organizations to automatically send a specific delivery based on the recipients transferred in a file to Symplify.
Send campaign can both be used by FTP file transfer (up next) and web service (rest API).
Example flow:
A Symplify user creates a campaign draft in Symplify. A selection in your CRM system is made on recipients who should receive the specific campaign from Symplify. The file with the recipients is then transferred from the CRM system to Symplify. Based on the filename Symplify will send the campaign to the recipients in the file. The filename should contain three parameters (deliveryID; ListID; Sendtime) for Symplify to be able to understand what to do with the file.
Setup overview for FTP file transfer
The setup of a Send Campaign consists of four parts.
- Symplify supplies this document and FTP or sFTP1 login information.
- Symplify Send Campaign is setup on the account to monitor the FTP or sFTP for Send Campaign files.
- A campaign draft is created in Symplify.
- You create a file according to the file format specifications described in this document and also follow the specific filename pattern.
* Symplify also support Secure Copy over SSH. This file transfer method provides greater security.
PLEASE NOTE! We recommend that you use Symplify REST API to get the correct delivery and ListID into the file name.
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 > 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.
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
2018-04-05 13:37
2019-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.
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 job runs 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
Your uploaded file must always follow the naming convention in order to work:
senddelivery_<deliveryid>_<ListID>_<Sendtime>.txt
where
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! If you upload a file where the scheduled time has passed, the campaign will be sent as soon as possible.
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 Symplify
To get the job running you need to, in Symplify, enter information about the job, when the import should run and where Symplify will find the file. This setting is called Scheduled job and is to be found on Account settings > (Integration) Scheduled jobs.
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 Symplify: Account settings > (Integration) 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 schedule job in the right upper corner and select Send delivery.
Enter the name you wish to give the specific job.
Select whether you want the import to replace the database or just add (add is recommended).
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*. 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.
Symplify 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.
Now you can check the progress of your job.
Setup overview for API file transfer
This is a compliment to the Symplify Rest API document that describes the Jobs resource in more detail. 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 campaign 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 be created.
You must also prepare your 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": "CAMPAIGN",
"id": 336858,
"listId": 22265
}
Valid type values are:
-
CAMPAIGN
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,
"listId":22265,
"contentUploaded”:false,
"feedback2:[
{
"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://test.carmamail.com/rest/487/jobs/generation/fixed HTTP/1.1
Host: test.carmamail.com
Authorization: Basic XXXX
Accept: application/json
{
"type": "CAMPAIGN",
"id": 336858,
"listId": 22265
}
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}]}
Request 2
POST http://test.carmamail.com/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
Response 2
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}]}
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 Symplify. This can easily be done by exporting all property values from the list in Symplify and analyse it.