REST APIs

The REST APIs provide programmatic access to read and write Helpwise data. Create a new mailbox, read emails, fetch conversations, and more.

Overview

Below are some points that will help you get going with the REST APIs as quickly as possible.

  • Authenticating Requests
  • Rate Limiting
  • Pagination
  • Endpoints

Authenticating Requests

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.

Rate Limiting

HTTP Headers and Response Codes

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.

  • X-Rate-Limit-Limit:the rate limit ceiling for that given endpoint
  • X-Rate-Limit-Remaining:the number of requests left for the 1 hour window
  • X-Rate-Limit-Reset:the remaining window before the rate limit resets, in UTC epoch seconds

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.

Pagination

Parameters for Pagination

  • limit (optional): The number of records to be returned. Default is 50. Maximum value for limit is 100.
  • page (optional): Page number to be returned. Defaults to 1.
  • offset (optional): The number of records to be returned. Default is 0. If provided with page it overrides the page number

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.

Endpoints

We have endpoints for your mailboxes, emails, threads, users. We can also customize this data for your business or your own custom needs.

Mailboxes

This endpoint lets you create, list Mailboxes that you have on Helpwise. An example Mailbox object on Helpwise looks like this -

Sample Object


{
	"id":"204499"
	"displayName":"Helpwise Support"
	"email":"help@helpwise.io"
	"isVerified":true
	"forwardingAddress":"h.helpwise.io@email.helpwisemail.com"
}

Get Mailbox

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

Parameters Type Details
id (required) string Mailbox's id which is needed to be returned

Sample Request


              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"

Sample Response


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

Create Mailbox

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

Parameters Type Details
displayName string Mailbox's name that you want to display Like for support@yourdomain.com We can have Yourdomain Support
email string email address associated with the mailbox

Sample Request


            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"

Sample Response


      {
        "status":"success",
        "data":{
          {
            "id":"204499",
            "forwardingAddress":"h.helpwise.io@email.helpiwsemail.com",
            "email":"help@helpwise.io",
            "isVerified": true,
            "displayName": "Helpwise Support"
          }
        },
        "message": null
      }

List mailboxes

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

Parameters

Pagination parameters maybe provided

^the response data is paginated with a limit of 100 per page - know more about this in our pagination section

Sample Request


        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"

Sample Response


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

Conversations/Threads

This endpoint lets you create, list Conversations that you have on Helpwise. An example Thread object on Helpwise looks like this -

Sample Object


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

List Threads

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

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.
Pagination parameters maybe provided

^the response data is paginated with a limit of 100 per page - know more about this in our pagination section

Sample Request


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

Sample Response


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

users

This endpoint lets you fetch users. An example User object on Helpwise looks like this -

Sample Object


{
	"id": 204378,
	"firstname": "Christel",
	"lastname": "Rojo",
	"email": "crystel.rojo@example.com"
}

Me

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

Parameters

No Parameters are needed apart from Authentication Credentials

Sample Request


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

Sample Response


        {
          "status": "success",
          "data": {
            "id": 204378,
            "firstname": "Christel",
            "lastname": "Rojo",
            "email": "crystel.rojo@example.com"
          },
          "message": null
      }

Emails

This endpoint lets you list Emails that you have on Helpwise. An example Email object on Helpwise looks like this -

Sample Object


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

List Emails

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

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.
Pagination parameters maybe provided

^the response data is paginated with a limit of 100 per page - know more about this in our pagination section

Sample Request


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

Sample Response


	{
"status": "success",
"data": [
		{
			"id": 233604,
			"cc": {},
			"to": {
					"help@helpwise.io": "Helpwise Support"
				},
			"text": null,
			"html": "\n

                                

                                

                                

                            

                        

                        

                        

                        
prabhat@saaslabs.co
                        has invited you to edit the following document:
                    

                    

                

                









    
    



    
    
    



    
    
    



    
    
    











    
    
    



    
    
    



    
    
    







    Google Docs: Create and edit documents online. 
Google LLC, 1600 Amphitheatre Parkway, Mountain View, CA 94043,
    USA
 You have received this email because someone shared a document with you from Google Docs.		
    \"Logo



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

Send Email

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

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

Sample Request


				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"

Sample Response


{
"status":"success",
 "data":null,
"message":"Email sent"
}

WhatsApp

This endpoint lets you send, list Messages that you have on Helpwise WhatsApp inbox. An example WhatsApp message thread Helpwise looks like this -

Sample Object


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

Send WhatsApp Message

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

Parameters Type Details
mailbox_id (required) number mailbox id of your email
to (required) number your customer
message string message of whatsapp

Sample Request


				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"

Sample Response


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

SMS

This endpoint lets you send, list SMS Messages that you have on Helpwise SMS inbox. An example SMS message thread Helpwise looks like this -

Sample Object


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

Send SMS

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

Parameters Type Details
mailbox_id (required) number mailbox id of your email
to (required) number your customer
message string message of SMS

Sample Request


				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"

Sample Response


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

Contacts

This endpoint lets you create, list contacts that you have on Helpwise. An example Contact object on Helpwise looks like this -

Sample Object


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

Get Contact

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

Parameters Type Details
id (required) string Contacts's id

Sample Request


				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"

Sample Response


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

List Contacts

You can use this endpoint, to fetch all your contacts on Helpwise

POST : https://app.helpwise.io/dev-apis/contacts/list

Parameters

Pagination parameters maybe provided

^the response data is paginated with a limit of 100 per page - know more about this in our pagination section

Sample Request


				curl -X POST \
				-H "Accept: application/json" \
				-H "Authorization: {api key}:{api secret}" \
			  --url "https://app.helpwise.io/dev-apis/contacts/list"

Sample Response

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

Search Contacts

You can use this endpoint, to fetch all your contacts on Helpwise

POST : https://app.helpwise.io/dev-apis/contacts/search

Parameters

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

Sample Request


				curl -X POST \
				-H "Accept: application/json" \
                -H "Authorization: {api key}:{api secret}" \
                -d
			  --url "https://app.helpwise.io/dev-apis/contacts/search"

Sample Response

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

Create Contact

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

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
primaryEmail (required) string Contacts's primary Email is the email that you receive email from customer.
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
emails (optional) string Contact's emails addresses associated with your customer contacts. Pass an array of emails.

Sample Request


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",
	        "primaryEmail": "rishabh@saaslabs.co",
	        "secondaryEmails": [
		               "rishabh@helpwise.io"
		      ],
	        "phones": [
		      {
		          "phone": "8587805615",
		          "type": "1"
		      },
		      {
		          "phone": "7777878765",
		          "type": "2"
		       }
		       ]
		}'
--url "https://app.helpwise.io/dev-apis/contacts/create"

Sample Response


{
	"status":"success",
	"data":null,
	"message":"Contact saved successfully"
}