> ## Documentation Index > Fetch the complete documentation index at: https://docs.go.aiinsurance.io/llms.txt > Use this file to discover all available pages before exploring further. # Get Record Email Conversation > Reads one conversation on a record: every message the caller may see, oldest first, with its participants, attachments and the mailboxes that hold it. A caller without `email.view` sees only email sent from the platform. Answers `404` while email is not turned on for the company. **Required permission:** `.view` for the path's `{entityType}` (`event.view`, `exposure.view`, `quote.view`, `submission.view`, `person.view`, `organization.view`). `email.view` shows synced email too. ## OpenAPI ````yaml /openapi/generated-external-api.yaml get /api/v1/companies/{companyId}/entities/{entityType}/{entityId}/email-conversations/{threadId} openapi: 3.0.3 info: title: AI Insurance External API description: External API for AI Insurance platform version: 1.0.0 contact: email: support@aiinsurance.io servers: - url: https://go.aiinsurance.io description: Production security: - ApiKeyAuth: [] paths: /api/v1/companies/{companyId}/entities/{entityType}/{entityId}/email-conversations/{threadId}: get: tags: - Record Emails summary: Get Record Email Conversation description: > Reads one conversation on a record: every message the caller may see, oldest first, with its participants, attachments and the mailboxes that hold it. A caller without `email.view` sees only email sent from the platform. Answers `404` while email is not turned on for the company. **Required permission:** `.view` for the path's `{entityType}` (`event.view`, `exposure.view`, `quote.view`, `submission.view`, `person.view`, `organization.view`). `email.view` shows synced email too. operationId: getRecordEmailConversation parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/crudEntityType' - $ref: '#/components/parameters/entityIdPath' - $ref: '#/components/parameters/emailThreadIdPath' responses: '200': description: The conversation content: application/json: schema: $ref: '#/components/schemas/EmailConversation' examples: conversation: summary: A conversation with one message value: threadId: 7f0c2a1e-4b5d-4c8e-9a71-2d3e4f5a6b7c subject: Claim update mentionsRecord: false mentions: [] messages: - messageId: 1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d origin: synced subject: Claim update sentAt: '2026-02-15T10:00:00.000Z' from: address: alan@law.example name: Alan Law linkedPersonId: 550e8400-e29b-41d4-a716-446655440010 to: - address: bob@acme.example cc: [] bcc: [] snippet: Photos of the damage are attached. bodyText: Photos of the damage are attached. internal: false attachments: [] foundIn: - mailboxId: 3c4d5e6f-7a8b-4c9d-8e1f-2a3b4c5d6e7f mailbox: bob@acme.example folder: Inbox openInOutlookUrl: null '400': description: Bad Request - an invalid id content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidId: summary: The conversation id is not a UUID value: error: code: InvalidId message: Invalid conversation id userMessages: - Invalid conversation id '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: >- The conversation is not on the record, the record does not exist, or email is not turned on for the company content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conversationNotFound: summary: Conversation not on the record value: error: code: NotFoundError message: >- Conversation 7f0c2a1e-4b5d-4c8e-9a71-2d3e4f5a6b7c is not on Event 550e8400-e29b-41d4-a716-446655440301 userMessages: - >- Conversation 7f0c2a1e-4b5d-4c8e-9a71-2d3e4f5a6b7c is not on Event 550e8400-e29b-41d4-a716-446655440301 '500': $ref: '#/components/responses/InternalServerError' security: - BearerAuth: [] - ApiKeyAuth: [] components: parameters: companyId: name: companyId in: path required: true schema: type: string format: uuid description: Company identifier crudEntityType: name: entityType in: path required: true schema: type: string enum: - event - exposure - quote - submission - person - organization description: > Field Model V1 entity type (lowercase kebab-case URL slug). One of the six CRUD entity types: `event`, `exposure`, `quote`, `submission`, `person`, `organization`. `policy` is NOT valid here — Policy has no generic CRUD (its writes go through the policy transaction endpoints), though it does have a read-only `/configuration` schema. entityIdPath: name: entityId in: path required: true schema: type: string format: uuid description: Entity identifier emailThreadIdPath: name: threadId in: path required: true schema: type: string format: uuid description: The conversation's `threadId`, from List Record Email Conversations. schemas: EmailConversation: type: object description: >- One conversation on a record, every message the caller may see, oldest first. required: - threadId - subject - mentionsRecord - mentions - messages properties: threadId: type: string format: uuid subject: type: string mentionsRecord: type: boolean description: >- A message names the record's number. For an exposure, person or organization, which have no number, a message names any record. mentions: type: array description: >- The other records the conversation's messages name, by type, then label. The record itself is left out. items: $ref: '#/components/schemas/EmailMentionedRecord' messages: type: array items: type: object required: - messageId - origin - subject - sentAt - from - to - cc - bcc - snippet - bodyText - internal - attachments - foundIn - openInOutlookUrl properties: messageId: type: string format: uuid origin: type: string enum: - synced - sent - intake description: >- `synced` from a connected mailbox, `sent` from the platform, or `intake` from the intake inbox. subject: type: string sentAt: type: string format: date-time from: type: object allOf: - $ref: '#/components/schemas/EmailParticipant' nullable: true to: type: array items: $ref: '#/components/schemas/EmailParticipant' cc: type: array items: $ref: '#/components/schemas/EmailParticipant' bcc: type: array items: $ref: '#/components/schemas/EmailParticipant' snippet: type: string bodyText: type: string description: The message body as plain text. internal: type: boolean description: Every participant is on one of the company's own domains. attachments: type: array items: type: object required: - id - filename - contentType - sizeBytes - scanStatus properties: id: type: string format: uuid filename: type: string contentType: type: string sizeBytes: type: integer scanStatus: type: string enum: - pending - clean - infected - failed foundIn: type: array description: The mailboxes holding a copy of the message. items: type: object required: - mailboxId - mailbox - folder properties: mailboxId: type: string format: uuid mailbox: type: string description: The mailbox's address. folder: type: string openInOutlookUrl: type: string nullable: true description: >- A link that opens the message in Outlook. Set only when the calling user's own mailbox holds a copy; null otherwise. delivery: $ref: '#/components/schemas/EmailDelivery' ErrorResponse: type: object description: Standard error response for all external API endpoints required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable error code example: VALIDATION_ERROR message: type: string description: Human-readable error message example: 'submissionId: Required field is missing' userMessages: type: array description: >- Clean, verbatim-displayable messages — one entry per failure, free of error-code tags, field paths, and internal noise. Suitable for showing to end users as-is. items: type: string example: - Exposures of type 'company' require an address details: type: array description: Additional details for validation errors (field-level errors) items: type: object properties: field: type: string description: The field that caused the error example: submissionId code: type: string description: Stable problem code for this individual validation failure example: BLANK_LIST_ELEMENT reason: type: string description: Stable reason the value violates its canonical contract example: blank-list-element expected: type: string description: The expected canonical value contract example: nonblank trimmed string message: type: string description: Description of the field error example: Required field is missing EmailMentionedRecord: type: object description: >- A record that a conversation names by its number: a claim number, quote number, submission number or policy number. A number that no record carries is left out. required: - type - id - label properties: type: type: string enum: - Policy - Exposure - Event - Quote - Submission - Person - Organization description: >- The record's type. Only `Event`, `Quote`, `Submission` and `Policy` have numbers today. id: type: string format: uuid label: type: string description: >- The record's name as the app shows it: a claim's name, or the quote, submission or policy number. EmailParticipant: type: object required: - address properties: address: type: string description: The email address, lowercased. name: type: string description: The display name the email carried, when it had one. linkedPersonId: type: string format: uuid description: >- The person on this record whose address this is. Absent for an address that belongs to no one on the record. EmailDelivery: type: object description: How the app sent one message, and every status it passed through. required: - deliveryId - status - waitingOnPacket - reason - sentAt - attachPacket - packet - template - automaticEmail - requestedBy - history properties: deliveryId: type: string format: uuid status: $ref: '#/components/schemas/EmailDeliveryStatus' waitingOnPacket: type: boolean description: >- The send is `queued` and held until the packet whose PDF it attaches has finished issuing. It is sent once the packet is issued, and fails if the packet's issuing fails. reason: type: string nullable: true description: >- Why the send failed or bounced, in plain words; null unless `status` is `failed` or `bounced`. sentAt: type: string format: date-time nullable: true attachPacket: type: boolean description: >- The send attaches the packet's PDF. The PDF is attached when the email is sent, after the packet is issued. packet: type: object nullable: true description: The packet the email was sent from, and the record that holds it. required: - id - anchor properties: id: type: string format: uuid anchor: type: object required: - type - id properties: type: type: string enum: - quote - policy - event id: type: string format: uuid template: type: object nullable: true description: >- The exact email template version sent; null for an automatic email or another app notice. required: - id - name - version properties: id: type: string format: uuid name: type: string version: type: integer automaticEmail: type: object nullable: true description: >- The automatic email it was, such as a member invitation; null for anything else. required: - key - name - source properties: key: type: string description: The automatic email's key, such as `member.invitation`. name: type: string source: description: Which wording went out, our default or the company's version. oneOf: - type: object required: - kind properties: kind: type: string enum: - default - type: object required: - kind - version properties: kind: type: string enum: - company version: type: integer description: The company's version that was sent. requestedBy: type: object nullable: true description: The user who sent it. required: - userId - name properties: userId: type: string format: uuid name: type: string history: type: array description: Every status change, newest first. items: type: object required: - status - attempt - at - actor properties: status: $ref: '#/components/schemas/EmailDeliveryStatus' attempt: type: integer description: The send's attempt count when it reached this status. at: type: string format: date-time actor: type: object nullable: true description: The user who caused it; null when the app's worker did. required: - userId - name properties: userId: type: string format: uuid name: type: string EmailDeliveryStatus: type: string description: >- Where a send from the app stands: `queued` waits for a worker, `sending` is with the provider, `sent` was accepted, and `failed` did not go out. After `sent`, the provider reports `delivered` (the recipient's mail server took it), `bounced` (it refused it for good), or `complained` (a recipient marked it as spam). A bounce or complaint for any recipient overrides `delivered`. enum: - queued - sending - sent - failed - delivered - bounced - complained responses: Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingApiKey: summary: Missing API key value: error: code: AuthenticationError message: API key authentication required userMessages: - API key authentication required invalidApiKey: summary: >- Invalid API key (e.g. unknown key, or a Bearer token used instead of an API key) value: error: code: AuthenticationError message: Invalid API key userMessages: - Invalid API key Forbidden: description: Forbidden - Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficientPermissions: summary: Insufficient permissions value: error: code: AuthorizationError message: User is not authorized to perform the requested action userMessages: - User is not authorized to perform the requested action companyMismatch: summary: A valid API key naming another company in the URL value: error: code: AuthorizationError message: API key is not scoped to the requested company userMessages: - API key is not scoped to the requested company InternalServerError: description: Internal Server Error - Unexpected error occurred content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: Unexpected server error value: error: code: UncaughtActionError message: Uncaught error occurred in userMessages: - An unexpected error occurred. Please try again later. securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: >- API key authentication. Send your raw API key as the `Authorization` header value with NO scheme prefix — `Authorization: YOUR-API-KEY`. Do NOT prefix it with `Bearer ` or `ApiKey `, and do not use an `X-API-Key` header; those are not accepted. BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- User-principal OAuth 2.0 Bearer authentication. Send a user-scoped Auth0 access token (audience = the app API audience) as `Authorization: Bearer `. The request resolves to the user's identity and is authorized by their Role on the `{companyId}` in the path — the same role-based permissions the web app enforces. This is the path the MCP connector uses to act on a user's behalf; endpoints that accept it list both `BearerAuth` and `ApiKeyAuth`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.