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:
- Prerequisite: Signup for Documo
- Send a Fax via the mFax Console UI
- Send a Fax via Email
- Send a Fax via the mFax REST API
- Receive a fax via mFax
- mFax phone numbers
- mFax pricing
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
coverPageparameter allows you to include a cover page you have created on your account, or a specificcoverPageId. For more information, see Documo's guide on Creating a custom cover page. - The
cfparameter 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 |
$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.