Messages

The Messages resource allows you to:

  • Send messages via POST
  • Collect a message’s status via GET
  • Mark a message as read via PUT

Sending a Message

To send a message you make a POST request to the Messages resource.

The POST url is: https://api.sendhub.com/v1/messages/?username=USERNAME&api_key=APIKEY

Where:

  • USERNAME - is your SendHub username.
  • APIKEY - is your api key which can be found on the settings page.

You’ll also need to pass Headers and Data.

Headers:

Content-Type: application/json

Data:

For example to send the message ‘Testing’ to the contact id ‘1111’ you would POST:

{
   "contacts": [
      1111
   ],
   "text": "Testing"
}

Note

You must use a valid contact id from your contacts, otherwise you will receive an error.

Therefore, to send a message through the API using cURL:

curl -H "Content-Type: application/json" -X POST --data '{"contacts" : [1111],"text" : "Testing"}' 'https://api.sendhub.com/v1/messages/?username=USERNAME&api_key=APIKEY'

If your message is accepted you’ll get a 201 Created status and a data response similar to this:

{
   "acknowledgment": "Message queued for sending.",
   "contacts": [
      1111
   ],
   "created_at": "2012-02-17T15:36:36.639968",
   "direction": "to",
   "groups": null,
   "id": "25",
   "resource_uri": "/api/v1/messages/25/",
   "scheduled_at": null,
   "sent": "2012-02-17T20:36:36.639968",
   "text": "Testing",
   "unread": null
}

Messages can be sent to multiple contacts and groups. Simply add additional contact and group ids to their respective lists, for example:

{
   "contacts": [
      1111,
      1112,
      1113
   ],
   "groups": [
      1000,
      1001
   ],
   "text": "Testing"
}

Messages can be sent directly to cell numbers. Please remember that unambiguous written consent is required before sending telemarkting calls or text messages. For example:

{
   "contacts": ["+16505551234"],
   "text": "Testing"
}

Sending a MMS Message

You can send MMS using the following payloads:

  • Send inline file with base64 encoding:

    {
  "contacts": [1111],
  "text": "Testing",
  "mms": {
     "filename": filename,
     "data": filedata
    }
}

  • Send MMS using public url:

    {
  "contacts": [1111],
  "text": "Testing",
  "mms": {
     "filename": PUBLIC_filename,
     "url": PUBLIC_url
    }
}

The MMS Messaging resource allows you to:

  • Either use inline file or public url per api call.
  • Only 1 file or 1 public url can be used per api call.
  • DownStream carrier file size restrictions still apply.

Scheduling a Message

You can post messages now for sending at some future date. To do this you must pass an additional variable in your post data: scheduled_at. This must be a timestamp, including timezone, consisting of exactly 24 characters, for example: 2011-02-17T20:29:40-0800.

An example request, would be:

{
   "contacts": [
      1111
   ],
   "text": "Testing Scheduling",
   "scheduled_at": "2011-02-17T14:30:00-0800"
}

If your message is accepted you’ll get a 201 Created status and a data response similar to this:

{
   "acknowledgment": "Message scheduled for delivery at 2011-02-17 22:30:00.",
   "contacts": [
      21399
   ],
   "created_at": "2012-02-17T13:06:58.859847",
   "direction": "to",
   "groups": null,
   "id": "30",
   "resource_uri": "/api/v1/messages/30/",
   "scheduled_at": "2011-02-17T22:30:00",
   "sent": null,
   "text": "Testing Scheduling",
   "unread": null
}

Note

The acknowledgment and scheduled_at timestamps are returned in UTC.

Available Fields:

Name Explanation
contacts The list of contacts ids you’d like to send to. Max 20.
groups The list of groups ids you’d like to send to. Max 3.
text The text of the message. Max 500 chars.
scheduled_at If the message was scheduled, the UTC time it was scheduled.
unread If the message is inbound, is it unread.
created_at The UTC time this message was created. Read Only.
sent The UTC time the message was sent. Null if not yet sent. Read only.
direction The direction of the message. To = outbound, from = inbound. Read only.
acknowledgment Information on your successful message sending request. Read only.
resource_uri The uri for this message. Read only.

Get Message Status

To get the status of a message you make a GET request to the Messages resource, with the message’s id:

https://api.sendhub.com/v1/messages/ID/?username=USERNAME&api_key=APIKEY

Where:

  • ID - is the message’s id. This can be obtained from the id or resource_uri field.

If your request is accepted you’ll get a 200 Ok status and a data response similar to this:

{
   "acknowledgment": "Message queued for sending.",
   "contacts": [
      1111
   ],
   "created_at": "2012-02-17T15:36:36.639968",
   "direction": "to",
   "groups": null,
   "id": "25",
   "resource_uri": "/api/v1/messages/25/",
   "scheduled_at": null,
   "sent": "2012-02-17T20:36:37.639968",
   "text": "Testing",
   "unread": null
}

Mark Message as Read

To mark a message as read you make a PUT request to the Messages resource, with the message’s id. You may only mark a message as read, you cannot mark a message as unread.

https://api.sendhub.com/v1/messages/ID/?username=USERNAME&api_key=APIKEY

You’ll also need to pass Headers and Data.

Headers:

Content-Type: application/json

Data:

Set unread to false.

{
   "unread": false
}