Skip to content
Fax/
API Reference
/
/
Update numbers for email

Fax API (3.0)

This document provides a detailed user guide and reference documentation on the Fax REST API.

If you have questions please contact us via our support portal and a team member will be happy to assist.

Note:

You must create an account on our support portal if you do not have one.

Authentication

For information on how to authenticate API requests we support two methods Basic or Oauth2

Global URL

Sinch has a global server that will route your call to the appropriate geography region automatically:

https://fax.api.sinch.com/

Formats

By default, all API calls return a JSON response unless otherwise specified.

Date time fields

All date and time fields are in UTC format unless otherwise specified.

Deletion and data retention

In general we retain fax logs and media for 13 months and you can access that via the API.

Errors & statuses

Find error codes and explanations here.

Webhooks

You can configure your service to use webhooks to send a request to you when faxes arrive or complete on your account.

Download OpenAPI description
fax.json
fax.yaml
Overview
URL
https://www.sinch.com/contact/
Contact Fax API Team
faxteam@sinch.com
License
MIT
Languages
Servers
v3.0 of the Fax API
https://fax.api.sinch.com/v3/projects/{projectId}

Faxes

The Fax API allows you to send and receive faxes. You can send faxes to a single recipient or to multiple recipients. You can also receive faxes and download them.

To send a TEST Outbound fax you can send a fax TO +19898989898. This will emulate all aspects of a real fax without charging your account.

Operations
Webhooks

Notifications

Webhooks allow you to get updates in real-time about the status of your faxes. Webhooks are triggered by events such as the completion of a fax, and transmit information about the state of that fax to you via HTTP(S) or email. HTTP webhooks are multipart/form-data POST requests, and should be processed like form submissions.

Webhooks

Fax to Email

The Emails endpoint allows you to configure the Fax to Email functionality. Fax to Email allows you to send an email and then receive a fax on your Sinch number or send a fax and have it sent to your email address. The service supports sending incoming faxes to multiple email addresses and having many numbers associated with one email address.

Operations

Setting up fax to email

You can configure fax to email in two different places:

  • In the dashboard on a number-by-number basis or by adding an email address and associating many numbers to one email address.
  • Via the API when you create a number or update a number, or by using the email endpoint to set it up directly
  • Supported fax to email file types are Word, PDF, and TIF

Fax to email example

The following example shows how to configure Fax to Email using the API:

  1. Buy a number in the dashboard and assign it to a Fax service
  2. Add your email and associate it with the number you bought in step 1.
POST https://fax.api.sinch.com/v3/projects/{projectId}/services/{serviceId}/emails
 {
    "email": "user@domain.com",
    "phoneNumbers": [
       "+14155552222"
    ]
}

Now you can use your email client with the above email address to fax.

Send a fax using email

Make sure the email address you are sending from is added to your account. You can add it in the dashboard under Fax to email or via the API.

Send an email to {PhoneNumberToSendFaxTo}@sinchfax.com with the following:

FieldDescription
Subject:If you have multiple phone numbers associated with the email address, enter the number you want to use. If left blank, the first number that we find will be used.
Body:By default, the email body is not used.
AttachmentsAdd any attachments you want to fax. If you want to specify the order of pages we recommend that you create one document with all pages in the correct order and attach that document. If you attach multiple documents we will merge them into one document in the order we receive them.

Receive a fax using email

When you receive a fax, we will send you an email with the following:

FieldDescription
From:The number the fax was sent from, e.g. +15612600684@sinchfax.com
Subject:Fax received on {your sinch number the fax was sent to}
Body:The body will contain data such as number of pages or other relevant metadata of the fax.

There will be one PDF attachment with the fax content.

Configuring your email system for best performance

Make sure you allowlist sinchfax.com and sinch.com in your spam filter to ensure delivery to your inbox, both on client and server side. Ensure your mail server is setup correctly and not on spam lists.

Encryption

All emails are sent using TLS during transport from Sinch.

List emails for a number

Request

List any emails for a number.

Security
BasicAuth or OAuth2
Path
phoneNumberstringrequired

The phone number you want to get emails for.

Example: +15612600684
idstringrequired

The serviceId containing the numbers you want to list.

Query
pageinteger

The page to fetch. If not specified, the first page will be returned.

Default 1
Example: page=1
pageSizeinteger<= 1000

Number of items to return on each page.

Default 100
Example: pageSize=20
curl -i -X GET \
  -u <username>:<password> \
  'https://fax.api.sinch.com/v3/projects/YOUR_project_id/services/{id}/numbers/+15612600684/emails?page=1&pageSize=20'

Responses

A list of emails associated with the number.

Bodyapplication/json
emailsArray of strings(email)

List of emails numbers

pageintegerread-only

Current page

totalPagesintegerread-only

Total number of pages.

pageSizeintegerread-only

Number of items per page.

totalItemsinteger(int32)read-only

Total size of the result.

Response
application/json
{
  "emails": [
    "user@example.com"
  ],
  "page": 0,
  "totalPages": 0,
  "pageSize": 0,
  "totalItems": 0
}

List emails

Request

List emails for the project.

Security
BasicAuth or OAuth2
Path
serviceIdstringrequired

The serviceId containing the emails you want to list.

Query
pageinteger

The page to fetch. If not specified, the first page will be returned.

Default 1
Example: page=1
pageSizeinteger<= 1000

Number of items to return on each page.

Default 100
Example: pageSize=20
curl -i -X GET \
  -u <username>:<password> \
  'https://fax.api.sinch.com/v3/projects/YOUR_project_id/services/{serviceId}/emails?page=1&pageSize=20'

Responses

A list of emails associated with the project.

Bodyapplication/json
emailsArray of objects(Email)

List of emails

pageintegerread-only

Current page

totalPagesintegerread-only

Total number of pages.

pageSizeintegerread-only

Number of items per page.

totalItemsinteger(int32)read-only

Total size of the result.

Response
application/json
{
  "emails": [
    { … }
  ],
  "page": 0,
  "totalPages": 0,
  "pageSize": 0,
  "totalItems": 0
}

Add an email

Request

Add an email to the specified service to be used for sending and receiving faxes. Default settings for permissions parameter is both.

Security
BasicAuth or OAuth2
Path
serviceIdstringrequired

The serviceId to which you want to add the email.

Bodyapplication/json
emailstring(email)required
Example: "user@domain.com"
phoneNumbersArray of objects(Number)required

Numbers you want to associate with this email.

phoneNumbers[].​numberstring(phoneNumber)(PhoneNumber)

A phone number in E.164 format, including the leading '+'.

phoneNumbers[].​permissionsstring

Allows you to set permissions for sending and receiving faxes to this email/phone number combination. Default value is both.

Default "both"
Enum ValueDescription
both

Allows the email to send and receive faxes to this email/phone number combination.

send

Allows the email to only send faxes to this email/phone number combination.

receive

Allows the email to only receive faxes from this email/phone number combination.

curl -i -X POST \
  -u <username>:<password> \
  'https://fax.api.sinch.com/v3/projects/YOUR_project_id/services/{serviceId}/emails' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@domain.com",
    "phoneNumbers": [
      {
        "number": "+14155552222",
        "permissions": "both"
      }
    ]
  }'

Responses

The added email

Bodyapplication/json
emailstring(email)required
Example: "user@domain.com"
phoneNumbersArray of objects(Number)required

Numbers you want to associate with this email.

phoneNumbers[].​numberstring(phoneNumber)(PhoneNumber)

A phone number in E.164 format, including the leading '+'.

phoneNumbers[].​permissionsstring

Allows you to set permissions for sending and receiving faxes to this email/phone number combination. Default value is both.

Default "both"
Enum ValueDescription
both

Allows the email to send and receive faxes to this email/phone number combination.

send

Allows the email to only send faxes to this email/phone number combination.

receive

Allows the email to only receive faxes from this email/phone number combination.

projectIdstringread-only

The Id of the project associated with the call.

Example: "ae00f005-e392-44dc-b3f5-a657a2684dg3"
Response
application/json
{
  "email": "user@domain.com",
  "phoneNumbers": [
    { … }
  ],
  "projectId": "ae00f005-e392-44dc-b3f5-a657a2684dg3"
}

Update numbers for email

Request

Set the numbers for an email.

Security
BasicAuth or OAuth2
Path
serviceIdstringrequired

The serviceId containing the email you want to work with.

emailstringrequired

The email you want to work with.

Bodyapplication/json
phoneNumbersArray of objects(Number)required

List of numbers

phoneNumbers[].​numberstring(phoneNumber)(PhoneNumber)

A phone number in E.164 format, including the leading '+'.

phoneNumbers[].​permissionsstring

Allows you to set permissions for sending and receiving faxes to this email/phone number combination. Default value is both.

Default "both"
Enum ValueDescription
both

Allows the email to send and receive faxes to this email/phone number combination.

send

Allows the email to only send faxes to this email/phone number combination.

receive

Allows the email to only receive faxes from this email/phone number combination.

curl -i -X PUT \
  -u <username>:<password> \
  'https://fax.api.sinch.com/v3/projects/YOUR_project_id/services/{serviceId}/emails/{email}' \
  -H 'Content-Type: application/json' \
  -d '{
    "phoneNumbers": [
      {
        "number": "+14155552222",
        "permissions": "both"
      }
    ]
  }'

Responses

The added email

Bodyapplication/json
emailstring(email)required
Example: "user@domain.com"
phoneNumbersArray of objects(Number)required

Numbers you want to associate with this email.

phoneNumbers[].​numberstring(phoneNumber)(PhoneNumber)

A phone number in E.164 format, including the leading '+'.

phoneNumbers[].​permissionsstring

Allows you to set permissions for sending and receiving faxes to this email/phone number combination. Default value is both.

Default "both"
Enum ValueDescription
both

Allows the email to send and receive faxes to this email/phone number combination.

send

Allows the email to only send faxes to this email/phone number combination.

receive

Allows the email to only receive faxes from this email/phone number combination.

projectIdstringread-only

The Id of the project associated with the call.

Example: "ae00f005-e392-44dc-b3f5-a657a2684dg3"
Response
application/json
{
  "email": "user@domain.com",
  "phoneNumbers": [
    { … }
  ],
  "projectId": "ae00f005-e392-44dc-b3f5-a657a2684dg3"
}

Remove email

Request

Delete an email and associated numbers to that email to disable that email from sending and receiving faxes.

Security
BasicAuth or OAuth2
Path
serviceIdstringrequired

The serviceId containing the email you want to work with.

emailstringrequired

The email you want to work with.

curl -i -X DELETE \
  -u <username>:<password> \
  'https://fax.api.sinch.com/v3/projects/YOUR_project_id/services/{serviceId}/emails/{email}'

Responses

No content: The email was deleted

Get numbers for email

Request

Get configured numbers for an email

Security
BasicAuth or OAuth2
Path
serviceIdstringrequired

The serviceId containing the email you want to work with.

emailstringrequired

The email you want to get numbers for.

Query
pageSizeinteger<= 1000

Number of items to return on each page.

Default 20
Example: pageSize=20
pagestring

Optional. The page to fetch. If not specified, the first page will be returned.

curl -i -X GET \
  -u <username>:<password> \
  'https://fax.api.sinch.com/v3/projects/YOUR_project_id/services/{serviceId}/emails/{email}/numbers?pageSize=20&page=string'

Responses

A list of numbers associated with the email

Bodyapplication/json
phoneNumbersArray of objects(ServicePhoneNumber)

List of numbers

pageintegerread-only

Current page

totalPagesintegerread-only

Total number of pages.

pageSizeintegerread-only

Number of items per page.

totalItemsinteger(int32)read-only

Total size of the result.

Response
application/json
{
  "phoneNumbers": [
    { … }
  ],
  "page": 0,
  "totalPages": 0,
  "pageSize": 0,
  "totalItems": 0
}

Cover pages

You can add cover pages to Sinch Fax either via the API or the Build dashboard.

A Fax service can have 0 or more cover pages configured.

Operations

Error Messages

Services

A fax service identifies a set of configuration values. You can specify the service as a part of an API request or by associating a Sinch number with a service.

This can be useful if you want to point a group of numbers to a particular incoming fax URL, or want to set the storage strategy for some of your numbers but not all of them.

Operations