4. JOBS

The functions below describe the management of jobs (transactional messages, newsletters, ...).

POST api/jobs

Create a new job and start sending

PUT api/jobs/<rfmailno>

GET api/jobs

Modifies the properties of the job <rfmailno> (start/end date, number of retries…)

Lists all user account jobs and their main status indicators and statistics

GET api/jobs/<rfmailno>/stats

GET api/jobs/<rfmailno>/report

Returns detailed sending and tracking statistics for the <rfmailno> job, broken down by [IP,sd,dm,mx]

Returns the sending report of the job <rfmailno>

GET api/jobs/<rfmailno>/clicks

GET api/jobs/<rfmailno>/<data>

Returns the broken down click statistics for the job <rfmailno>

Returns the content of the job'snative elements (txtbody/htmbody/ampbody/list)

Method

Description

4.1. Launch a job

This method creates a new job, launches the sendings, and returns the result of the operation in the "stamp" section of the response. The detailed description of JSON objects is provided in section 6 ("Objects").

POST api/jobs HTTP/1.1
Authorization: <apikey>
Content-Type: application/json
Content-Lenght: <JSON data size below>

{
"job" : {
"ref" : <job's reference (3-30 chars ‘a’-‘z’ ‘0’-‘9’ ‘-‘>,
"title" : <job description>,
"tags" : [<search keyword list>,… ],
"datestart" : <job start date (YYMMDDhhmmss)>,
"datestop" : <job stop date (YYMMDDhhmmss)>,
"retrynb" : <number of retries>,
"retrydelay" : <delay between retries (s)>
},

"header" : {
"subject" : <email subject>,
"from" : { "addr": <from email address> , "name": <from name> },
"sender" : { "addr": <sender email address> , "name": <sender name> },
"reply-to" : { "addr": <reply email address> , "name": <reply name> },
"to" : [ { "addr" : <recipient email address>, "name" : <recipient name> },… ],
"cc" : [ { "addr" : <recipient email address>, "name" : <recipient name> },… ],
"feedback-id" : <feedback-id field (Google) format_a:b:c:d>,
"precedence" : <precedence field (Google) true/false>,
"unlst" : <List-Unsubscribe field: liens http/smtp/both>,
"charset" : <email header encoding charset, def utf-8>
},

"recipients" : {
"path" : <@path of the uploaded csv list of recipients OR name of the section that contains the record data of the recpicient, for ex "rec" - see below>,
"charset" : <list's native charset>,

"testaddr" : [<test email address list>,… ],
"checkaddr" : [<check email address list>,… ],
"filter" : [<list of blacklists used for address filtering>,… ],

"optout" : <blacklist in which to record unsubscriptions>

"rec" : {

"email" : <recipient email address - mandatory>,

"custom1" : <first custom field, for ex "name" : "xxx">,

"custom2" : <second custom field>,

...

"custom(n)" : <last custom field>

"txtbody" : {
"path" : <@path of the txt body file>,
"encoding" : <body encoding format, def Quote-Printable>,
"charset" : <charset of the txt body>

"htmbody" : {
"path" : <@path of the htm body file>,
"encoding" : <body encoding format, def Quote-Printable>,
"charset" : <charset of the htm body>

"attachments" : [ {
"path" : <attachment file @path>,
"encoding" : <attachment encoding format, def Base64>,
},… ],

"images" : [ {
"path" : <image file @path>,
"encoding" : <image encoding format, def Base64>,

},… ],

"tracking" : {
"host" : <domain name used for tracked URLs>,
"open" : <opening tracking option: disable/image/pixel>,
"click" : <click tracking option: disable/embedded>,
"image" : <image tracking option: disable/embedded>,
"bot" : <hidden link insertion option: enable/disable>,
"unsub" : <link to unsubscribe page>,
"uncfm" : <link to unsubscribe confirmation page>,
"mirror" : <link to mirror page>,

"https" : <use https links for tracking option: true/false>,
},

"routing" : {

"ehlo" : <domain name used in the EHLO (@rdns)>,

"envelopefrom": <address used in the MAIL FROM: @mailfrom/@verp/@from>,

"sign" : <DKIM signing flag: from/envelope/both>,

"starttls" : <STARTTLS usage flag: true/false>,

"ip" : <list of IPs and/or transmission resources>

}
}

-----------------------------------------------------------------------------------------------HTTP/1.1 200 OK
Content-Type: application/json
Content-Lenght: <JSON data size below>

{
"stamp" : {
"date" : <processing date YYMMDDhhmmss>,
"mailno" : <system job reference >,
"err" : <error code, 0=OK>,
"msg" : <error description>
}
}

4.2. Modify a job

This method allows you to modify the parameters of a running job.

PUT api/jobs/<rfmailno> HTTP/1.1
Authorization: <apikey>
Content-Type: application/json
Content-Lenght: <JSON data size below>

{
"status" : {
"hold" : <true/false>,
},

"job" : {
"datestart" : <job start date (YYMMDDhhmmss)>,
"datestop" : <job stop date (YYMMDDhhmmss)>
"retrynb" : <number of retries>
},

"header" : {
"subject" : <email subject>,
}
}

-----------------------------------------------------------------------------------------------HTTP/1.1 200 OK
Content-Type: application/json
Content-Lenght: <JSON data size below>

{
"stamp" : {
"date" : <processing date YYMMDDhhmmss>,
"err" : <error code, 0=OK>,
"msg" : <error description>
}
}

The "status" key is used to suspend the distribution of the job with immediate effect. The job remains in a suspended state until it is relaunched via a request that sets the value of "hold" to false.

The "job" section allows you to reschedule the start and end dates of the job sends, as well as the number of send attempts.

Finally "header" allows the modification of the subject of the emails being broadcast.

4.3. Jobs list

This method lists the jobs injected into the system.

GET api/jobs/<rfmailno>?from=<index_from>&to=<index_to>
&fmt=<csv/htm/xml/json_output_file_format> HTTP/1.1
Authorization: <apikey>

-----------------------------------------------------------------------------------------------HTTP/1.1 200 OK
Content-Type: application/json
Content-Lenght: <JSON data size below>

{
"jobs" : [ {
"ref" : <job reference>,
"type" : <‘S’ = campaign, ‘T’ = test, 'M' = message>,
"rfmailno" : <system job reference>,
"rfstart" : <job start date (YYMMDDHHMMSS)>,
"rfstop" : <job stop date (YYMMDDHHMMSS)>,
"rfsts" : <job status (see below)>,
"rfstr" : <status name>,
"rfrsn" : <status reason>,
"rfrecfirst" : <internal counter>,
"rfrecidx" : <internal counter>,
"rfrecbusy" : <number of messages in queue>,
"rfrecfeed" : <last number of messages injected in the queue>,
"rflistsize" : <total number of recipient in email address list>,
"rffiltered" : <number of recipients filtered when submited>,
"rfdiscarded" : <number of recipients filtered during sending>,
"rfsyserr" : <number of recipients in system error>,
"rfdelivered" : <number of delivered emails>,
"rfsoft" : <number of soft bounces>,
"rfhard" : <number of hard bounces>,
"rfflow" : <total number of flow change during sending>,
"rfptrn" : <total number of unknown SMTP pattern>,
"rfopen" : <total number of openings>,
"rfopener" : <total number of openers>,
"rfclick" : <total number of clicks>,
"rfclicker" : <total number of clickers>,
"rfmirror" : <total number of recipients who clicked on the mirror page link>,
"rfunsub" : <total number of recipients who clicked on the unsbuscribe link>,
"rfuncfm" : <total number of recipients who clicked on the confirmation unsbuscribe

link>,
"rfunlst" : <total number of unsbuscribe recipients via List-Unsubscribe TAG>,
"rfbot" : <total number of recipients with click on invisible link>,
"rffbl" : <total number of FeedBackLoop messages received>,
"rfreply" : <total number of replies received>,
"datestart" : <scheduled job start date>,
"datestop" : <scheduled job stop date>,
"retrynb" : <number of retries>,
"retrydelay" : <delay between retries>,
"title" : <job title>,
"tags" : <search keyword list>,
"subject" : <email subject>,
"fromaddr" : <from email address>,
"fromname" : <from name>,
"toaddr" : <first recipient email address>,
"toname" : <first recipient name>,
"ccaddr" : <first recipient in CC email address>,
"ccname" : <first recipient in CC name>,
"rftextsz" : <txt body size (bytes)>,
"txtbody" : <link to txt body>,
"rfhtmsz" : <htm body size (bytes)>,
"htmbody" : <link to htm body>,
"list" : <link to original csv recipient list>,

"filter" : <list of blacklists>,

"optout" : <blacklist in which to record unsubscriptions>,
"rfattchsz" : <total size of attachments>,
"rfattchnb" : <number of attachment>,
"rfimagenb" : <total size of embedded images>,
"rfimagesz" : <total size of embedded images>
},… ]
}

Intitulé

rfsts

Description

Job running

Job submitted to the system

Job completed

Job manually suspended

Job in error

Job awaiting datestart

Submitted

Running

Completed

Waiting

Suspended

Error

Query :

The "rfmailno" parameter is optional. If not specified, the system returns by default the last 100 jobs injected into the system by the user. It is possible to modify this scope using the "from" and "to" parameters, with a maximum interval of 1000 results at a time. If the "rfmailno" parameter is specified, the system returns only the table entry corresponding to the job reference and ignores the other query parameters.

4.4. Detailed job statistics

GET api/jobs/<rfmailno>/stats?groupby=<flag de regroupement>
&fmt=<csv/htm/xml/json_output_file_format> HTTP/1.1
Authorization: <apikey>

-----------------------------------------------------------------------------------------------HTTP/1.1 200 OK
Content-Type: application/json
Content-Lenght: <JSON data size below>

{
"stats" : [ {
"rfdate" : <always 0)>,
"rfipno" : <internal number of sending IP>,
"rfipstr" : <sending IP address>,
"rfsdno" : <internal number of sender domain>,
"rfsdstr" : <sender domain name>,
"rfdmno" : <internal number of domain group>,
"rfdmstr" : <domain group name>,
"rfmxno" : <internal number of MX>,
"rfmxstr" : <MX IP address>,
"rfmxdm" : <internal number of domain group linked to MX>,
"rfmxds" : <domain group name linked to MX>,
"rflistsize" : <number of recipient per domain group
(precomputed at job submission, according to known aliases)>,
"rfdelivered" : <number of delivered emails>,
"rfsoft" : <number of soft bounces>,
"rfhard" : <number of hard bounces>,
"rfflow" : <number of flow change during sending>,
"rffallback" : <number of sending on secondary MX>,
"rfopen" : <number of openings>,
"rfopener" : <number of openers>,
"rfclick" : <number of clicks>,
"rfclicker" : <number of clickers>,
"rfmirror" : <total number of clicks on mirror link>,
"rfunsub" : <total number of clicks on unsubscribe link>,
"rfuncfm" : <total number of clicks on confirmation unsubscribe link>,
"rfunlst" : <total number of clicks on List-Unsubscribe (http/smtp)>,
"rfbot" : <total number of clicks on invisible link>,
"rffbl" : <number of FeedBackLoop messages received>,
"rfreply" : <number of incoming email received>
},… ]
}

Query :

This command generates delivery and tracking statistics for the job referenced by the 'mailno' variable, taken from the job log.

The main indicators (emails delivered, hardbounces, openings, clicks, etc.) are broken down by unique quadruplets { ip; nd; dm; mx }, where 'ip' represents the sending IP, 'sd' the sender domain, 'dm' the destination domain group, and 'mx' the remote SMTP server IP.

"listsize" represents the number of recipients per domain group, as precalculated based on known aliases when the job is injected into the system.

The GROUPBY parameter represents the decimal value of the Logical Or (OR) of the following flags:

STAT_FLAG_IP 0x08
STAT_FLAG_SD 0x04
STAT_FLAG_DM 0x02
STAT_FLAG_MX 0x01

4.5. Job sending reports

GET api/jobs/<rfmailno>/report?&fmt=<csv/htm/xml/json_output_file_format> HTTP/1.1
Authorization: <apikey>

-----------------------------------------------------------------------------------------------HTTP/1.1 200 OK
Content-Type: application/json
Content-Lenght: <JSON data size below>

{
"report" : [ {
"rfsts" : <status code (see below)>,

"rfevt" : <even code>,
"rfstr" : <status name>,
"rfpatten" : <detected pattern name>,
"rfpoolno" : <specific outbound address pool>,
"rfcrc" : <internal hash>,

"rftryno" : <number of sending attempt>,

"rfcancelnb" : <number of expired jobs in message queue>,
"rfsubmitdate" : <submit date (YYMMDDHHMMSS)>,

"rfsenddate" : <sending date (YYMMDDHHMMSS)>,
"rfduration" : <total processing duration (ms)>,
"rfipno" : <internal number of sending IP>,
"rfipstr" : <sending IP address>,
"rfsdno" : <internal number of sender domain>,
"rfsdstr" : <sender domain name>,
"rfdmno" : <internal number of domain group>,
"rfdmstr" : <domain group name>,
"rfmxno" : <internal number of MX>,
"rfmxstr" : <MX IP address>,
"rfmxname" : <MX host name>,
"rfmxdx" : <number of MX in MX list>,

"rfmxnb" : <total number of MX in MX list>,

"rfmxdm" : <internal number of domain group linked to MX>,
"rfmxds" : <domain group name linked to MX>,
"rfipflowno" : <number of IP flow profile used while sending>,
"rfipflowstr" : <name of IP flow profile used while sending>,

"rfsdflowno" : <number of SENDER flow profile used while sending>,
"rfsdflowstr" : <name of SENDER flow profile used while sending>,

"rfssno" : <number of the message in the same session SMTP>,
"rfdforge" : <merging duration (ms)>,
"rfdsign" : <DKIM signing duration (ms)>,
"rfsize" : <message size (bytes)>,
"rfssl" : <negociated SSL/TLS version>,
"rferr" : <last error code>,
"rfapp" : <last application error code>,
"rfdwe" : <last system error code>,
"rfval" : <last XXX received>,
"rfstp" : <last protocol step>,
"rfclientip" : <client IP address (web)>,
"rflasthit" : <last tracking event>,
"rflastclick" : <last click>,
"rfopennb" : <total number of openings>,
"rfopen" : <date of last open>,
"rfclicknb" : <total number of clicks>,
"rfclick" : <date of last click>,
"rfmirror" : <date of first click on mirror page link>,
"rfunsub" : <date of first click on unsubscribe link>,
"rfuncfm" : <date of first click on confirmation unsubscribe link>,
"rfunlst" : <date of first List-Unsubscribe>,
"rfbot" : <date of first click on invisible link>,
"rffbl" : <FeedBackLoop reception date>,
"rfreply" : <reply reception date>,
"rfreplytype" : <reply type (sse ch. 8)>,
"rfdevice" : <recipient's OS>,
"rfbrowser" : <recipient's web browser>,
"email" : <recipient's email address>,
<custom field> : <value>,
<custom field> : <value>,
<custom field> : <value>,
…
<custom field> : <value>
},… ]
}

rfsts

Intitulé

Description

Invalid email address format

Empty email address

Duplicate email address in the list

Email delivered successfully

Address present in the blacklist xxx

Empty

Invalid

Duplicate

BL xxx

Delivered

Soft

Soft Bounce – see rfstr

Hard

Hard Bounce – see rfstr

Flow

Change of parameter sets following SMTP match pattern

Discarded

IP/MX/banner filtered

System

System error

4.6. Detail of job clicks

GET api/jobs/<rfmailno>/clicks?fmt=<csv/htm/xml/json_output_file_format> HTTP/1.1
Authorization: <apikey>

-----------------------------------------------------------------------------------------------HTTP/1.1 200 OK
Content-Type: application/json
Content-Lenght: <JSON data size below>

{
"clicks" : [ {
"no" : <number of the link in the body>,
"nb" : <total number of clicks on the link>,
"url" : <redirection url>
},… ]
}

4.7. Downloading job elements

GET api/jobs/<rfmailno>/<txtbody/htmbody/ampbody/list> HTTP/1.1
Authorization: <apikey>

-----------------------------------------------------------------------------------------------HTTP/1.1 200 OK
Content-Type: application/<content type>
Content-Lenght: <data size below>

API based

SYNCHRONOUS

SMTP RELAY

4. JOBS

4.1. Launch a job

4.2. Modify a job

4.3. Jobs list

4.4. Detailed job statistics

4.5. Job sending reports

4.6. Detail of job clicks

4.7. Downloading job elements