How to send a fax using the Dropbox Fax API

This article covers how to start sending faxes using the Dropbox Fax API, once the integration has been set up and authenticated.

Learn how to set up Dropbox Fax API.

How to send a fax

To 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`

Just because you get a 200 HTTP response, it doesn’t guarantee the fax will be sent or go through (a file conversion error could occur). Once the fax's StatusCode becomes E (for Error) or S (for Success) you'll get a POST back to the callback URL you specified when setting up the API.
 

Possible StatusCode values:

T: Transmitting/sending.
P: Pending/converting.
S: Successfully sent.
E: Error. Failed to convert or to fully send.
O: On hold. An error caused by having an unconfirmed account or by being out of fax pages and without a monthly subscription.
 

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

R: Received a busy signal.
N: No answer.
A: Unallocated number (usually means it's disconnected).
D: The line is disconnected or unreachable
L: This number is on the denied list (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:

• 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). Your primary fax number will be overlaid on the fax. If you have multiple Dropbox Fax lines, you may choose which one to use as the sending fax machine by including the 'From' parameter in the URL:
  
   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, review the available fax lines.
  
  
• You can upload multiple files or send faxes to multiple recipients in a single request by providing the "file" and "To" parameters as arrays:
  
   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]'
  
  
• You can add a Dropbox Fax-generated cover page by supplying one or more of the following parameters: CoverPageTo, CoverPageFrom, and CoverPageMessage.
  
  
• Faxes sent by the API aren't stored on Dropbox Fax servers. Once they’re successfully sent, they’re removed so they’re not available to be viewed However incoming faxes which are successfully POST'ed to your callback are stored on the servers and are available in your "documents" screen. Only outlet going faxes are deleted and made unavailable.
  
  
• Users are limited to 200 pending faxes per day. 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.