Skip to main content

Send a fax

POST 
/faxes

Send a fax. Files have size limits and page count limit validations. If a file is bigger than 50MB or has more than 350 pages it will fail with file_size_limit_exceeded and page_count_limit_exceeded respectively.

Expected Webhooks:

  • fax.queued
  • fax.media.processed
  • fax.sending.started
  • fax.delivered
  • fax.failed

Request

Body

required

Send fax request

    connection_id stringrequired

    The connection ID to send the fax with.

    media_url MediaUrl (string)

    The URL (or list of URLs) to the PDF used for the fax's media. media_url and media_name/contents can't be submitted together.

    media_name MediaName (string)

    The media_name used for the fax's media. Must point to a file previously uploaded to api.telnyx.com/v2/media by the same user/organization. media_name and media_url/contents can't be submitted together.

    to To (string)required

    The phone number, in E.164 format, the fax will be sent to or SIP URI

    from From (string)required

    The phone number, in E.164 format, the fax will be sent from.

    from_display_name string

    The from_display_name string to be used as the caller id name (SIP From Display Name) presented to the destination (to number). The string should have a maximum of 128 characters, containing only letters, numbers, spaces, and -_~!.+ special characters. If ommited, the display name will be the same as the number in the from field.

    quality Quality (string)

    Possible values: [normal, high, very_high, ultra_light, ultra_dark]

    Default value: high

    The quality of the fax. The ultra settings provides the highest quality available, but also present longer fax processing times. ultra_light is best suited for images, wihle ultra_dark is best suited for text.

    t38_enabled boolean

    Default value: true

    The flag to disable the T.38 protocol.

    monochrome boolean

    The flag to enable monochrome, true black and white fax results.

    store_media boolean

    Should fax media be stored on temporary URL. It does not support media_name, they can't be submitted together.

    store_preview boolean

    Should fax preview be stored on temporary URL.

    preview_format string

    Possible values: [pdf, tiff]

    Default value: tiff

    The format for the preview file in case the store_preview is true.

    webhook_url string

    Use this field to override the URL to which Telnyx will send subsequent webhooks for this fax.

    client_state string

    Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.

Responses

202: Send fax response

default: Unexpected error

Callbacks

Request samples


curl -L 'https://api.telnyx.com/v2/faxes' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
"connection_id": "234423",
"media_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
"media_name": "my_media_uploaded_to_media_storage_api",
"to": "+13127367276",
"from": "+13125790015",
"from_display_name": "Company Name",
"quality": "high",
"t38_enabled": true,
"monochrome": false,
"store_media": false,
"store_preview": false,
"preview_format": "tiff",
"webhook_url": "https://www.example.com/server-b/",
"client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d"
}'

Response samples


{
"data": {
"record_type": "fax",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"connection_id": "c-1",
"direction": "outbound",
"from": "+123",
"to": "+456",
"media_url": "http://www.example.com/fax.pdf",
"store_media": true,
"stored_media_url": "https://s3.amazonaws.com/faxes-dev/user-1/cf4a6b52-bf8e-4945-9f49-611d0d2b083b.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=xxxxxxxxxx%2F20200505%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200505T095917Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=fac2af40464fcc77673ad762db86e34f9c1b91a82699b5578c5327f53874df51",
"preview_url": "https://s3.amazonaws.com/faxes-dev/user-1/cf4a6b52-bf8e-4945-9f49-611d0d2b083b_preview.tiff?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=xxxxxxxxxx%2F20200505%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200505T095917Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=fac2af40464fcc77673ad762db86e34f9c1b91a82699b5578c5327f53874df51",
"quality": "high",
"webhook_url": "http://www.example.com/webhooks",
"webhook_failover_url": "",
"status": "queued",
"client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
"created_at": "2020-05-05T09:59:12",
"updated_at": "2020-05-05T09:59:12"
}
}