Sending Commands

A Programmable Fax API command is sent with a fax_id. The fax_id allows a user to communicate to Telnyx the fax the user wants to take an action on.

The Telnys Programmable Fax API supports PDF files. To initiate sending the fax, we need to send the request to the Telnyx Programmable Fax API endpoint https://api.telnyx.com/v2/faxes.

Authentication

With the request we need to send additional parameters containing authentication information so Telnyx knows which account to send the fax from and information about the destination and file being sent.

Header	Description
media_url	The URL to the PDF used for the fax's media.
media_name	The media_name of a file to be used for the fax's media. The media_name must point to a file previously uploaded to api.telnyx.com/v2/media by the same user/organization. media_url and media_name can't be submitted together.
connection_id	The fax application ID to send the fax with.
to	The fax enabled phone number, in E.164 format, the fax will be sent to or SIP URI.
from	The phone number, in E.164 format, the fax will be sent from.
t38_enabled	The flag to disable the T.38 protocol. Set to `false` to disable.
monochrome	The flag to enable monochrome, true black and white fax results. Set to `true` to enable.
quality	The quality of the fax. Can be normal, high, very_high.
store_media	Should fax media be stored on temporary URL. It does not support media_name, they can't be submitted together.
Authorizaton: Bearer	The prefix to your API V2 key created in Step 2.

Available Commands and their Expected Webhooks

Telnyx sends webhooks to update on the status of Programmable Fax. Webhooks will also be sent in response to requests to list and delete faxes.

Command	Associated Webhooks
Send a fax	`fax.queued` `fax.media.processed` `fax.sending.started` `fax.delivered` `fax.failed`

Response when sending command

When you send a Programmable Fax API Command, you will immediately receive an http response. Responses include, but are not limited to:

HTTP Status Code	Message	Description
202	OK	The request succeeded.
403	Forbidden	The request was valid, however the user is not authorized to perform this action.
404	Not Found	The requested resource could not be found.
422	Invalid Parameters	The request has invalid parameters.
429	Too many requests	There is a limit for outbound faxes of 1500 faxes being processed at the same time.

Example: Sending Commands

To send a fax, send a POST request to the https://api.telnyx.com/v2/faxes endpoint as shown in the example below.

With a API V2 Key

curl -X POST https://api.telnyx.com/v2/faxes \
--data-urlencode "media_url=https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" \
--data-urlencode "connection_id=1232154810234" \
--data-urlencode "to=+13129457420" \
--data-urlencode "from=+19459457421" \
--header "Authorization: Bearer APIAuthKey_fromPortal"

Previous: Getting Started with Programmable Fax

Next: Receiving Webhooks