Sign in
Programmable Fax Commands

Send a fax

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.

Supported file formats:

  • PDF (application/pdf)
  • TIFF (application/tiff, image/tiff)
  • JPEG (image/jpeg)
  • PNG (image/png)
  • Microsoft Word .doc (application/msword)
  • Microsoft Word .docx (application/vnd.openxmlformats-officedocument.wordprocessingml.document)
  • Rich Text Format .rtf (application/rtf)
  • Plain text .txt (text/plain)

Expected Webhooks:

  • fax.queued
  • fax.media.processed
  • fax.sending.started
  • fax.delivered
  • fax.failed
post/faxes

Request body

connection_idstring required

The connection ID to send the fax with.

media_urlstring

The URL (or list of URLs) to the fax document. Supported formats: PDF, TIFF, JPEG, PNG, DOC, DOCX, RTF, and TXT. media_url and media_name/contents can't be submitted together.

media_namestring

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. Supported formats: PDF, TIFF, JPEG, PNG, DOC, DOCX, RTF, and TXT. media_name and media_url/contents can't be submitted together.

tostring required

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

fromstring required

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

from_display_namestring

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'normal' | 'high' | 'very_high' | 'ultra_light' | 'ultra_dark'

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_enabledboolean

The flag to disable the T.38 protocol.

monochromeboolean

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

black_thresholdinteger

The black threshold percentage for monochrome faxes. Only applicable if monochrome is set to true.

store_mediaboolean

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

store_previewboolean

Should fax preview be stored on temporary URL.

preview_format'pdf' | 'tiff'

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

webhook_urlstring

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

client_statestring

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

Example request

{
  "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",
  "webhook_url": "https://www.example.com/server-b/",
  "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d"
}

Response

Fax queued for sending. Track its progress by polling GET /faxes/{id} with the returned fax id.

Example response

{
  "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",
    "failure_reason": null,
    "internal_failure_reason": null,
    "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
    "created_at": "2020-05-05T09:59:12Z",
    "updated_at": "2020-05-05T09:59:12Z"
  }
}

Changes

Changed in 4 of the 99 revisions of this API.62

  • a6a61a29ecdd2See the full diff
    • ▲

      the // response's property type changed from string to integer, and format from no format to int32 for status

      response-property-type-changed

    • ▲

      the // response's property type changed from string to integer, and format from no format to int32 for status

      response-property-type-changed

    This revision also has 34 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 1571b0380bd72See the full diff
    • ▲

      the // response's property type changed from integer to string, and format from int32 to no format for status

      response-property-type-changed

    • ▲

      the // response's property type changed from integer to string, and format from int32 to no format for status

      response-property-type-changed

    This revision also has 64 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 8f5f4e5379942See the full diff
    • ▲

      the // response's property type changed from string to integer, and format from no format to int32 for status

      response-property-type-changed

    • ▲

      the // response's property type changed from string to integer, and format from no format to int32 for status

      response-property-type-changed

    This revision also has 41 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • dd933b0ed49d2See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

Of the 99 revisions, 1 has no diff computed.