Email Report
Our Email report measures efficiency working with email conversations. You’ll be able to keep track of how your team is performing in terms of time spent addressing and responding to conversations. Check out Reports: Email for the scoop on how these metrics are calculated.
Note: The reporting endpoints are only available to Plus and Pro plans.
Request
GET /v2/reports/email HTTP/1.1
Authorization: Bearer oauth_token
URL Parameters
| Parameter | Type | Examples | Description |
|---|---|---|---|
start |
date |
start=2019-05-02T12:00:00Z |
Start of the interval |
end |
date |
end=2019-06-02T12:00:00Z |
End of the interval |
previousStart |
date |
previousStart=2019-04-02T12:00:00Z |
Start of the previous interval |
previousEnd |
date |
previousEnd=2019-05-02T12:00:00Z |
End of the previous interval |
mailboxes |
number |
mailboxes=123mailboxes=123,567 |
List of comma separated ids to filter on mailboxes |
tags |
number |
tags=99787tags=5666,99787 |
List of comma separated ids to filter on tags |
folders |
number |
folders=991folders=991,992 |
List of comma separated folder ids to filter on folders |
officeHours |
boolean |
officeHours=true |
Whether to take office hours into consideration in the report (defaults to false); office hours must be enabled if true is passed, otherwise the default of false will be used |
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
{
"filterTags" : [ {
"id" : 100,
"name" : "vip"
} ],
"current" : {
"startDate" : "2015-01-01T00:00:00Z",
"endDate" : "2015-01-31T23:59:59Z",
"volume" : {
"emailConversations" : 8,
"emailsCreated" : 5,
"repliesSent" : 24,
"messagesReceived" : 40
},
"resolutions" : {
"resolved" : 10,
"resolvedOnFirstReply" : 1,
"percentResolvedOnFirstReply" : 0.1,
"resolutionTime" : 20.5,
"repliesToResolve" : 17.0,
"handleTime" : 129,
"closed" : 20
},
"responses" : {
"responseTime" : 1023,
"firstResponseTime" : 500
}
},
"previous" : {
"startDate" : "2015-01-01T00:00:00Z",
"endDate" : "2015-01-31T23:59:59Z",
"volume" : {
"emailConversations" : 7,
"emailsCreated" : 4,
"repliesSent" : 14,
"messagesReceived" : 20
},
"resolutions" : {
"resolved" : 11,
"resolvedOnFirstReply" : 140,
"percentResolvedOnFirstReply" : 0.2,
"resolutionTime" : 20.4,
"repliesToResolve" : 7.0,
"handleTime" : 110,
"closed" : 19
},
"responses" : {
"responseTime" : 1021,
"firstResponseTime" : 300
}
},
"deltas" : {
"volume" : {
"emailConversations" : 639.2,
"emailsCreated" : 865.0602,
"repliesSent" : 402.4922,
"messagesReceived" : 245.098
},
"resolutions" : {
"resolved" : -15.0,
"resolvedOnFirstReply" : 3.8235,
"resolutionTime" : -99.3841,
"repliesToResolve" : 45.6583,
"handleTime" : -45.5696,
"closed" : -40.678
},
"responses" : {
"responseTime" : -99.0912,
"firstResponseTime" : -99.085
}
},
"responseTime" : {
"count" : 1,
"previousCount" : 14,
"ranges" : [ {
"id" : 10,
"count" : 1,
"percent" : 100.0,
"previousCount" : 12,
"previousPercent" : 85
} ]
},
"handleTime" : {
"count" : 1,
"previousCount" : 14,
"ranges" : [ {
"id" : 1,
"count" : 1,
"percent" : 100.0,
"previousCount" : 14,
"previousPercent" : 100
} ]
},
"firstResponseTime" : {
"count" : 1,
"previousCount" : 14,
"ranges" : [ {
"id" : 10,
"count" : 1,
"percent" : 100.0,
"previousCount" : 12,
"previousPercent" : 85
} ]
},
"resolutionTime" : {
"count" : 17,
"previousCount" : 20,
"ranges" : [ {
"id" : 1,
"count" : 12,
"percent" : 70.588234,
"previousCount" : 5,
"previousPercent" : 25
}, {
"id" : 3,
"count" : 2,
"percent" : 11.764706,
"previousCount" : 1,
"previousPercent" : 5
} ]
},
"repliesToResolve" : {
"count" : 1,
"previousCount" : 14,
"ranges" : [ {
"id" : 2,
"count" : 1,
"percent" : 100.0,
"previousCount" : 4,
"previousPercent" : 28,
"resolutionTime" : 2278004
} ]
}
}
Response fields
| Path | Type | Description |
|---|---|---|
filterTags |
Array |
All tags available for filtering in reports, including tag id=1, which represents conversations that are untagged |
current |
Object |
Statistics about emails for the current time range |
previous |
Object |
Statistics about emails for the previous time range; only included if a previous time range was specified |
deltas |
Object |
Statistics showing how productivity changed between two time ranges; only included if a previous time range was specified |
responseTime |
Object |
Statistics about the amount of time customers waited for a reply from your company |
firstResponseTime |
Object |
Statistics about the amount of time customers waited for the first reply from your company; subsequent response times are not included |
handleTime |
Object |
Statistics about the amount of time between loading the conversation and pressing the Send button; if you save a draft and come back to visit it several times, only the final visit before sending will be captured as the handle time |
repliesToResolve |
Object |
Statistics about the number of replies sent to the customer before the conversation was resolved |
resolutionTime |
Object |
Statistics about the resolution time. |
Response fields
| Path | Type | Description |
|---|---|---|
startDate |
String |
Start of the range |
endDate |
String |
End of the range |
volume |
Object |
Email volume statistics |
responses |
Object |
Response time statistics |
resolutions |
Object |
Resolutions statistics |
Response fields
| Path | Type | Description |
|---|---|---|
emailConversations |
Number |
Conversations created by an email thread from the customer or a Help Scout User |
emailsCreated |
Number |
Email conversations created by a Help Scout User via the New Conversation screen or API |
repliesSent |
Number |
Number of replies sent from Users to customers, including new conversation email threads |
messagesReceived |
Number |
Number of messages received from customers. Each customer thread in a conversation counts towards this total |
Response fields
| Path | Type | Description |
|---|---|---|
resolved |
Number |
Conversations with at least one User reply and a status of Closed; a conversation can only be resolved once |
resolvedOnFirstReply |
Number |
Number of conversations that were resolved after one reply, as opposed to those requiring multiple replies |
percentResolvedOnFirstReply |
Number |
Percentage of conversations that were resolved after one reply, as opposed to those requiring multiple replies |
resolutionTime |
Number |
Average amount of time it takes (in seconds) from the time a conversation is created to the time it is resolved; a conversation can only be resolved once and must include a reply |
repliesToResolve |
Number |
Number of replies sent to the customer before the conversation is resolved |
handleTime |
Number |
This represents the time from when you open the conversation to the time you press Send. If you save a draft and come back to it several times, only the final visit before sending will be captured as the handle time. |
closed |
Number |
Number of conversations that were closed during the time range |
Response fields
| Path | Type | Description |
|---|---|---|
responseTime |
Number |
Average amount of time (in seconds) a customer is waiting for a response from your company |
firstResponseTime |
Number |
The average amount of time a customer is waiting for the first reply from your team; subsequent response times are not included |
Response fields
| Path | Type | Description |
|---|---|---|
count |
Number |
Total number of conversations in the current time range |
previousCount |
Number |
Total number of conversations in the previous time range |
ranges |
Array |
Contains information about how about distribution of the values in individual ranges; each element in the collection represents one time duration, identified by id |
ranges[].id |
Number |
Range identifier |
ranges[].count |
Number |
Total number of conversations in the current range |
ranges[].previousCount |
Number |
Total number of conversations in the previous time range |
ranges[].percent |
Number |
Percentage of conversations in this range |
ranges[].previousPercent |
Number |
Percentage of conversations in the previous range |
Response Time Range Identifiers
| ID | Category |
|---|---|
| 1 | < 15 min. |
| 2 | 15-30 min. |
| 3 | 30-60 min. |
| 4 | 1-2 hours |
| 5 | 2-3 hours |
| 6 | 3-6 hours |
| 7 | 6-12 hours |
| 8 | 12-24 hours |
| 9 | 1-2 days |
| 10 | > 2 days |
Response fields
| Path | Type | Description |
|---|---|---|
count |
Number |
Total number of conversations in the current time range |
previousCount |
Number |
Total number of conversations in the previous time range |
ranges |
Array |
Contains information about how about distribution of the values in individual ranges; each element in the collection represents one time duration, identified by id |
ranges[].id |
Number |
Range identifier |
ranges[].count |
Number |
Total number of conversations in the current range |
ranges[].previousCount |
Number |
Total number of conversations in the previous time range |
ranges[].percent |
Number |
Percentage of conversations in this range |
ranges[].previousPercent |
Number |
Percentage of conversations in the previous range |
Handle Time Range Identifiers
| ID | Category |
|---|---|
| 1 | < 1 min. |
| 2 | 1-2 min. |
| 3 | 2-5 min. |
| 4 | 5-10 min. |
| 5 | > 10 min. |
Response fields
| Path | Type | Description |
|---|---|---|
count |
Number |
Total number of conversations in the current time range |
previousCount |
Number |
Total number of conversations in the previous time range |
ranges |
Array |
Contains information about how about distribution of the values in individual ranges; each element in the collection represents one time duration, identified by id |
ranges[].id |
Number |
Range identifier |
ranges[].count |
Number |
Total number of conversations in the current range |
ranges[].previousCount |
Number |
Total number of conversations in the previous time range |
ranges[].percent |
Number |
Percentage of conversations in this range |
ranges[].previousPercent |
Number |
Percentage of conversations in the previous range |
ranges[].resolutionTime |
Number |
Average resolution times (in seconds) for each category |
Number of Replies Identifiers
| ID | Number of Replies |
|---|---|
| 1 | 1 |
| 2 | 2 |
| 3 | 3 |
| 4 | 4 |
| 5 | > 5 |