TwiML™ Fax: <Receive>

The verb <Receive> instructs Twilio to receive an incoming fax. This results in the creation of a new Fax instance resource.

Optional Element Attributes

ATTRIBUTE	DESCRIPTION
action	URL to consult when the fax has been received or has failed
method	HTTP method to use when requesting the action URL; POST or GET. Defaults to POST.
mediaType	The media type used to store media in the fax media store. Currently, supported values are: `application/pdf` (the default) and `image/tiff`.
pageSize	What size to interpret received pages as (defaults to `letter`, US Letter). Supported values: `letter`, `legal`, and `a4`.
storeMedia	Whether or not to store received media in the fax media store (defaults to `true`). If setting to `false` please see below for more information.

Receive a Fax with Action URL

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Receive action="/fax/received"/>
</Response>

Receive a fax and provide a url endpoint

Receive a Fax with Action URL

Receive a fax and provide a url endpoint

Store Fax Image as TIFF

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Receive mediaType="image/tiff" storeMedia="true"></Receive>
</Response>

Specify file format with the mediaType attribute

Store Fax Image as TIFF

Specify file format with the mediaType attribute

Action Callback

If action is specified, the parameters sent in the action callback will include:

PARAMETER	DESCRIPTION
FaxSid	The 34-character unique identifier for the fax
AccountSid	The account on which the fax was received
From	The caller ID of the sending fax machine
To	The Twilio phone number receiving the fax
RemoteStationId	The transmitting subscriber identification (TSID) reported by the sending fax machine
FaxStatus	The status of the fax transmission
ApiVersion	The API version used to receive the fax, which for this API is "v1"
NumPages	The number of pages received (only if successful)
MediaUrl	A media URL on Twilio's servers that can be used to fetch the received media. Note that this URL will expire after 2 hours, but a new URL can be fetched from the Fax instance resource
ErrorCode	A Twilio error code that gives more information about a failure, if any
ErrorMessage	A detailed message describing a failure, if any

If you are expecting sensitive material that should not be stored on Twilio's servers after it is received, you can specify storeMedia="false" as an attribute on this verb. However, please note the following changes, limitations, and possible concerns:

An action callback must be specified, and the only supported method is POST. Instead of being provided a MediaUrl in the callback, the media file itself will be provided in a parameter called Media, and the callback will be sent using the multipart/form-data content-type (rather than the usual application/x-www-form-urlencoded).

The media will be permanently deleted on Twilio's side after the callback is successfully delivered. If we do not receive a 2xx HTTP response from your server, we will continue to try to deliver the callback (with media) for the next 2 hours (we will try every 2.5 minutes). If we still have not received a 2xx response from your server after 2 hours, the media will be deleted.

Twilio still stores a metadata record of the received fax. If you wish to delete this record, you can do so using the REST API.

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.