integrations

Get the thread of an email

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://docs.usehearsay.com/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json 
{
  "integrations MCP server": {
    "url": "https://docs.usehearsay.com/mcp"
  }
}
Close
GET /local-emails/{caseId}/emails/{emailId}/thread
Access token

Returns the thread an email belongs to and the ids of all its emails, newest first. An email the caller may not see is reported as not found.

Path parameters

  • caseId string Required
  • emailId string Required

Query parameters

  • includeLastMessage boolean

    When truthy (1/true), populate lastMessageOrDraft (id/subject) on the thread; otherwise it is returned as null. The message body is never included — fetch it from the thread-emails endpoint.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • data object Required
      Hide data attributes Show data attributes object
      • thread object Required
        Hide thread attributes Show thread attributes object
        • createdAt string(date-time) Required
        • updatedAt string(date-time) Required
        • id string Required
        • sourceEmail string Required
        • grantId string Required
        • externalId string Required
        • lastMessageOrDraft object Required

          The full record on routes that load it; null (or an empty list) on routes that do not.

          Hide lastMessageOrDraft attributes Show lastMessageOrDraft attributes object
          • createdAt string(date-time) Required
          • updatedAt string(date-time) Required
          • id string Required
          • emailDataProvider object | null Required

            Not loaded by any route, so always null.

          • sourceEmail string Required
          • body string | null Required
          • date string(date-time) | null Required
          • attachments array[object] | null Required

            The full record on routes that load it; null (or an empty list) on routes that do not.

            Hide attachments attributes Show attachments attributes object
            • createdAt string(date-time) Required
            • updatedAt string(date-time) Required
            • id string Required
            • name string Required
            • providerId string Required
            • convertedName string | null Required
            • convertedProviderId string Required
            • provider string Required
            • size number Required

              Size in bytes

            • transferState number | null Required
          • bcc array[object] Required
          • cc array[object] Required
          • from array[object] Required
          • replyTo array[object] Required
          • to array[object] Required
          • folders array[string] Required
          • grantId string Required
          • externalId string Required
          • object string | null Required
          • snippet string | null Required
          • starred boolean Required
          • unread boolean Required
          • subject string | null Required
          • threadId string Required
          • threadIndex number Required
          • tags array[object] | null Required

            The full record on routes that load it; null (or an empty list) on routes that do not.

            Hide tags attributes Show tags attributes object
            • createdAt string(date-time) Required
            • updatedAt string(date-time) Required
            • id string Required
            • name string Required
            • nameLowercase string Required
            • backgroundColor string Required
            • textColor string Required
            • type string Required

              Values are system, organization, case, or user.

            • severity string Required

              Values are info, warning, or danger.

            • origin string Required

              Values are manual or auto-import.

            • creatorAccessType string | null

              Values are org or opposing_council.

            • isActive boolean Required
          • attachedTags array[object]
            Hide attachedTags attributes Show attachedTags attributes object
            • tagId string Required

              Tag id (Tag._id)

            • tag string Required

              Tag display name (Tag.name)

            • addedBy string Required

              Values are user, ai, auto, auto-import, system, or default.

            • addedById string | null
            • removedAt string(date-time) | null
            • removedBy string | null

              Values are user, ai, auto, auto-import, system, or default.

            • removedById string | null
        • emailCount number Required

          Number of emails in the thread

        • hasAttachments boolean Required
        • hasDrafts boolean Required
        • earliestMessageDate string(date-time) | null Required
        • latestMessageReceivedDate string(date-time) | null Required
        • latestMessageSentDate string(date-time) | null Required
        • participants array[object] Required
        • folders array[string] Required
        • messageIds array[string] Required
        • draftIds array[string] Required
        • snippet string | null Required
        • starred boolean Required
        • unread boolean Required
        • subject string | null Required
        • tags array[object] | null Required

          The full record on routes that load it; null (or an empty list) on routes that do not.

          Hide tags attributes Show tags attributes object
          • createdAt string(date-time) Required
          • updatedAt string(date-time) Required
          • id string Required
          • name string Required
          • nameLowercase string Required
          • backgroundColor string Required
          • textColor string Required
          • type string Required

            Values are system, organization, case, or user.

          • severity string Required

            Values are info, warning, or danger.

          • origin string Required

            Values are manual or auto-import.

          • creatorAccessType string | null

            Values are org or opposing_council.

          • isActive boolean Required
        • attachedTags array[object]
          Hide attachedTags attributes Show attachedTags attributes object
          • tagId string Required

            Tag id (Tag._id)

          • tag string Required

            Tag display name (Tag.name)

          • addedBy string Required

            Values are user, ai, auto, auto-import, system, or default.

          • addedById string | null
          • removedAt string(date-time) | null
          • removedBy string | null

            Values are user, ai, auto, auto-import, system, or default.

          • removedById string | null
        • ocSharedStatus string | null

          Opposing-council only: whether this thread has been shared with the OL. null for OL/OG callers — same convention as cases/files/:caseId and conversation/search-entries.

          Values are shared, pending, or not_gated.

      • emailIds array[string] Required
    • statusCode number Required
    • timestamp string(date-time) Required
GET /local-emails/{caseId}/emails/{emailId}/thread 
curl \
 --request GET 'http://api.example.com/local-emails/{caseId}/emails/{emailId}/thread' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
{
  "data": {
    "thread": {
      "createdAt": "2026-01-15T14:30:00.000Z",
      "updatedAt": "2026-01-15T14:30:00.000Z",
      "id": "507f1f77bcf86cd799439011",
      "sourceEmail": "jane.doe@example.com",
      "grantId": "5f0c8b3e-2a41-4d7c-9a51-1c2b3d4e5f60",
      "externalId": "18d1f2a3b4c5d6e0",
      "lastMessageOrDraft": {
        "createdAt": "2026-01-15T14:30:00.000Z",
        "updatedAt": "2026-01-15T14:30:00.000Z",
        "id": "507f1f77bcf86cd799439011",
        "emailDataProvider": {},
        "sourceEmail": "jane.doe@example.com",
        "body": "<p>Please find the signed agreement attached.</p>",
        "date": "2026-01-15T14:30:00.000Z",
        "attachments": [
          {
            "createdAt": "2026-01-15T14:30:00.000Z",
            "updatedAt": "2026-01-15T14:30:00.000Z",
            "id": "507f1f77bcf86cd799439011",
            "name": "photo.heic",
            "providerId": "uploads/507f1f77bcf86cd799439011/photo.heic",
            "convertedName": "photo.jpg",
            "convertedProviderId": "uploads/507f1f77bcf86cd799439011/photo.jpg",
            "provider": "s3",
            "size": 204800,
            "transferState": 42.0
          }
        ],
        "bcc": [
          {}
        ],
        "cc": [
          {
            "name": "Sam Lee",
            "email": "sam.lee@example.com"
          }
        ],
        "from": [
          {
            "name": "John Roe",
            "email": "john.roe@example.org"
          }
        ],
        "replyTo": [
          {}
        ],
        "to": [
          {
            "name": "Jane Doe",
            "email": "jane.doe@example.com"
          }
        ],
        "folders": [
          "INBOX"
        ],
        "grantId": "5f0c8b3e-2a41-4d7c-9a51-1c2b3d4e5f60",
        "externalId": "18d1f2a3b4c5d6e7",
        "object": "message",
        "snippet": "Please find the signed agreement attached.",
        "starred": false,
        "unread": false,
        "subject": "Signed agreement",
        "threadId": "18d1f2a3b4c5d6e0",
        "threadIndex": 0,
        "tags": [
          {
            "createdAt": "2026-01-15T14:30:00.000Z",
            "updatedAt": "2026-01-15T14:30:00.000Z",
            "id": "507f1f77bcf86cd799439011",
            "name": "Important",
            "nameLowercase": "important",
            "backgroundColor": "#FDE68A",
            "textColor": "#92400E",
            "type": "system",
            "severity": "info",
            "origin": "manual",
            "creatorAccessType": "org",
            "isActive": true
          }
        ],
        "attachedTags": [
          {
            "tagId": "507f1f77bcf86cd799439011",
            "tag": "Important",
            "addedBy": "user",
            "addedById": "507f1f77bcf86cd799439012",
            "removedAt": "2026-05-04T09:42:00Z",
            "removedBy": "user",
            "removedById": "string"
          }
        ]
      },
      "emailCount": 3,
      "hasAttachments": true,
      "hasDrafts": false,
      "earliestMessageDate": "2026-01-12T09:05:00.000Z",
      "latestMessageReceivedDate": "2026-01-15T14:30:00.000Z",
      "latestMessageSentDate": "2026-01-14T16:45:00.000Z",
      "participants": [
        {
          "name": "Jane Doe",
          "email": "jane.doe@example.com"
        },
        {
          "name": "John Roe",
          "email": "john.roe@example.org"
        }
      ],
      "folders": [
        "INBOX"
      ],
      "messageIds": [
        "18d1f2a3b4c5d6e0",
        "18d1f2a3b4c5d6e5",
        "18d1f2a3b4c5d6e7"
      ],
      "draftIds": [
        "string"
      ],
      "snippet": "Please find the signed agreement attached.",
      "starred": false,
      "unread": true,
      "subject": "Signed agreement",
      "tags": [
        {
          "createdAt": "2026-01-15T14:30:00.000Z",
          "updatedAt": "2026-01-15T14:30:00.000Z",
          "id": "507f1f77bcf86cd799439011",
          "name": "Important",
          "nameLowercase": "important",
          "backgroundColor": "#FDE68A",
          "textColor": "#92400E",
          "type": "system",
          "severity": "info",
          "origin": "manual",
          "creatorAccessType": "org",
          "isActive": true
        }
      ],
      "attachedTags": [
        {
          "tagId": "507f1f77bcf86cd799439011",
          "tag": "Important",
          "addedBy": "user",
          "addedById": "507f1f77bcf86cd799439012",
          "removedAt": "2026-05-04T09:42:00Z",
          "removedBy": "user",
          "removedById": "string"
        }
      ],
      "ocSharedStatus": "shared"
    },
    "emailIds": [
      "65a1b2c3d4e5f6a7b8c9d0c3",
      "65a1b2c3d4e5f6a7b8c9d0c2"
    ]
  },
  "statusCode": 200,
  "timestamp": "2026-01-15T10:15:00.000Z"
}