The REST APIs provide programmatic access to read and write Helpwise data. Create a new mailbox, read emails, fetch conversations, and more.
Below are some points that will help you get going with the REST APIs as quickly as possible.
To make a REST API call, you must include request headers including the Authorization header with your API Key and API Key.
To get an API Key, you can visit helpwise's API credentials Page and click on Generate Credentials Page. Now You can copy your API Key and Secret pair from that page and use it to call our APIs.
Request Header | Description |
Authorization | When you request an endpoint, send the value as the HTTP basic authentication credentials by using your api key and api secret.For example: Authorization: api key:api secret.If you use cURL, specify -u “api key:api secret”.Required. |
Accept | Set to application/json. Required. |
Use the HTTP headers in order to understand where the application is at for a given rate limit, on the method that was just utilized.
Note that the HTTP headers are contextual. When using api key and api secret, they indicate the rate limit for the application context.
When an application exceeds the rate limit for a given API endpoint, the API will return a HTTP 429 “Too Many Requests” response code, along with a detailed error message in response body.
To better predict the rate limits available, consider periodically using GET application / rate_limit_status.
When an application exceeds the limit i.e. greater than 100 for a given API endpoint, the API will return a HTTP 400 “Bad Request” response code, along with a detailed error message in response body.
Parameters needs to be provided in POST request in JSON.
We have endpoints for your mailboxes, emails, threads, users. We can also customize this data for your business or your own custom needs.
This endpoint lets you create, list Mailboxes that you have on Helpwise. An example Mailbox object on Helpwise looks like this -
{
"id":"204499"
"displayName":"Helpwise Support"
"email":"help@helpwise.io"
"isVerified":true
"forwardingAddress":"h.helpwise.io@email.helpwisemail.com"
}
You can use this endpoint, to get a single Mailbox on Helpwise using your api key and api secret.
POST : https://app.helpwise.io/dev-apis/mailboxes/get
Parameters | Type | Details |
id (required) | string | Mailbox's id which is needed to be returned |
curl -X POST \
-H "Accept: application/json" \
-H "Authorization: {api key}:{api secret}" \
--data '{
"id":"204420"
}' \
--url "https://app.helpwise.io/dev-apis/mailboxes/get"
{
"status": "success",
"data": {
"id": "204499",
"forwardingAddress": "h.helpwise.io@email.helpiwsemail.com",
"email": "help@helpwise.io",
"isVerified": false,
"displayName": "Helpwise Support",
"stats": {
"mine": 28,
"unassigned": 395,
"assigned": 50,
"drafts": 3,
"inbox": 194
},
"outboundSettings": {
"active": "0",
"settings": {
"smtp": {
"type": "2",
"settings": {
"servername": "smtp.helpwise.io",
"username": "someusername",
"port": "465",
"security": "SSL",
"password": "some password"
}
},
"google": {
"type": "1",
"settings": {
"isConnected": true,
"email": "help@helpwise.io"
}
},
"microsoft": {
"type": "3",
"settings": {
"isConnected": false,
"email": null
}
},
"helpwise": {
"type": "0",
"settings": {
"status": "inactive",
"dns": {
"records": [
{
"host": "204499.helpwise.io",
"type": "CNAME",
"value": "email.helpwisemail.com",
"isValid": false
},
{
"host": "s1._domainkey.helpwise.io",
"type": "CNAME",
"value": "s1._domainkey.helpwisemail.com",
"isValid": false
},
{
"host": "s2._domainkey.helpwise.io",
"type": "CNAME",
"value": "s2._domainkey.helpwisemail.com",
"isValid": false
}
],
"isValid": false
}
}
}
}
}
},
"message": null
}
You can use this endpoint, to create mailbox on Helpwise using your api key and api secret.
https://app.helpwise.io/dev-apis/mailboxes/create
Parameters | Type | Details |
displayName | string | Mailbox's name that you want to display Like for support@yourdomain.com We can have Yourdomain Support |
string | email address associated with the mailbox |
curl -X POST \
-H "Accept: application/json" \
-H "Authorization: {api key}:{api secret}" \
--data '{
"email":"help@helpwise.io",
"displayName": "Helpwise Support"
}' \
--url "https://app.helpwise.io/dev-apis/mailboxes/create"
{
"status":"success",
"data":{
{
"id":"204499",
"forwardingAddress":"h.helpwise.io@email.helpiwsemail.com",
"email":"help@helpwise.io",
"isVerified": true,
"displayName": "Helpwise Support"
}
},
"message": null
}
You can use this endpoint, to list your mailboxes on Helpwise using your api key and api secret. This api returns a paginated response that you can use to go through your mailboxes.
POST : https://app.helpwise.io/dev-apis/mailboxes/list
^the response data is paginated with a limit of 100 per page - know more about this in our pagination section
curl -X POST \
-H "Accept: application/json" \
-H "Authorization: {api key}:{api secret}" \
--data '{
"page":"1",
"limit":"20"
}' \
--url "https://app.helpwise.io/dev-apis/mailboxes/list"
{
"status":"success",
"data":[
{
"id":"204499",
"forwardingAddress":"h.helpwise.io@email.helpiwsemail.com",
"email":"help@helpwise.io",
"isVerified": true,
"displayName": "Helpwise Support"
},
{
"id":"204322",
"forwardingAddress":"s.helpwise.io@email.helpiwsemail.com",
"email":"s@helpwise.io",
"isVerified": true,
"displayName": "Helpwise Sales"
}
],
"message": null
}
This endpoint lets you create, list Conversations that you have on Helpwise. An example Thread object on Helpwise looks like this -
{
"id": 229671,
"totalEmailCount": 1,
"tags": [],
"isRead": true,
"latestEmail": {
"id": 232907,
"snippet": "How Are you?",
"subject": "Hi, How are you. Regards, Crystel Rojo",
"to": {
"help@helpwise.io": "Helpwise Support"
},
"from": {
"crystel.rojo1212@gmail.com": "Crystel Rojo"
},
"hasAttachment": false,
"date": "2019-11-19T03:31:57+0000",
"inReplyTo": null,
"snoozedAt": "2019-11-19T04:48:48+0000",
"attachments": [],
"labelID": 0,
"snoozedTill": "2019-11-19T06:42:00+0000"
},
"hasDraft": false
}
You can use this endpoint, to list your conversations on Helpwise using your api key and api secret. This api returns a paginated response that you can use to go through your mailboxes.
POST : https://app.helpwise.io/dev-apis/threads/list
Parameters | Type | Details |
mailboxId (required) | number | id of the mailbox for which you want to fetch the conversations. |
labelId (optional) | number | The folder from which conversations need to be fetched. Defaults to 0(inbox). |
labelId (optional) | number | The folder from which conversations need to be fetched. Defaults to 0(inbox). |
tagId (optional) | number | Provide a tagId if you want to list conversations for a particular tag. |
squery (optional) | number | Search query to perform a text based search on emails to list the search results. |
^the response data is paginated with a limit of 100 per page - know more about this in our pagination section
curl -X POST \
https://app.helpwise.io/dev-apis/threads/list \
-H 'Accept: application/json' \
-H 'Authorization: {api key}:{api secret}' \
-d '{
"limit":5,
"page":1,
"mailboxId":"204420"
}'
{
"status": "success",
"data": [
{
"id": 252409,
"totalEmailCount": 1,
"tags": [],
"isRead": true,
"latestEmail": {
"id": 233604,
"snippet": "I've shared an item with you:\r\n\r\nTerms of Service\r\nhttps://docs.google.com/document/d/1tnf7P-YTvwyuZrN7iE029F0DaXHwkRH3CXYDCkSq-Uo/edit?usp=sharing&ts=5dd3c906\r\n\r\nIt's not an attachment -- it's st",
"subject": "Terms of Service - Invitation to edit",
"to": {
"vibhor@saaslabs.co": ""
},
"from": {
"drive-shares-noreply@google.com": "Prabhat Mishra (via Google Docs)"
},
"hasAttachment": false,
"date": "2019-11-19T10:50:49+0000",
"inReplyTo": null,
"snoozedAt": null,
"attachments": [],
"labelID": 0,
"snoozedTill": null
},
"hasDraft": false
},
{
"id": 229671,
"totalEmailCount": 1,
"tags": [],
"isRead": true,
"latestEmail": {
"id": 232907,
"snippet": "SaaS Labs Inc:\r\n\r\nHere’s the latest activity across everything since 9am on Monday, November 18\r\n\r\n\r\n## SaaS Labs Inc HQ ##\r\n----------------------------------\r\n- 1 message was posted to the messag",
"subject": "Basecamp (SaaS Labs Inc): Here’s the latest activity",
"to": {
"vibhor@saaslabs.co": ""
},
"from": {
"notifications@3.basecamp.com": "Basecamp (SaaS Labs Inc)"
},
"hasAttachment": false,
"date": "2019-11-19T03:31:57+0000",
"inReplyTo": null,
"snoozedAt": "2019-11-19T04:48:48+0000",
"attachments": [],
"labelID": 0,
"snoozedTill": "2019-11-19T06:42:00+0000"
},
"hasDraft": false
}
],
"message": null
}
This endpoint lets you fetch users. An example User object on Helpwise looks like this -
{
"id": 204378,
"firstname": "Christel",
"lastname": "Rojo",
"email": "crystel.rojo@example.com"
}
This is a special endpoint. You can use this endpoint, to get the authenticated user on Helpwise using your api key and api secret.
POST : https://app.helpwise.io/dev-apis/users/me
curl -X POST \
https://app.helpwise.io/dev-apis/users/me \
-H 'Accept: application/json' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Authorization: {api key}:{api secret}'
{
"status": "success",
"data": {
"id": 204378,
"firstname": "Christel",
"lastname": "Rojo",
"email": "crystel.rojo@example.com"
},
"message": null
}
This endpoint lets you list Emails that you have on Helpwise. An example Email object on Helpwise looks like this -
{
"data":{
"id":272645,
"at":"2020-06-08T14:15:45+0000",
"body":"\nHi Adam, please schedule a demo with this customer.<\/p><\/body><\/html>\n",
"by":{
"id":205571,
"firstname":"Rishabh",
"lastname":"Rawat",
"email":"rishabh@helpwise.io",
"avatarTag":"
",
"avatarUrl":"https:\/\/cdn.helpwise.io\/profile\/143d4b49e96f8725d317.1587616833.ae9baa2c550a4fd8c7cf"
},
"attachments":[]
}
},
You can use this endpoint, to add your notes on Helpwise using your api key and api secret.
POST : https://app.helpwise.io/dev-apis/notes/add
Parameters | Type | Details |
mailbox_id (required) | number | mailbox id of your email |
thread_id (required) | number | thread_id of your mailbox |
message | string | body of the note |
curl --location --request POST 'https://app.helpwise.io/dev-apis/notes/add' \
--header 'Authorization: your_api_key:your_api_secret' \
--header 'Content-Type: application/json' \
--data-raw '{
"mailbox_id":205234,
"thread_id":1910985,
"message":"Hi Rishabh! How may I help you?"
}'
{
"status": "success",
"data": {
"comment": {
"id": 272645
}
},
"message": "Comment Added"
}
This endpoint lets you list Notes that you have on Helpwise. An example Notes object on Helpwise looks like this -
{
"id": 233604,
"cc": {},
"to": {
"help@helpwise.io": "Helpwise Support"
},
"text": null,
"html": "You are invited to edit the google docs",
"subject": "Terms of Service - Invitation to edit",
"isSpam": false,
"from": {
"drive-shares-noreply@google.com": "Prabhat Mishra (via Google Docs)"
},
"date": "2019-11-19T10:50:49+0000",
"sentBy": null,
"attachments": [],
"labelId": 0,
"inReplyTo": 204376,
"replyAll": false,
"forwardOf": null,
"readStats": {
"readAt": [],
"distinctReadCount": null
},
"bcc": {}
}
You can use this endpoint, to list your Emails in a particular Conversation on Helpwise using your api key and api secret. This api returns a paginated response that you can use to go through your mailboxes.
POST : https://app.helpwise.io/dev-apis/emails/list
Parameters | Type | Details |
mailboxId (required) | number | id of the mailbox for which you want to fetch the conversations. |
threadId (required) | number | id of the thread for which you want to fetch the conversations. |
^the response data is paginated with a limit of 100 per page - know more about this in our pagination section
curl -X POST \
https://app.helpwise.io/dev-apis/emails/list \
-H 'Accept: application/json' \
-H 'Authorization: {api key}:{api secret}' \
-d '{
"limit":2,
"page":1,
"mailboxId":"204420",
"threadId":"252409"
}'
{
"status": "success",
"data": [
{
"id": 233604,
"cc": {},
"to": {
"help@helpwise.io": "Helpwise Support"
},
"text": null,
"html": '\n
',
"subject": "Terms of Service - Invitation to edit",
"isSpam": false,
"from": {
"drive-shares-noreply@google.com": "Prabhat Mishra (via Google Docs)"
},
"date": "2019-11-19T10:50:49+0000",
"sentBy": null,
"attachments": [],
"labelId": 0,
"inReplyTo": 204376,
"replyAll": false,
"forwardOf": null,
"readStats": {
"readAt": [],
"distinctReadCount": null
},
"bcc": {}
}
],
"message": null
}
You can use this endpoint, to send your email to your customer on Helpwise using your api key and api secret.
POST : https://app.helpwise.io/dev-apis/emails/send_mail
Parameters | Type | Details |
mailbox_id (required) | number | mailbox id of your email |
to (required) | string | to email addresses of your customers(comma separated for multiple) |
cc | string | cc email addresses of your customers(comma separated for multiple) |
subject (required) | string | Subject of the email |
email body (required) | string | Body of the email |
curl -X POST \
-H "Accept: application/json" \
-H "Authorization: {api key}:{api secret}" \
--data '{
"mailbox_id": 204811,
"to":"rishabh@saaslabs.co,rishabh@helpwise.io",
"cc":"help@helpwise.io",
"subject":"Balance your workload from Helpwise",
"body":""
}' \
--url "https://app.helpwise.io/dev-apis/emails/send_mail"
{
"status":"success",
"data":null,
"message":"Email sent"
}
This endpoint lets you send, list Messages that you have on Helpwise WhatsApp inbox. An example WhatsApp message thread Helpwise looks like this -
{
"status":"success",
"data":{
"threads":[
{
"id":"918587805615",
"totalSmsCount":1,
"isRead":true,
"last_message":"hello Rishabh, How may I help you?",
"date":"2020-05-27T09:54:18+0000",
"humanFriendlyDate":"27 May",
"client_number":"918587805615",
"your_number":"18304200005",
"labelID":1,
"tags":[
{
"id":205223,
"name":"WhatsApp",
"color":"rgb(0, 255, 65)"
}
]
},
"message":null
}
You can use this endpoint, to send your WhatsApp message to your customer on Helpwise using your api key and api secret.
POST : https://app.helpwise.io/dev-apis/whatsapp/send
Parameters | Type | Details |
mailbox_id (required) | number | mailbox id of your email |
to (required) | number | your customer |
message | string | message of whatsapp |
curl -X POST \
-H "Accept: application/json" \
-H "Authorization: {api key}:{api secret}" \
--data '{
"mailbox_id": 204811,
"to":'+918587805615',
"message":"Hello Rishabh, How are you?"
}' \
--url "https://app.helpwise.io/dev-apis/whatsapp/send"
{
"status": "success",
"data": {
"client_number": "+918587805615",
"your_number": "+18304200005",
"message_time": "2020-05-27T08:48:14+0000",
"direction": "outbound-api",
"delivery_status": "queued",
"segments": "1",
"body": "hello Rishabh",
"sent_by": {
"id": 205571,
"firstname": "Helpwise",
"lastname": "Team",
"email": "help@helpwise.io"
},
"attachment": {},
"id": 206658
},
"message": "Message sent"
}
This endpoint lets you send, list SMS Messages that you have on Helpwise SMS inbox. An example SMS message thread Helpwise looks like this -
{
"status":"success",
"data":{
"threads":[
{
"id":"918587805615",
"totalSmsCount":1,
"isRead":true,
"last_message":"hello Rishabh, How may I help you?",
"date":"2020-05-27T09:54:18+0000",
"humanFriendlyDate":"27 May",
"client_number":"918587805615",
"your_number":"18304200005",
"labelID":1,
"tags":[
{
"id":205223,
"name":"SMS",
"color":"rgb(0, 255, 65)"
}
]
},
"message":null
}
You can use this endpoint, to send your SMS message to your customer on Helpwise using your api key and api secret.
POST : https://app.helpwise.io/dev-apis/sms/send
Parameters | Type | Details |
mailbox_id (required) | number | mailbox id of your email |
to (required) | number | your customer |
message | string | message of SMS |
curl -X POST \
-H "Accept: application/json" \
-H "Authorization: {api key}:{api secret}" \
--data '{
"mailbox_id": 204811,
"to":'+918587805615',
"message":"Hello Rishabh, How are you?"
}' \
--url "https://app.helpwise.io/dev-apis/sms/send"
{
"status": "success",
"data": {
"client_number": "+918587805615",
"your_number": "+18304200005",
"message_time": "2020-05-27T08:48:14+0000",
"direction": "outbound-api",
"delivery_status": "queued",
"segments": "1",
"body": "Hello Rishabh, How are you?",
"sent_by": {
"id": 205571,
"firstname": "Helpwise",
"lastname": "Team",
"email": "help@helpwise.io"
},
"attachment": [],
"id": 206658
},
"message": "SMS sent"
}
This endpoint lets you create, list contacts that you have on Helpwise. An example Contact object on Helpwise looks like this -
{
"firstname": "Basecamp",
"lastname": "Inc",
"primaryEmail": "notifications@3.basecamp.com",
"secondaryEmails": [
"basecamp@gmail.com",
"basecamp@outlook.com"
],
"phones": [
{
"phoneNo": "919200000016",
"type": "9"
},
{
"phoneNo": "819090909090",
"type": "8"
}
],
"id": 204811,
"companyName": "Basecamp",
"jobTitle": "Software Developer"
}
You can use this endpoint, to get your specific contact on Helpwise using your api key and api secret.
POST : https://app.helpwise.io/dev-apis/contacts/get
Parameters | Type | Details |
id (required) | string | Contacts's id |
curl -X POST \
-H "Accept: application/json" \
-H "Authorization: {api key}:{api secret}" \
--data '{
"id": 204811,
}' \
--url "https://app.helpwise.io/dev-apis/contacts/get"
{
"firstname": "Basecamp",
"lastname": "Inc",
"primaryEmail": "notifications@3.basecamp.com",
"secondaryEmails": [
"basecamp@gmail.com",
"basecamp@outlook.com"
],
"phones": [
{
"phoneNo": "919200000016",
"type": "9"
},
{
"phoneNo": "819090909090",
"type": "8"
}
],
"id": 204811,
"companyName": "Basecamp",
"jobTitle": "Software Developer"
}
You can use this endpoint, to fetch all your contacts on Helpwise
POST : https://app.helpwise.io/dev-apis/contacts/list
^the response data is paginated with a limit of 100 per page - know more about this in our pagination section
curl -X POST \
-H "Accept: application/json" \
-H "Authorization: {api key}:{api secret}" \
--url "https://app.helpwise.io/dev-apis/contacts/list"
{
"status": "success",
"data": [
{
"id": 205361,
"firstname": "Intercom",
"lastname": "",
"primaryEmail": "noreply@intercom.io",
"secondaryEmails": [],
"phones": []
},
{
"id": 205072,
"firstname": "",
"lastname": "",
"primaryEmail": "rishabh@helpwise.io",
"secondaryEmails": [],
"phones": []
}
],
"message": null
}
You can use this endpoint, to fetch all your contacts on Helpwise
POST : https://app.helpwise.io/dev-apis/contacts/search
Parameters | Type | Details |
name (optional)^^ | string | Contacts's first name that you want to save |
phone (optional)^^ | string | Phone No to look for |
email (optional)^^ | string | Email to look for |
^the response data is paginated with a limit of 100 per page - know more about this in our pagination section
^^One of the fields name,phone or email is required
curl -X POST \
-H "Accept: application/json" \
-H "Authorization: {api key}:{api secret}" \
-d
--url "https://app.helpwise.io/dev-apis/contacts/search"
{
"status": "success",
"data": [
{
"id": 205361,
"firstname": "Intercom",
"lastname": "",
"primaryEmail": "noreply@intercom.io",
"secondaryEmails": [],
"phones": []
},
{
"id": 205072,
"firstname": "",
"lastname": "",
"primaryEmail": "rishabh@helpwise.io",
"secondaryEmails": [],
"phones": []
}
],
"message": null
}
You can use this endpoint, to create contacts on Helpwise using your api key and api secret.
https://app.helpwise.io/dev-apis/contacts/create
Parameters | Type | Details |
firstname (required) | string | Contacts's first name that you want to save |
lastname (optional) | string | Contacts's last name that you want to save |
emails (required) | array | Contact's emails addresses associated with your customer contacts. Pass an array of emails. |
phones (optional) | Object | Contacts's phones no. Type define the which type of phone no you save. Pass an array of phones no. |
companyName (optional) | string | Contacts's company name where he/she works |
Job title (optional) | string | Contacts's job title |
curl -X POST \
-H "Accept: application/json" \
-H "Authorization: {api key}:{api secret}" \
--data '{
"firstname": "Rishabh",
"lastname": "Rawat",
"companyName": "Saas Labs",
"jobTitle": "Full Stack Web Developer",
"emails": ["rishabh@saaslabs.co","rishabh@helpwise.io"],
"phones": [
{
"phone": "8587805615",
"type": "1"
},
{
"phone": "7777878765",
"type": "2"
}
]
}'
--url "https://app.helpwise.io/dev-apis/contacts/create"
{
"status":"success",
"data":null,
"message":"Contact saved successfully"
}