(index ("smsmatrix-username" 0) ("smsmatrix-password" 210) ("send-sms" 376) ("send-fax" 2355) ("get-credits" 4493) ("message-status" 4679) ("get-rate" 5460) ("carrier-name" 6033) ("call-with-csv-report" 6451))
(def (sig (parameter "(smsmatrix-username [USERNAME])" (id smsmatrix-username))) (p (tt "USERNAME") " should be a string which identifies your SMSMatrix username (generally in the form of an email address)."))
(def (sig (parameter "(smsmatrix-password [PASSWORD])" (id smsmatrix-password))) (p (tt "PASSWORD") " should be a string which identifies your SMSMatrix password."))
(def (sig (procedure "(send-sms RECIPIENTS MESSAGE [username: USERNAME] [password: PASSWORD] [group: GROUP?] [tts-fallback: FALLBACK?] [error-on-failure ERROR?])" (id send-sms))) (p "Send " (tt "MESSAGE") " (a string) as an SMS-message to " (tt "RECIPIENTS") ", which is either a string or a list of strings identifying the recipients. These can be either phone numbers or a group name.  If it's a group, " (tt "GROUP?") "  should be " (tt "#t") ", otherwise it should be " (tt "#f") " (the default).  Groups can be defined in the SMSMatrix user interface on their site.") (p "If " (tt "FALLBACK?") " is " (tt "#t") ", and one of the recipient numbers is a land line which can't receive SMS messages, the service will attempt to use a text-to-speech fallback for delivering your message, otherwise it will raise an error. " (tt "FALLBACK?") " defaults to " (tt "#f") ".") (p "If " (tt "ERROR?") " is " (tt "#t") " (the default) this procedure will raise an error on the first number that failed.  Be careful, however, this will currently just throw " (b "one") " error even if multiple phone numbers failed (there can also be different reasons for failure).  If it is " (tt "#f") ", you will just get a list of result alists which you will need to check for errors yourself.") (p "The result of this call is a list of alists.  Each alist represents one message sent, and includes the following keys:") (dl (dt (tt "pin")) (dd "The phone number of this record (a string)") (dt (tt "id")) (dd "The internal ID (an opaque hash code as a string) assigned to this message.  You can use this to request more information with " (tt "message-status") " or to look up the message in the CSV report.") (dt (tt "timestamp")) (dd "A number which is the UNIX timestamp at which time the message was delivered.") (dt (tt "statuscode")) (dd "A status code (number) indicating the delivery status of this record.") (dt (tt "statustxt")) (dd "A string containing the delivery status message.")))
(def (sig (procedure "(send-fax RECIPIENTS FILENAME [username: USERNAME] [password: PASSWORD] [group: GROUP?] [error-on-failure ERROR?])" (id send-fax))) (p "Send the file indicated by " (tt "FILENAME") " as a fax-message to " (tt "RECIPIENTS") ", which is either a string or a list of strings identifying the recipients.  These can be either phone numbers or a group name.  If it's a group, " (tt "GROUP?") "  should be " (tt "#t") ", otherwise it should be " (tt "#f") " (the default).  Groups can be defined in the SMSMatrix user interface on their site.") (p "The file types accepted by SMSMatrix are listed on their site.  At the time of writing this includes PDF, most common image formats and several office file formats.") (p "If " (tt "ERROR?") " is " (tt "#t") " (the default) this procedure will raise an error on the first number that failed.  Be careful, however, this will currently just throw " (b "one") " error even if multiple phone numbers failed (there can also be different reasons for failure).  If it is " (tt "#f") ", you will just get a list of result alists which you will need to check for errors yourself.") (p "The result of this call is a list of alists.  Each alist represents one message sent, and includes the following keys:") (dl (dt (tt "pin")) (dd "The phone number of this record (a string)") (dt (tt "id")) (dd "The internal ID (an opaque hash code as a string) assigned to this message.  You can use this to request more information with " (tt "message-status") " or to look up the message in the CSV report.") (dt (tt "timestamp")) (dd "A number which is the UNIX timestamp at which time the message was delivered.") (dt (tt "statuscode")) (dd "A status code (number) indicating the delivery status of this record.") (dt (tt "statustxt")) (dd "A string containing the delivery status message.")) (p (b "Warning") ": The fax API is undocumented save for one Perl example. It is also officially " (i "unsupported") " by SMSmatrix at the time of writing.  The procedure has been tested and returned the same error as the Perl example did, so it should most likely work, but nothing is guaranteed."))
(def (sig (procedure "(get-credits [username: USERNAME] [password: PASSWORD])" (id get-credits))) (p "Get the number of credits left on your account, as a number (possibly a flonum)."))
(def (sig (procedure "(message-status MESSAGE-ID [username: USERNAME] [password: PASSWORD])" (id message-status))) (p "Get the status of a message that was sent earlier.  The " (tt "MESSAGE-ID") " should be a string which " (tt "send-sms") " returned (ie, an opaque hash code).") (p "Returns 5 values:") (ol (li "The user's response, which is a number indicating which key on the phone the user pressed in response to a voice question, or " (tt "#f") " if it was a non-interactive call or the user didn't choose anything.") (li "The timestamp when the message was sent (a UNIX timestamp number)") (li "The timezone (a string which appears to always be " (tt "\"PDT\"") ")") (li "The message delivery status code (a number)") (li "The message delivery status message (a string)")))
(def (sig (procedure "(get-rate TYPE PHONE-NUMBER)" (id get-rate))) (p "Get the current rate (credits subtracted from your account when you would send a message of the given " (tt "TYPE") ") for " (tt "PHONE-NUMBER") " (a string).  " (tt "TYPE") " is a symbol indicating the type of message and can currently be one of " (tt "sms") " (SMS messages), " (tt "voice") " (prerecorded audio) or " (tt "tts") " (text-to-speech synthesis).") (p "This is the only API entry point which does not require a valid SMSMatrix account, hence there are no username/password arguments."))
(def (sig (procedure "(carrier-name PHONE-NUMBER [username: USERNAME] [password: PASSWORD])" (id carrier-name))) (p "Returns the name (a string) of the cellular carrier (one of those listed in the " (link "http://www.smsmatrix.com/?sms-carriers" "carrier table") " on the SMSMatrix website) for " (tt "PHONE-NUMBER") ". It might also return \"UNKNOWN\" if the phone number is valid but it doesn't know the carrier."))
(def (sig (procedure "(call-with-csv-report PROC [username: USERNAME] [password: PASSWORD] [limit: LIMIT] [incoming-only: INCOMING-ONLY?])" (id call-with-csv-report))) (p "Get a summary report of all transactions made on your account.") (p "The procedure " (tt "PROC") " is invoked with one argument: an input port from which the report can be read (in CSV format).") (p "If " (tt "LIMIT") " (a number) is given and nonzero, a maximum of that many records will be returned (defaults to zero, ie all messages).") (p "If " (tt "INCOMING-ONLY?") " is " (tt "#t") ", only incoming messages are shown (useful when using the \"virtual mobile phone number\" feature, whatever that may be...."))
