Programmable Fax Migration Guide for Documo mFax

On December 17, 2021, Twilio will be sunsetting support for the Twilio Programmable Fax offering. For users with continuing fax needs, we have partnered with Documo to help ease the burden of transitioning your workflows. This guide contains details on how to migrate your workflows, and covers the following topics:

Notice: For Japanese customers, we have identified InterFax as an alternative partner solution. For full details, see Programmable Fax Migration Guide for Upland InterFAX.

Prerequisite: Signup for Documo

Before sending and receiving faxes via Documo mFax, users will need to create a Documo account here: https://app.documo.com/signup 

Notice: Documo gives Console and Email fax access by default. Users who wish to send faxes via API will first need to enable the API and retrieve an API key.

Send a fax via the mFax console UI

Login to your Documo account, and enter the Fax number (destination) and attachment you wish to send. Full instructions can be found under the "How to Send a Fax" topic in the mFax Simple User Guide.

Send a fax via email

Send a message from the email address associated with your Documo account to the full phone number (including the International Country Calling code) at the domain send.mfax.io. For example, an emailed fax to the USA number (310) 555 - 1234 would go to 13105551234@send.mfax.io. For full details, see Documo's guide How to Send a Fax from Email.

Send a fax via the mFax REST API

Notice: Unlike Twilio, Documo does not offer helper libraries. When building your mFax app, your API requests will need to be constructed using your favorite language’s HTTP library. For example, with Python, you can use Requests.

The Documo REST API is similar to Twilio’s, but uses slightly different nomenclature.
An HTTP POST request to the /faxes endpoint is the foundation for sending a transmission. Like Twilio, a few parameters are required:

Twilio parameter Documo mFax equivalent Notes
To faxNumber The recipient or destination Fax number.
mediaURL attachments Instead of a URL, Documo uses the directory path of the document on the sending server.
From callerId Not required, will default to user setting if not included.
Auth Token Authorization Your API key is sent as a request header. It must be requested before API requests can be sent.

Here’s an example cURL script:

curl -X POST 'https://api.documo.com/v1/faxes' \
    -H 'Authorization: Basic API_KEY' \
    -H 'content-type: multipart/form-data' \
    -F 'faxNumber=18885551234' \
    -F 'coverPage=true' \
    -F 'recipientName=John' \
    -F 'subject=test' \
    -F 'notes=test' \
    -F 'tags=4c225812-81f1-4827-8194-b0e9475c54e6' \
    -F 'attachments=@/home/user/Documents/Sample.pdf'
    -F 'cf={"patientId":"1234"}'

Documo also offers some unique optional API parameters that could help level up your Fax app:

  • The coverPage parameter allows you to include a cover page you have created on your account, or a specific coverPageId. For more information, see Documo's guide on Creating a custom cover page.
  • The cf parameter allows you to associate an object with custom fields to each fax transmission - "patientId: 1234" in the above example.

For full details, see Documo's API documentation topic Send a fax.

Send multiple identical faxes

mFax allows you to send multiple faxes with one API call, by sending an HTTP POST to the /faxes/multiple endpoint. The only parameter change required is to replace faxNumber with recipientFax, and include a comma separated list of recipient numbers. When you submit the POST request, Documo will send an identical transmission to each destination in the recipientFax list.

For more information see Documo's API documentation topic Send multiple faxes.

Documo’s response

When a POST is sent to create a fax, Documo will respond with JSON like this:

{
    "accountId":"6c838c7c-cb48-4763-84d6-233b5f8cf782",
"channelType":"web",
"direction":"outbound",
"createdAt":"2018-01-01T12:00:00.000Z",
"deletedAt":null,
"deliveryId":"2180614133420933276",
"duration":86318,
"faxAttempt":1,
"faxbridge":null,
"faxbridgeId":null,
"faxCallerId":"18885551234",
"faxCsid":"mFax",
"faxDetected":true,
"faxECM":256,
"faxNumber":"+18885550000",
"faxProtocol":34,
"faxSpeed":33600,
"isArchived":false,
"isFilePurged":false,
"messageId":"027012f1-80c9-4be5-b093-1f54783dfa3b",
"messageNumber":"8900000",
"pagesComplete":3,
"pagesCount":3,
"status":"success",
"resolvedDate":"2018-01-01T12:00:00.000Z",
"resultCode": "0",
"resultInfo": "OK",
"contacts":[],
"tagId": "4c225812-81f1-4827-8194-b0e9475c54e6",
"tags":[
{
"uuid": "4c225812-81f1-4827-8194-b0e9475c54e6",
"createdBy": "7b667809-c88f-4a27-b1fe-2cc932401e15",
"name": "Healthcare",
"color": "1E88E5",
"isPublic": 1
}
],
"users":[],
"cf": {
"customField": "value"
}
}

If you iterate over Twilio’s JSON response today, you will likely need to change your code to accommodate Documo's response. A lot of similar data is included in Documo’s response, along with some new parameters that relate to Documo specific features. Please review the JSON response carefully to make sure your application can handle the payload.

Check out the rest of Documo's API docs for more examples of how to fetch faxes, cover sheets, and perform deletions.

Receive a fax via mFax

Documo allows users to receive faxes via a number of methods, including FTP/SFTP servers, email, and a phone number & webhook. For full details, see Documo's guide Receiving inbound faxes.

Inbound fax webhook

Like Twilio, Documo can receive faxes with inbound phone numbers, and ping your user-defined webhook URL when a fax is received. The payload will look a bit different, though, so you may need to update the code of your fax application to accommodate mFax's requests.

Here's an example of what an inbound request looks like from mFax:

{
    "method": "POST",
    "path": "/",
    "query": {},
    "headers": {
        "x-forwarded-for": "35.225.187.84",
        "x-forwarded-proto": "https",
        "x-forwarded-port": "443",
        "host": "74a927fe9f2def8b6d9f7f7b2045186e.m.pipedream.net",
        "x-amzn-trace-id": "Root=1-5fd7985e-333ea79452b049725033a8bd",
        "content-length": "1231",
        "user-agent": "got (https://github.com/sindresorhus/got)",
        "x-environment": "production",
        "content-type": "multipart/form-data; boundary=--------------------------468510834120531538279001",
        "accept-encoding": "gzip, deflate, br"
    },
    "bodyRaw": "{\"name\":\"fax.inbound\",\"data\":\"{\\\"resultInfo\\\":\\\"OK\\\",\\\"messageId\\\":\\\"0eb6aec6-5648-4f14-88d5-58c0448d0b8c\\\",\\\"channelType\\\":\\\"web\\\",\\\"isArchived\\\":false,\\\"isFilePurged\\\":false,\\\"deliveryId\\\":\\\"2201214165226330782\\\",\\\"watermark\\\":\\\"2201214165241960798\\\",\\\"messageNumber\\\":\\\"127477054\\\",\\\"status\\\":\\\"success\\\",\\\"pagesCount\\\":1,\\\"pagesComplete\\\":1,\\\"duration\\\":194000,\\\"faxNumber\\\":\\\"+18778360721\\\",\\\"faxCsid\\\":\\\"12028837801\\\",\\\"faxCallerId\\\":\\\"2028837801\\\",\\\"faxECM\\\":256,\\\"faxSpeed\\\":14400,\\\"faxDetected\\\":true,\\\"faxProtocol\\\":17,\\\"faxAttempt\\\":1,\\\"direction\\\":\\\"inbound\\\",\\\"errorCode\\\":\\\"0\\\",\\\"resultCode\\\":\\\"0\\\",\\\"country\\\":\\\"US\\\",\\\"resolvedDate\\\":\\\"2020-12-14T16:52:22.000Z\\\",\\\"createdAt\\\":\\\"2020-12-14T16:52:45.000Z\\\",\\\"accountId\\\":\\\"ddddfc7c-8f64-4a69-a2e7-f34457181711\\\",\\\"processingStatusName\\\":\\\"success\\\",\\\"classificationLabel\\\":\\\"inbound\\\",\\\"recipientName\\\":null,\\\"subject\\\":null,\\\"deviceId\\\":null,\\\"faxbridgeId\\\":null,\\\"deletedAt\\\":null,\\\"account\\\":{\\\"uuid\\\":\\\"ddddfc7c-8f64-4a69-a2e7-f34457181711\\\",\\\"accountNumber\\\":\\\"1202030519\\\",\\\"accountName\\\":\\\"Firstname Lastname\\\",\\\"accountType\\\":\\\"customer\\\"},\\\"cf\\\":{}}\"}",
    "body": {
        "name": "fax.inbound",
         "data": "{\"resultInfo\":\"OK\",\"messageId\":\"0eb6aec6-5648-4f14-88d5-58c0448d0b8c\",\"channelType\":\"web\",\"isArchived\":false,\"isFilePurged\":false,\"deliveryId\":\"2201214165226330782\",\"watermark\":\"2201214165241960798\",\"messageNumber\":\"127477054\",\"status\":\"success\",\"pagesCount\":1,\"pagesComplete\":1,\"duration\":194000,\"faxNumber\":\"+18778360721\",\"faxCsid\":\"12028837801\",\"faxCallerId\":\"2028837801\",\"faxECM\":256,\"faxSpeed\":14400,\"faxDetected\":true,\"faxProtocol\":17,\"faxAttempt\":1,\"direction\":\"inbound\",\"errorCode\":\"0\",\"resultCode\":\"0\",\"country\":\"US\",\"resolvedDate\":\"2020-12-14T16:52:22.000Z\",\"createdAt\":\"2020-12-14T16:52:45.000Z\",\"accountId\":\"ddddfc7c-8f64-4a69-a2e7-f34457181711\",\"processingStatusName\":\"success\",\"classificationLabel\":\"inbound\",\"recipientName\":null,\"subject\":null,\"deviceId\":null,\"faxbridgeId\":null,\"deletedAt\":null,\"account\":{\"uuid\":\"ddddfc7c-8f64-4a69-a2e7-f34457181711\",\"accountNumber\":\"1202030519\",\"accountName\":\"Firstname Lastname\",\"accountType\":\"customer\"},\"cf\":{}}"
    }
}

mFax phone numbers

When new users signup for Documo, you will be issued a randomly selected phone number. To port your existing Twilio number to Documo, follow these guides:

mFax pricing

Twilio has arranged a volume pricing arrangement with Documo:

Volume pricing grid for API-based faxing

Tier Bronze Silver Gold Platinum
Pages per month 0 -
50,000
50,001 -
250,000
250,001 -
499,999
500,000+

Price per page
(US/CA)

$0.04 $0.035 $0.03 $0.0275
DID MRC
(Fax numbers)
$2/mo per DID for all tiers.

Important notes:

  • Porting fees are $15 per DID.
  • Per page prices are based on a 60 second transmission time; pages that take longer to transmit may be charged as multiple pages.
  • 1 API user is included.
  • For more pricing info, please reach out to sales@documo.com.
Have more questions? Submit a request
Powered by Zendesk