Sending Faxes using XML Control Files

Administrator -

XMediusFAX Cloud exposes a web application to which applications can send fax control files over HTTPs to your Fax Service.

Generating an XML Control File

The XML control file will include all the necessary information to send a fax (with possible attachments). Your application must be able to generate this XML file for each fax and it must follow a specific syntax. You can use the following link to download a sample XML file and the DTD file (document type definition) to help you build the XML control file (XML Example and DTD file download).

For a description of the XML tags, refer to the Faxing with XML chapter in the online Administration Guide (Help > Fax Administration Help).

Creating an Authorization Token

To submit the fax, an authorization token is required, which will be passed in an HTTP header called XM-Token-Authorization. This token must be created through your Fax Service administration interface.

For example:
XM-Token-Authorization: 7d887f894a0597f79a36de461abda2d1
where 7d887f894a0597f79a36de461abda2d1 is the token.

To create the token:

  1. Select Access Tokens from your administration interface navigation bar.
  2. Click Add New Access Token.
  3. Add a display name and select the Send and manage faxes permission type.
  4. Click Add. The system will generate an authorization token.

POSTing a fax

There are two steps your application must make to send a fax:

  1. The application must first determine where to POST the data. To do so:
    1. Submit an HTTPs GET to:
      https://portal.<domain>/services/<account_name>/fax/restservice/url
      where:
      • <domain> is the domain corresponding to the region of your enterprise account (i.e. xmedius.com for North America or xmedius.eu for Europe).
      • <account_name> is the login name of your Fax Service account. The response to this request will be a 200 OK with a body that contains only the URL to the restservice API of your associated fax server.
    2. Take this new URL and append sendfax to it. This is where you will need to POST your document.
  2. The application must then submit an HTTPs POST to the new URL obtained above. This POST:
    • Must include an XM-Token-Authorization header (see Creating an Authorization Token).
    • Must have a multipart/form-data Content-Type.
    • Must have a first part with a header: name="metadata". The body within this part will be the XML metadata.
    • Must have an additional part for each attachment specified in the XML metadata
      • Each of these parts must have a header: name="attachments".
      • Each part must also have a filename attribute that contains the name and file extension of the attachment file (e.g. filename="sample.txt").
    Note: The application can request the body of the response to be in JSON or in XML format by using the accept header:
    • accept: application/json, or
    • accept: application/xml
    If not specified, the result will be in JSON format.
    After the POST is made, you will receive a reply from XMediusFAX Cloud describing the status of your request.

POST reply

Upon successful enqueuing of the fax for delivery, the response to the POST will be 200 OK, with a body detailing the broadcast ID (one per submission) and the transaction IDs (one per recipient) of the fax transaction.

In JSON, the body of the response will look like this:
{"success":"true","successInfo":{"broadcastId":"[Fax broadcast ID]","transactionIds":{"transactionId":["[Fax transaction ID for first recipient]","[Fax transaction ID for second recipient]","..."]}}}
In XML, the body of the response will look like this:
<response>
   <success>true</success>
   <successInfo>
      <broadcastId>[Fax broadcast ID]</broadcastId>
      <transactionIds>
         <transactionId>[Fax transaction ID for first recipient]</transactionId>
         <transactionId>[Fax transaction ID for second recipient]</transactionId>
         <transactionId>[...]</transactionId>
      </transactionIds>
   </successInfo>
</response>

Upon failure, the application will receive a 4XX/5XX error. For errors that are related to authentication and processing of the XML metadata, the body of the response will include an error message with more details about what went wrong.

In JSON, the body of the response will look like this:
{"success":"false","errorInfo":{"errorMsg":"[Description of error]","errorCode":"[Label of error]"}}
In XML, the body of the response will look like this:
<response>
   <success>false</success>
   <errorInfo>
      <errorMsg>[Description of error]</errorMsg>
      <errorCode>[Label of error]</errorCode>
   </errorInfo>
</response>

Using cURL as a tool to construct and POST the HTTP request

If you don't want to develop the portion of the application that would construct the HTTP message and submit the request, there exists some tools that could be launched from the command line to perform these tasks.

One of these handy tools is called cURL. cURL is a command line tool for transferring data using various protocols. It is freely available on the internet (see http://curl.haxx.se/download.html).

Command Line

You can use the following command line in the folder where cURL resides to build a multipart/form-data body in the format described in the previous section.
curl -k -F metadata=@<xml_file> -F attachments=@<attachment> -H "XM-Token-Authorization: <authorization_token>" <POST_URL>
Note: You can repeat -F attachments=@<attachment2> to include all referenced files.
For example, if:
  • <xml_file> is: MyFaxFile.xml
  • <attachment> is: MyAttachment.docx
  • <authorization_token> is: 7d887f894a0597f79a36de461abda2d1
  • <POST_URL> is: https://faxus1.xmedius.com/restservice/sendfax
The command line would look like this:
curl -k -F metadata=@MyFaxFile.xml -F attachments=@MyAttachment.docx -H "XM-Token-Authorization: 7d887f894a0597f79a36de461abda2d1" https://faxus1.xmedius.com/restservice/sendfax
Note: This URL is an example. You must use the URL returned by the GET request to make your POST.

Batch File

The following batch file provides an example of how cURL could be used:
  1. to obtain the URL where the XML metadata will be sent;
  2. to submit the fax.
set DOMAIN=<your fax service regional domain>
set ACCOUNT=<your fax service account login name>
set TOKEN=<access token>
set XML_FILE=<path to xml file>
set ATTACHMENT_FILE=<path to attachment file>
set SERVICE_URL=https://portal.%DOMAIN%/services/%ACCOUNT%/fax/restservice/url
for /F %%x in ('curl -s -k %SERVICE_URL%') do set POST_URL=%%x/sendfax
curl -v -k -F metadata=@%XML_FILE% -F attachments=@%ATTACHMENT_FILE% -H "XM-Token-Authorization: %TOKEN%" %POST_URL%
Have more questions? Submit a request

Comments

  • Avatar
    giovanni venegas

    We are trying to send fax using XML control file but receiving error "User not found". can you please help

    POST URL response
    {
    "success": "false",
    "errorInfo": {
    "errorMsg": "User not found",
    "errorCode": "AUTHORIZATION"
    }
    }

Powered by Zendesk