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",
"type": "message-in"
"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",
"type": "message-out"
"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",
"type": "message-out"
"unread": null
}
]
}
You can distinguish between inbound and outbound messages via the ‘unread’ value:
"unread": null = OUTBOUND
"unread": true = INBOUND
"unread": false = INBOUND