Rate this page:

TwiML™ Fax: <Receive>

We have made the difficult decision to disable Programmable Fax for all accounts on December 17, 2021. For new and inactive accounts, access to Programmable Fax is disabled effective immediately. We recognize the challenges this decision might cause and have provided detailed migration plans to prevent disruptions.

For Japan customers, please refer to this migration plan. For all other customers, please refer to this migration plan. Learn more.

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

Optional Element Attributes

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 the below information.

        Receive a fax and provide a url endpoint

        Receive a Fax with Action URL

        Receive a fax and provide a url endpoint
              This code receives the incoming media and stores it on Twilio's servers in TIFF format. MediaUrl will point to the received media.

              Store Fax Image as TIFF

              This code receives the incoming media and stores it on Twilio's servers in TIFF format. MediaUrl will point to the received media.

              Action Callback

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

              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 (See the status property of the Fax resource)
              ApiVersion The API version used to receive the fax (for this API: v1)
              NumPages If successful, the number of pages received
              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

              Avoiding Media Storage

              • If you are expecting sensitive material, you can specify storeMedia="false" as an attribute on this verb. Twilio will not store the media on our servers at all if so. Please note the following changes, limitations, and possible concerns.
              • You must specify an action callback with a POST method.
              • Instead of being provided a MediaUrl in the callback, the media file itself will be provided in a parameter called Media
              • The callback is sent using the multipart/form-data content-type (not application/x-www-form-urlencoded).
              • The media will be permanently deleted on Twilio's side after the callback is successfully delivered.
              • If we receive any of 500, 502, 503 or 504 HTTP responses from your server, we will attempt to deliver the callback with the media every 2.5 minutes for up to 2 hours.
              • 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.
              Rate this page:

              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 by visiting Twilio's Community Forums or browsing the Twilio tag on Stack Overflow.


                    Thank you for your feedback!

                    We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

                    Sending your feedback...
                    🎉 Thank you for your feedback!
                    Something went wrong. Please try again.

                    Thanks for your feedback!

                    Refer us and get $10 in 3 simple steps!

                    Step 1

                    Get link

                    Get a free personal referral link here

                    Step 2

                    Give $10

                    Your user signs up and upgrade using link

                    Step 3

                    Get $10

                    1,250 free SMSes
                    OR 1,000 free voice mins
                    OR 12,000 chats
                    OR more