A convenient library for the eFax automated Fax sending API.
API documentation is at https://secure.efaxdeveloper.com/downloads.jsp.
All procedures accept account, username and password keyword arguments, which you can pass on each call. Alternatively, you can set these once in a global parameter so you can easily put it in a configuration file, or enter it once on the REPL. If you pass account, username and password to the procedure, those will have precedence over the global parameters.
- (efax-account [ACCOUNT]) parameter
ACCOUNT should be a string which identifies your eFax developer account number. This is generally your fax number (digits only, no spaces etc).
- (efax-username [USERNAME]) parameter
USERNAME should be a string which identifies your eFax developer username.
- (efax-password [PASSWORD]) parameter
PASSWORD should be a string which identifies your eFax password.
- (efax-send RECIPIENTS FILES [account: ACCOUNT] [username: USERNAME] [password: PASSWORD] [transmission-id: TID] [unique-id: UNIQUE?] [customer-id: CID] [self-busy: SELFBUSY?] [high-resolution: HIRES?] [high-priority: PRIO?]) procedure
Send FILES (a list of pairs) as a fax message to RECIPIENTS, which is either a string, a list of strings or a list of alists identifying the recipients. If it's a string or list of strings, these are assumed to be the fax numbers for these recipients. If RECIPIENTS is an alist, it can contain the following keys: name, company and fax. fax is a string containing the fax number of this recipient (must be supplied), company is a string that holds the company name (optional) and name is a string that holds the recipient name (optional). These keys can be used in the fax header line.
FILES should be a list of pairs, the car being a symbol or string identifying the type of the file and the cdr being a string with the file's contents. The allowed values for the type are: pdf, txt, doc(x), xls(x), ppt(x), htm(l), png, smp, gif, tif(f), jp(e)g, or rtf.
If TID is given, this can later be used as a key to retrieve the status using efax-status. If UNIQUE? is #t, this key must be unique or an error is raised. Both default to #f.
CID is purely informational and will be returned in subsequent efax-status calls. Can be useful for accounting or debugging purposes. Defaults to #f.
If HIRES? is #t, the fax will be in high resolution and if PRIO? is #t, the fax will be given extra priority. Both these options cost extra! Both default to #f.
The result of this call is an alist with two keys:
- The document ID of this transmission assigned by eFax.
- The transmission ID which you supplied as TID, or #f if you didn't supply one.
- (efax-status [account: ACCOUNT] [username: USERNAME] [password: PASSWORD] [doc-id: DID] [transmission-id: TID]) procedure
Fetch the status of a message previously sent with efax-send (or other means). You can either pass DID, which should be the eFax document id (document-id in the alist returned by efax-send) or your own transmission identifier (transmission-id in the alist returned by efax-send, which is the TID you passed in yourself).
This will return an alist which currently has two keys: transmission-id and recipients. transmission-id is simply the transmission ID of the message, or #f if you didn't provide one when sending it. recipients is a list of pairs, the cars of which are fax numbers (strings) and the cdrs of which are alists with the following keys (all values are strings):
- name (optional)
- The name of the recipient as specified in efax-send.
- company (optional)
- The company of the recipient as specified in efax-send.
- The fax number again
- A human-readable message indicating the message's current status.
- status-classification (optional)
- A value indicating the message's status "classification".
- status-outcome (optional)
- Another value like status-classification. The difference is unclear from the documentation. In success cases both status-classification and status-outcome have "Success" as a value.
- last-attempt-date (optional)
- The date of the last transmission attempt.
- last-attempt-time (optional)
- The time of the last transmission attempt.
- next-attempt-date (optional)
- The date when the next transmission attempt will take place, if the message hasn't been successfully transmitted and eFax hasn't given up yet.
- next-attempt-time (optional)
- The time when the next transmission attempt will take place.
- pages-scheduled (optional)
- The number of pages that were scheduled for transmission.
- pages-sent (optional)
- The number of pages that were actually sent.
- baud-rate (optional)
- The baud rate used for the transmission.
- duration (optional)
- Duration in minutes for the transmission.
- retries (optional)
- Number of retries for the transmission.
- remote-csid (optional)
- The CSID transmitted to.
In case of errors, an composite condition of types (exn efax) is raised. The efax condition contains the following properties:
- The code used to indicate that there's an error (should be "2", unless something is really wrong)
- A description of the error status (usually just "Failure", though...)
- The level of the error, a symbol which is either user or system. If it's system, it's an internal error on eFax's end and you might need to contact eFax support to have them fix it.
- Might be #f, but if present it's a string which indicates the eFax internal document ID the error refers to.
- Might also be #f, but if present it's the transmission ID you assigned to the document the error refers to.
- Currently efax-status returns only strings in the recipient alist. This should probably convert some values (the numerical ones, particularly) to Scheme types.
- All the "disposition" support (URLs, Email) is unimplemented right now.
- All data is currently processed in-memory. For large files this may be undesirable.
- Dynamic fax headers are currently unimplemented.
- The SelfBusy option is not implemented, as I have absolutely no clue what it does and hence can't properly document it. If I understand it correctly, this option determines whether the recipients can accept simultaneous incoming connections. However, if that's the case, why is it a property of the transmission in general, instead of each recipient?
- 0.1 Initial release
Copyright (c) 2011, Response Genetics, Inc. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.