---
title: "Send a fax"
method: POST
path: "/faxes"
tags: ["Programmable Fax Commands"]
---

# 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.

**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`

## Request body

- SendFaxRequest
  - `black_threshold` integer — The black threshold percentage for monochrome faxes. Only applicable if `monochrome` is set to `true`.
  - `client_state` string — Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
  - `connection_id` string, required — The connection ID to send the fax with.
  - `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.
  - `media_name` 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. Supported formats: PDF, TIFF, JPEG, PNG, DOC, DOCX, RTF, and TXT. media_name and media_url/contents can't be submitted together.
  - `media_url` string — 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.
  - `monochrome` boolean — The flag to enable monochrome, true black and white fax results.
  - `preview_format` 'pdf' | 'tiff' — The format for the preview file in case the `store_preview` is `true`.
  - `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.
  - `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.
  - `t38_enabled` boolean — The flag to disable the T.38 protocol.
  - `to` string, required — The phone number, in E.164 format, the fax will be sent to or SIP URI
  - `webhook_url` string — Use this field to override the URL to which Telnyx will send subsequent webhooks for this fax.

## Response `202`

Send fax response

- object
  - `data` Fax
    - `client_state` string — State received from a command.
    - `connection_id` string — The ID of the connection used to send the fax.
    - `created_at` string, date-time — ISO 8601 timestamp when resource was created
    - `direction` 'inbound' | 'outbound' — The direction of the fax.
    - `failure_reason` string, nullable — Customer-facing failure reason for the fax. Present on every fax object (null when the fax has not failed). Mapped from the more granular `internal_failure_reason`. Common values include: `receiver_call_dropped`, `sender_call_dropped`, `sender_canceled`, `carrier_lost`, `service_unavailable`, `fax_signaling_error`, `receiver_communication_error`, `sender_communication_error`, `receiver_decline`, `receiver_recovery_on_timer_expire`, `receiver_no_response`, `receiver_invalid_number_format`, `receiver_no_answer`, `receiver_incompatible_destination`, `receiver_unallocated_number`, `destination_unreachable`, `user_busy`, `invalid_ecm_response_from_receiver`, `fax_initial_communication_timeout`, `destination_not_in_service_plan`, `account_disabled`, `destination_invalid`, `no_outbound_profile`, `destination_not_in_countries_whitelist`, `user_channel_limit_exceeded`, `outbound_profile_channel_limit_exceeded`, `connection_channel_limit_exceeded`, `outbound_profile_daily_spend_limit_exceeded`, `unverified_origination_number`, `unverified_destination_not_allowed`, `file_format_invalid`, `file_download_failed`, `file_size_limit_exceeded`, `page_count_limit_exceeded`, `media_processing_exception`.
    - `from` string — The phone number, in E.164 format, the fax will be sent from.
    - `from_display_name` string — The string used as the caller id name (SIP From Display Name) presented to the destination (`to` number).
    - `id` string, uuid — Identifies the type of resource.
    - `internal_failure_reason` string, nullable — Internal, more granular failure reason for the fax. Present on every fax object (null when the fax has not failed). Useful for deeper debugging beyond the customer-facing `failure_reason`.
    - `media_name` 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. Supported formats: PDF, TIFF, JPEG, PNG, DOC, DOCX, RTF, and TXT. media_name and media_url/contents can't be submitted together.
    - `media_url` string — 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.
    - `preview_url` string — If `store_preview` was set to `true`, this is a link to temporary location. Link expires after 10 minutes.
    - `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.
    - `record_type` 'fax' — Identifies the type of the resource.
    - `status` 'queued' | 'media.processed' | 'originated' | 'sending' | 'delivered' | 'failed' | 'initiated' | 'receiving' | 'media.processing' | 'received' — Status of the fax
    - `store_media` boolean — Should fax media be stored on temporary URL. It does not support media_name.
    - `stored_media_url` string — If store_media was set to true, this is a link to temporary location. Link expires after 10 minutes.
    - `to` string — The phone number, in E.164 format, the fax will be sent to or SIP URI
    - `updated_at` string, date-time — ISO 8601 timestamp when resource was updated
    - `webhook_failover_url` string — Optional failover URL that will receive fax webhooks if webhook_url doesn't return a 2XX response
    - `webhook_url` string — URL that will receive fax webhooks

## Other responses

- `422` — Unprocessable entity. The request was well-formed but contains semantic errors.
- `default` — Unexpected error

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api-2/revisions/1571b0380bd7/schema)