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

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const fax = await client.faxes.create({
  connection_id: '234423',
  from: '+13125790015',
  to: '+13127367276',
});

console.log(fax.data);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
fax = client.faxes.create(
    connection_id="234423",
    from_="+13125790015",
    to="+13127367276",
)
print(fax.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	fax, err := client.Faxes.New(context.TODO(), telnyx.FaxNewParams{
		ConnectionID: "234423",
		From:         "+13125790015",
		To:           "+13127367276",
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", fax.Data)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.faxes.FaxCreateParams;
import com.telnyx.sdk.models.faxes.FaxCreateResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        FaxCreateParams params = FaxCreateParams.builder()
            .connectionId("234423")
            .from("+13125790015")
            .to("+13127367276")
            .build();
        FaxCreateResponse fax = client.faxes().create(params);
    }
}

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $fax = $client->faxes->create(
    connectionID: '234423',
    from: '+13125790015',
    to: '+13127367276',
    blackThreshold: 1,
    clientState: 'aGF2ZSBhIG5pY2UgZGF5ID1d',
    fromDisplayName: 'Company Name',
    mediaName: 'my_media_uploaded_to_media_storage_api',
    mediaURL: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf',
    monochrome: true,
    previewFormat: 'pdf',
    quality: 'high',
    storeMedia: true,
    storePreview: true,
    t38Enabled: true,
    webhookURL: 'https://www.example.com/server-b/',
  );

  var_dump($fax);
} catch (APIException $e) {
  echo $e->getMessage();
}

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

{
  "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"
  }
}

{
  "errors": [
    {
      "code": "422",
      "title": "Unprocessable Entity",
      "detail": "The request parameters failed validation"
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "Unexpected error",
      "detail": "An unexpected error occured."
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

Send fax request

connection_id

string

required

The connection ID to send the fax with.

Example:

"234423"

string

required

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

Example:

"+13127367276"

from

string

required

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

Example:

"+13125790015"

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.

Example:

"https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"

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.

Example:

"my_media_uploaded_to_media_storage_api"

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.

Example:

"Company Name"

quality

enum<string>

default: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.

Available options:

normal,

high,

very_high,

ultra_light,

ultra_dark

Example:

"high"

t38_enabled

boolean

default:true

The flag to disable the T.38 protocol.

monochrome

boolean

default:false

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

black_threshold

integer

default:95

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

Required range: 1 <= x <= 100

store_media

boolean

default:false

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

store_preview

boolean

default:false

Should fax preview be stored on temporary URL.

preview_format

enum<string>

default:tiff

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

Available options:

pdf,

tiff

webhook_url

string

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

Example:

"https://www.example.com/server-b/"

client_state

string

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

Example:

"aGF2ZSBhIG5pY2UgZGF5ID1d"

Response

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

data

object

Show child attributes

Example:

{
  "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"
}

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const fax = await client.faxes.create({
  connection_id: '234423',
  from: '+13125790015',
  to: '+13127367276',
});

console.log(fax.data);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
fax = client.faxes.create(
    connection_id="234423",
    from_="+13125790015",
    to="+13127367276",
)
print(fax.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	fax, err := client.Faxes.New(context.TODO(), telnyx.FaxNewParams{
		ConnectionID: "234423",
		From:         "+13125790015",
		To:           "+13127367276",
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", fax.Data)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.faxes.FaxCreateParams;
import com.telnyx.sdk.models.faxes.FaxCreateResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        FaxCreateParams params = FaxCreateParams.builder()
            .connectionId("234423")
            .from("+13125790015")
            .to("+13127367276")
            .build();
        FaxCreateResponse fax = client.faxes().create(params);
    }
}

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $fax = $client->faxes->create(
    connectionID: '234423',
    from: '+13125790015',
    to: '+13127367276',
    blackThreshold: 1,
    clientState: 'aGF2ZSBhIG5pY2UgZGF5ID1d',
    fromDisplayName: 'Company Name',
    mediaName: 'my_media_uploaded_to_media_storage_api',
    mediaURL: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf',
    monochrome: true,
    previewFormat: 'pdf',
    quality: 'high',
    storeMedia: true,
    storePreview: true,
    t38Enabled: true,
    webhookURL: 'https://www.example.com/server-b/',
  );

  var_dump($fax);
} catch (APIException $e) {
  echo $e->getMessage();
}

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

{
  "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"
  }
}

{
  "errors": [
    {
      "code": "422",
      "title": "Unprocessable Entity",
      "detail": "The request parameters failed validation"
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "Unexpected error",
      "detail": "An unexpected error occured."
    }
  ]
}

Account & Billing

Video

SETI

Fax

OAuth

Bot Signup

For AI Agents

Send a fax

Authorizations

Body

Response