================ Getting Started ================ The SendHub API is free and simple. All you need to get started is a `SendHub `_ account. Once you've registered, go to the settings page: http://sendhub.com/settings and collect your API key. This key plus your SendHub username will be the credentials you use to access the SendHub API. 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' **Response:** If your messages 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-17T20:36:35.129968", "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 } Accessing Contacts =================== In order to send a message, you'll need at least 1 valid contact id. You can view the contact database for your account through the `Contacts `_ resource. To view all your contacts, make a **GET** request to: `https://api.sendhub.com/v1/contacts/?username=USERNAME&api_key=APIKEY `_ **Response:** If your request is valid, you'll get a **200 Ok** status and a data response similar to this: :: {    "meta": {       "limit": 20,       "next": null,       "offset": 0,       "previous": null,       "total_count": 1    },    "objects": [       {          "blocked": false,          "groups": [],          "id": "1111",          "name": "John Doe",          "number": "+15555555555",          "resource_uri": "/api/v1/contacts/1111/"       }    ] } As a new user you should have 1 contact, yourself, already added for you in the database. As you can see in the example above, contacts are listed in the **objects** field and each contact has an **id** field. This id matches up with id used for the `'Sending a Message' example `_ in the contacts field. Accessing Groups ================= To view the groups on your account, you make a **GET** request through the `Groups `_ resource: `https://api.sendhub.com/v1/groups/?username=USERNAME&api_key=APIKEY `_ If your request is valid, you'll get a **200 Ok** status and a data response similar to this: :: {    "meta": {       "limit": 20,       "next": null,       "offset": 0,       "previous": null,       "total_count": 2    },    "objects": [       {          "id": "1000",          "name": "demo",          "resource_uri": "/api/v1/groups/1000/",          "size": 1,          "slug": "demo",          "text_to_subscribe": true       },       {          "id": "1001",          "name": "customers",          "resource_uri": "/api/v1/groups/1001/",          "size": 0,          "slug": "customers",          "text_to_subscribe": false       }    ] } Send a message to a group is very similar to sending to a contact. For example, to send a message to these 2 groups and a contact, perform a **POST** request, as in the `'Sending a Message' example `_ above, with the following **data**: :: {    "contacts": [       1111    ],    "groups": [       1000,       1001    ],    "text": "Testing multiple recipients" } Viewing the Inbox ================= Once you have sent a message it will be available, along with other out and inbound messages, via the `Inbox `_ resource. `https://api.sendhub.com/v1/inbox/?username=USERNAME&api_key=APIKEY `_ If your request is valid, you'll get a **200 Ok** status and a data response similar to this: :: {    "meta": {       "limit": 20,       "next": null,       "offset": 0,       "previous": null,       "total_count": 2    },    "objects": [     {          "contacts": [             {                "id": 1111,                "name": "John Doe"             }          ],          "groups": [             {                "id": 1000,                "name": "demo"             } {                "id": 1001,                "name": "customers"             }          ],          "resource_uri": "/api/v1/threads/26/",          "sent": "2012-02-17T21:39:22.978898",          "text": "Testing multiple recipients",          "unread": null     }   {          "contacts": [             {                "id": 1111,                "name": "John Doe"             }          ],          "groups": [],          "resource_uri": "/api/v1/threads/25/",          "sent": "2012-02-17T20:36:36.639968",          "text": "Testing",          "unread": null       }    ] } Each item in the objects list represents a conversation thread and includes the text of most recent message for that conversation. If a conversation has 'unread' set to true, it contains unread messages. The entire conversation thread can be accessed via the url provided in 'resource_uri'. Viewing Threads ================= Complete views of conversations is available via the `Threads `_ resource. `https://api.sendhub.com/v1/threads/THREADID/?username=USERNAME&api_key=APIKEY `_ Where THREADID (and the full path) is obtained from the 'resource_uri' value in the `Inbox `_ response. If your request is valid, you'll get a **200 Ok** status and a data response similar to this: :: {    "meta": {       "limit": 10,       "next": null,       "offset": 0,       "previous": null,       "total_count": 3    },    "objects": [       { "contacts": [             {                "id": 1111,                "name": "John Doe"             }          ],          "groups": null,          "id": "23",          "resource_uri": "/api/v1/messages/23/",          "scheduled_at": null,          "sent": "2012-02-17T20:19:16.192747",          "text": "Inbound message test",          "unread": false       },       {          "contacts": [             {                "id": 1111,                "name": "John Doe"             }          ],          "groups": null,          "id": "24",          "resource_uri": "/api/v1/messages/24/",          "scheduled_at": null,          "sent": "2012-02-17T20:29:22.978898",          "text": "Outbound test message",          "unread": null       },       {          "contacts": [             {                "id": 1111,                "name": "John Doe"             }          ],          "groups": null,          "id": "25",          "resource_uri": "/api/v1/messages/25/",          "scheduled_at": null,          "sent": "2012-02-17T20:36:36.639968",          "text": "Testing",          "unread": null       }    ] } You can distinguish between inbound and outbound messages via the 'unread' value: :: "unread": null = OUTBOUND "unread": true = INBOUND "unread": false = INBOUND