How do I send a fax using the Dropbox Fax API?

Once your integration is setup with authentication using Steps 1-7 of the Walkthrough, you can start to send faxes through the API.

Now let's actually send a fax:

curl -u"[your username]:[your password]" "https://api.hellofax.com/v1/Accounts/[Your Account GUID]/Transmissions?To=[destination phone number]" -F file=@myfile.pdf`

This will begin the process of sending the fax. Just because you get a 200 HTTP response to this call does not mean that the fax will go through or even be sent (a file conversion error could occur). However, once the fax's StatusCode becomes E (for Error) or S (for Success) you will get a POST back to the callback URL you specified in step #5. Click here for an example of the callback event body.

Possible StatusCode values:

T = transmitting/sending
P = pending/converting
S = successfully sent
E = error. Failed to convert or to send fully
H = on hold. A type of error caused by having an unconfirmed account or by being out of fax pages and not having a monthly subscription.

Possible ErrorCode values (reference only when StatusCode is set to E):

B = received a busy signal
N = no answer
A = unallocated number (usually means it has been disconnected)
D = the line is disconnected or unreachable
L = this number has been blacklisted (shouldn't happen for any US number)
U = unknown error. This usually occurs when a human answers the line or an error occurred during the fax transmission.

NOTES:

A.  If you send a fax and the receiver's fax machine supports reading CSID, then the caller ID will display your primary fax number (or the fax number you specify in the ‘From’ parameter). (Fax machines supporting CSID is a standard: http://en.wikipedia.org/wiki/Called_subscriber_identification) Also, keep in mind that your primary fax number will be overlaid on the fax itself. If you have multiple Dropbox Fax fax lines, you may specify which one to use as the sending fax machine by including the 'From' parameter in the URL, e.g.:

curl -u"[your username]:[your password]" "https://api.hellofax.com/v1/Accounts/[Your Account GUID]/Transmissions?To=[destination phone number]&From=[your fax line phone number]" -F file=@myfile.pdf`

For the format of the "From" value, please see the "Number" field returned by calling /FaxLines (see step #5)

B.  You can upload multiple files and/or send multiple faxes in one call - just make the `file` and/or `To` params each an array:

curl -u"[your username]:[your password]" -F file[]="@1.pdf" -F file[]="@2.txt" "https://api.hellofax.com/v1/Accounts/[Your Account GUID]/Transmissions?To=[phone number in all digits]"

// or

curl -X POST https://[your username]:[your password]@api.hellofax.com/v1/Accounts/[Your Account GUID]/Transmissions -F 'file[0]=@file1.pdf' -F 'file[1]=@file2.pdf' -F 'To[0]=[destination fax number 0]' -F 'To[1]=[destination fax number 1]'

C.  You can add a Dropbox Fax generated cover page by supplying one or more of the following parameters: CoverPageTo, CoverPageFrom, and CoverPageMessage

D.  Faxes sent via the API are not stored on our servers once the fax has successfully been sent - they are removed. Therefore they are not available to be viewed in our UI. However incoming faxes which are successfully POST'ed to your callback are stored on our servers and are available in your "documents" screen. It's only outgoing faxes (from the API) that we delete and do not make available in the UI.

E. There is a 500 Pending Faxes in the prior day rate limit. If you hit the limit, you'll receive this 429 error:

Error sending fax. Status: 429; Message: Please wait. You already have at least 500 transmissions that are currently pending or transmitting.