Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

eFax
  1. Outdated egg!
  2. eFax
    1. Description
    2. Author
    3. Requirements
    4. Repository
    5. Documentation
      1. Sending faxes
      2. Checking message status
    6. Errors
    7. TODO
    8. Changelog
    9. License

Description

A convenient library for the eFax automated Fax sending API.

API documentation is at https://secure.efaxdeveloper.com/downloads.jsp.

Author

Written for Response Genetics, Inc. by Peter Bex.

Requirements

Requires the http-client, base64, sxml-serializer, ssax and sxpath eggs.

Repository

http://code.more-magic.net/efax.

Documentation

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.

[parameter] (efax-account [ACCOUNT])

ACCOUNT should be a string which identifies your eFax developer account number. This is generally your fax number (digits only, no spaces etc).

[parameter] (efax-username [USERNAME])

USERNAME should be a string which identifies your eFax developer username.

[parameter] (efax-password [PASSWORD])

PASSWORD should be a string which identifies your eFax password.

Sending faxes

[procedure] (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?])

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:

doc-id
The document ID of this transmission assigned by eFax.
transmission-id
The transmission ID which you supplied as TID, or #f if you didn't supply one.

Checking message status

[procedure] (efax-status [account: ACCOUNT] [username: USERNAME] [password: PASSWORD] [doc-id: DID] [transmission-id: TID])

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.
fax
The fax number again
status-message
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.

Errors

In case of errors, an composite condition of types (exn efax) is raised. The efax condition contains the following properties:

error-code
The code used to indicate that there's an error (should be "2", unless something is really wrong)
error-description
A description of the error status (usually just "Failure", though...)
error-level
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.
document-id
Might be #f, but if present it's a string which indicates the eFax internal document ID the error refers to.
transmission-id
Might also be #f, but if present it's the transmission ID you assigned to the document the error refers to.

TODO

Changelog

License

 
 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.