Summary
Every thread, message, and attachment exchanged with one email address in this inbox. :address is URL-encoded, trimmed, and compared case-insensitively. A value that is not an email is HTTP 400 invalid_address. A message counts when the address is From on inbound mail, or it is in To or Cc, or it is in Bcc of mail this account sent. The inbox address, including a plus address such as local+tag@domain, is not a contact. SMS is omitted. Spam and trash stay out unless folder is set, the same as a thread list. limit defaults to 20 and cannot exceed 100. before and after are exclusive ISO-8601 bounds (HTTP 400 invalid_date). cursor pages the messages, newest first (HTTP 400 invalid_cursor). include=bodies adds text bodies. The default omits them. Attachments are id, filename, content type, and size. The scan keeps the newest 5000 matching messages. summary counts that window, and summary.truncated is true when older matches were left out. threads lists at most 50, newest activity first. threads_has_more is true when more threads are in the window. Requires message_read. Another inbox is HTTP 404 inbox_not_found. MCP: cooper_contact_history.
Request
This call has no JSON body.
Response
HTTP 200. Sample values illustrate the schema.
{
"object": "contact_history",
"address": "ada@example.com",
"inbox_id": null,
"summary": {
"first_seen_at": null,
"last_seen_at": null,
"last_inbound_at": null,
"last_outbound_at": null,
"messages_received": 1,
"messages_sent": 1,
"threads": 1,
"attachments": 1,
"truncated": true
},
"threads": [
{
"object": "thread",
"id": "inb_example",
"inbox_id": "inb_example",
"subject": "Hello",
"message_count": 1,
"updated_at": "2026-10-18T12:00:00.000Z"
}
],
"threads_has_more": true,
"messages": [
{
"id": "msg_example",
"inbox_id": "inb_example",
"thread_id": "thr_example",
"folder": "inbox",
"direction": "inbound",
"from": "ada@example.com",
"to": [
"string"
],
"subject": "Hello",
"text": "Tuesday works.",
"html": null,
"extracted_text": "string",
"alias": null,
"aliases": [
"string"
],
"extracted_html": "string",
"preview": "string",
"verification": {
"codes": [
"string"
],
"links": [
{
"url": null,
"text": null
}
]
},
"delivery_events": [
{
"type": "string",
"recipient": "string",
"created_at": "2026-10-18T12:00:00.000Z",
"detail": "string"
}
],
"cc": [
"string"
],
"bcc": [
"string"
],
"reply_to": null,
"in_reply_to": null,
"references": [
"string"
],
"labels": [
"string"
],
"auth": {
"spf": null,
"dkim": null,
"dmarc": null
}
}
],
"has_more": true,
"next_cursor": null
}Errors
- HTTP 400 invalid_address
- HTTP 400 invalid_date
- HTTP 400 invalid_cursor
- HTTP 404 inbox_not_found
- HTTP 400 invalid_folder
- HTTP 400 invalid_include
Idempotency
This route does not document Idempotency-Key or client_id.