================
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 <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 <http://sendhub.com/settings>`_.

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"
}



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 <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 <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
    }