We're upgrading our API
On June 6th, 2019, Mailbox API 1.0 will be sunsetted, and at that time any apps using this legacy API will no longer work. Please use Mailbox API 2.0 instead.
This is an HTTPS-only API. Authentication is based on API Keys. Each API Key is associated with a Help Scout user. Results returned from various responses are based upon the role of the user to which the API key is tied.
The API Key is passed via HTTP Basic Authentication and goes in the username field. A dummy password, such as X, goes in the password field.
To try the API via curl on the command-line, the general form used would be:
For instance, if your API key is 60783dd23ef, you would execute:
All API requests are made to https://api.helpscout.net/and all requests are served over HTTPS. The current version is v1.
Each endpoint specifies the response format in the URL. However, the API will only support JSON at this time.
Maximum allowed request size is 100kB by default. There are two exception - 10MB for Create attachment endpoint and 256kB for Create conversation endpoint. The API will return response code 413 when the request size was exceeded.
Basic rate limiting
Requests are limited to 200 requests per minute per account. All API keys associated with the same account count against the minute rate limit. Response code 429 is returned when the throttle limit has been reached. A "Retry-After" header is returned indicating how many seconds to wait until retry. Applicable to all requests
Burst write rate limiting
Write requests (
POST, PUT, DELETE) have an additional limit of 12 requests every 5 seconds per account.
Read requests (
GET) are not subject to this limit
|X-RateLimit-Interval-*||Length of the rate limiting interval in seconds|
|X-RateLimit-Limit-*||Maximum number of requests per interval|
|X-RateLimit-Remaining-*||Number of requests remaining in the current rate limit interval|
Maximum URL Length
The maximum length for a URL is 4000 bytes.
The API returns one of three envelopes depending upon the request issued:
- Single Item Envelope
- Collections Envelope
- Error Envelope
Single Item Envelope
All dates/times are returned in ISO8601 format and in UTC timezone.
All dates/times are returned in ISO8601 format and in UTC timezone. Collections return a maximum of 50 records per page.