Function: SendMessageDirect

Sends a short message to either a phone number (via SMS) or via email. Both types of request are queued on our server and we deliver it on your behalf, meaning you do not need to set up and maintain you own email server, etc. This service is used by the Excel Web Add-In to support message delivery directly from workbooks based on either static or dynamic messages (e.g. derived from Excel formulas). Please note that message count restrictions may be in place as we gauge interest in this feature: you can check on any current limit by visiting our Rates page.

Usage

  • HTTP GET
    https://www.xs.codexframework.com/api/SendMessageDirect?cc=CLIENT_CODE
    &body=ENCODED_BODY
    &sendto=ENCODED_SEND_TO
    &defprov=DEFAULT_PROVIDER
    &subject=ENCODED_SUBJECT
    &from=ENCODED_FROM

Parameters

  • CLIENT_CODE
    This is an authorization token that identifies your xSkrape.com account to which any credit charges will be applied. You can locate this code by logging into your xSkrape.com account, under My Account - Queries. (Remember: it's your duty to secure your client code against unauthorized use.) Required.
  • ENCODED_BODY
    The message text you wish to send. Credit charges based on message size. The text needs to be URL encoded. Required.
  • ENCODED_SEND_TO
    A list of email addresses or phone numbers. If there are multiple, they should be separated with a semi-colon (;). If dealing in phone numbers, the default cell provider is assumed for all numbers. If cell providers vary by phone number, the provider for a given phone number can be specified after a pipe (|) delimiter. For example, "7075551234|verizon;7075556666|att" has the first number relating to Verizon, the second relating to AT&T. Required.
  • DEFAULT_PROVIDER
    Either "email" or a specific cell provider which becomes the default for all phone numbers listed under ENCODED_SEND_TO. Available provider codes are listed here. Required.
  • ENCODED_SUBJECT
    The subject for the email or SMS message. Required. The text needs to be URL encoded.
  • ENCODED_FROM
    The "sent from" email address for the message. Required. (Must be a valid email address.)

Return Value(s)

  • Returns JSON in all cases (success and failure).
  • Format: { "Success":true|false, "Message":"message", "Source":"source" }
  • Success: Indicates overall success or failure status of the request.
  • Message: In the case of failure, provides an error message. (On success, provides status.)
  • Source: In the case of failure, identifies the origin of the message.

Remarks

This API allows you to send messages to distribution lists. When sending via SMS, you do need to be aware of the cell carrier involved, or you can use the "email" option and find the appropriate email that works with your cell carrier of interest to turn the email into an SMS message. We currently limit you to a maximum number of messages per day (limits are published on xskrape.com under "rates"). We additionally prevent the sending of "duplicate messages" at your discretion. If you send a duplicate, the return message may say "The same message has been delievered within the last x minute(s) as set on user profile - will not be resent." You can control the interval as noted by updating your user profile on xSkrape.com.

Examples

  • cURL

    1. Send multiple messages with a single request (combine SMS and email)

    In this example we use the "curl" command line tool to illustate calling the WebGetTable API.

    curl --data-urlencode "cc=5e.....2e" --data-urlencode "body=My sample message." --data-urlencode "sendto=70......43|verizon;in..@...com" --data-urlencode "defprov=email" --data-urlencode "subject=Test Subject" --data-urlencode "from=ad..@...com" -G "https://www.xs.codexframework.com/api/SendMessageDirect"

    Results:

    {"Success":true, "Message":"Queued 2 messages to send. They will be sent shortly. ", "Source":"Result"}

    Of note, we've omitted most of our client token: you would substitute your own, as found when you log into your xSkrape.com account. Various parameters are encoded as part of our request to SendMessageDirect, and the result shows a successful completion (Success = true).

  • jQuery

    2. Send multiple messages with a single request (combine SMS and email)

    This is effectively the same example as above, except implemented using a JQuery get call.

    <input type="text" id="result"/>
    <script type="text/javascript">
    var requestUrl = "https://www.xs.codexframework.com/api/SendMessageDirect";

    var parm = {
        cc: "5e.....2e",
        body: "Hello, world!",
        sendto: "70......43|verizon;in..@....com",
        defprov: "email",
        subject: "Test Subject",
        from: "ad..@....com"
    };

    $.get(requestUrl, parm).done(function (data) {
        $("#result").val(data.Message);
    });
    </script>

Related