ReplixFax Mail Merge Reference

1. Overview
2. Create Job
3. Job Status
4. Job Faxes
5. Jobs

1. Developer Home
2. Mail Merge

Mail Merge REST Overview

The Softlinx Cloud Mail Merge REST API provides a simplified API for creating mail merge jobs and retrieving the status of the job and resulting faxes. Requests are made over a secured HTTPS connection.

A mail merge job requires two files, a fax metadata file that contains data to be substituted in a PDF form and the PDF form itself. The fax metadata file must be a CSV file where the first line contains the column headings. One of the columns must contain the destination fax numbers. During the processing of the mail merge job, each line in the metadata file is read and the values in each column are substituted into corresponding named fields in the PDF form. The resulting PDF file is sent as a fax.

The mail merge API allows for the creation of a mail merge job and the ability to check its status. Additionally, with the API, you can get a list of all the faxes resulting from the mail merge job. Each fax has a status that will indicate whether the fax has been successfully sent or had an error.

Getting Started

A quick way to get started with the mail merge API is to download the sample CSV file and PDF template. Open the readme file and change the credentials. You will need curl.exe to execute the sample API call.

Mail Merge REST API Resources

Base URL

The base URL is "https://api-mm.rpxtest.com/softlinx/mailmerge/v1". The "v1" denotes version 1 of the APIs. The APIs are documented relative to the base URL, e.g., for creating a mail merge job the documented URL is /Job so the real URL is https://api-mm.rpxtest.com/softlinx/mailmerge/v1/Job.

The URL above is for the Softlinx Cloud Fax test environment. A production URL is provided as part of the customer onboarding process.

HTTP submission method

The HTTP method is denoted with GET, POST, PUT, or DELETE keywords.

API arguments

The API parameters can be passed in QUERY_STRING or in the body of the request using "www-form-urlencoded" or "form-data" formats. Both formats are standard form/url submission formats used by browsers. The "application/www-form-urlencoded" body contains multiple parameters "key=value&key=value..." whereas "form-data" is multipart/form-data contains one parameter per MIME part and is usually used to send attachments.

Arguments are case sensitive and unrecognized arguments are ignored.

Client credentials

The client user ID and password is passed to the API using the Basic Authentication header.

REST API responses

Response HTTP code:

• 200 OK for success. Most responses should return 200.
• 401 Authentication failure Unauthorized - bad username or password
• 403 Forbidden access denied to a resource
• 400 Bad Request - Client errors in parameters/URLs
• 404 Not Found missing resource
• 500 Server Error - Server processing errors

Response body

All responses return JSON data (application/json). ALL JSON responses contain "RequestStatus" object with StatusCode (0 for success), StatusText members. e.g.,

...
"RequestStatus" : {
   "StatusCode" : 0,
   "StatusText" : ""
 }

1. Developer Home
2. Mail Merge
3. Create a Job

Create a Mail Merge Job

A mail merge job requires a CSV file containing fax metadata and a PDF form. The first line on the CSV file must contain the column headings. When a column name matches a name of a PDF field, the value in that column will be put into the form field when the fax image is created.

The CSV, Template, and FaxNumerColumnName arguments are required.

If the barcode column name is specified, then there needs to be a corresponding image field in the PDF with the same name. A PDF417 barcode will be placed at the location of the image field. The field's attribute should be set to hidden. The size of the barcode is fixed and will not change based on the image field size.

POST /softlinx/mailmerge/v1/Job HTTP/1.1
Host: api-mm.rpxtest.com
Authorization: Basic XXX
Cache-Control: no-cache
Postman-Token: e8b3e52c-8b3e-6f24-bacc-984fce9f43f6
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="ExpectedFaxes"

10

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="CSV"; filename="meta_10.csv"
Content-Type: application/vnd.ms-excel


------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="Template"; filename="mm1f.pdf"
Content-Type: application/pdf


------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="FaxNumerColumnName"

faxnum
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="KeywordColumnName"

internal_id
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="BarcodeColumnName"

barcode
------WebKitFormBoundary7MA4YWxkTrZu0gW--

curl https://api-mm.rpxtest.com/softlinx/mailmerge/v1/Job -F FaxNumerColumnName=faxnum -F CSV=@<
filename
> -F Template=@<
filename
> -u <
username@organization
>:<
password
>

HTTP/1.1 201
Content-Length: 
length
Content-Type: application/json; charset=utf-8
{
"JobID":63,
"RequestStatus":
{
"StatusCode":0,
"StatusText":""
}
}

POST /Job

Arguments

Response

Potential Errors

1. Developer Home
2. Mail Merge
3. Job Status

Mail Merge Job Status

All mail merge jobs go through a process where each line in the CSV is read and a corresponding outbound fax is created with a merged PDF file. The fields in the PDF will contain the corresponding values in the row of the CSV file.

As each line in the CSV file is processed, the current line number for the mail merge job is updated. While the CSV file is being processed, the job status will be "INPROCESS".

When all lines of the CSV file are processed, the status will be "COMPLETE". This does not mean that all faxes have been sent. It means that all fax requests have been created. Each fax request goes through an independent process of sending.

A mail merge job can be cancelled prior to all of its lines being processed and a corresponding fax is generated. If a job is cancelled, its status will be "CANCELLED".

GET /softlinx/mailmerge/v1/Job/23 HTTP/1.1
Host: api-mm.rpxtest.com
Authorization: Basic XXX
Cache-Control: no-cache
Postman-Token: ba0fed50-c129-21f3-31e3-bdfef97dd4fc

curl https://api-mm.rpxtest.com/softlinx/mailmerge/v1/Job/23   -u <
username@organization
>:<
password
>

"Job":
{
"ID":23,
"CreatedOn":"2018-10-18T19:47:42",
"LastCompletedLine":10000,
"Status":"COMPLETE",
"CancelledOn":null,
"ExpectedFaxCount":0
},
"RequestStatus":
{
"StatusCode":0,"StatusText":""
}
}

GET/Job/{Job ID}

Response

Potential Errors

1. Developer Home
2. Mail Merge
3. Faxes from Job

Faxes from Mail Merge Job

List all Mail Merge Jobs

GET /softlinx/mailmerge/v1/Job/23 HTTP/1.1
Host: api-mm.rpxtest.com
Authorization: Basic XXX
Cache-Control: no-cache
Postman-Token: ba0fed50-c129-21f3-31e3-bdfef97dd4fc

curl https://api-mm.rpxtest.com/softlinx/mailmerge/v1/Job/23/Faxes   -u <
username@organization
>:<
password
>

{
"Faxes":
[
{
"ID":41253,
"CreatedOn":"2018-02-15T16:30:28",
"Status":"Submitted",
"ErrorCode":"0",
"ErrorText":"",
"Keyword":"",
"FaxNumber":"1",
"ModifiedOn":"2018-02-15T16:30:28",
"Owner":"seth"
}
,
{
"ID":41254,
"CreatedOn":"2018-02-15T16:30:29",
"Status":"Submitted",
"ErrorCode":"0",
"ErrorText":"",
"Keyword":"",
"FaxNumber":"2",
"ModifiedOn":"2018-02-15T16:30:29",
"Owner":"seth"
}
],
"RequestStatus":
{
"StatusCode":0,"StatusText":""
}
}

GET/Job/{Job ID}/Faxes

Response

Potential Errors

1. Developer Home
2. Mail Merge
3. Jobs

Mail Merge Jobs

List all Mail Merge Jobs

GET /softlinx/mailmerge/v1/Job/23 HTTP/1.1
Host: api-mm.rpxtest.com
Authorization: Basic XXX
Cache-Control: no-cache
Postman-Token: ba0fed50-c129-21f3-31e3-bdfef97dd4fc

curl https://api-mm.rpxtest.com/softlinx/mailmerge/v1/Job -G  -u <
username@organization
>:<
password
>

{
"Jobs":
[
{
"ID":22,
"CreatedOn":"2018-10-18T16:49:59",
"LastCompletedLine":0,
"Status":"CANCELLED",
"CancelledOn":null,
"ExpectedFaxCount":0
},
{
"ID":23,
"CreatedOn":"2018-10-18T19:47:42",
"LastCompletedLine":10000,
"Status":"COMPLETE",
"CancelledOn":null,
"ExpectedFaxCount":0
}
],
"RequestStatus":
{
"StatusCode":0,
"StatusText":""
}
}

GET/Job

Response

Potential Errors