> ## 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. # List Policy Email Conversations > Lists the email conversations linked to a record, newest activity first, 50 per page. These are the conversations the record's Emails tab shows. Pass `nextCursor` back as `cursor` for the next page. A caller without `email.view` sees only email sent from the platform. A person or organization lists its last 12 months unless `from` or `to` is given. Answers `404` while email is not turned on for the company. The policy's twin of the record route under `/entities`: policies live under the policy API. **Required permission:** `policy.view`. `email.view` shows synced email too. ## OpenAPI ````yaml /openapi/generated-external-api.yaml get /api/v1/companies/{companyId}/policies/{policyId}/email-conversations 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}/policies/{policyId}/email-conversations: get: tags: - Record Emails summary: List Policy Email Conversations description: > Lists the email conversations linked to a record, newest activity first, 50 per page. These are the conversations the record's Emails tab shows. Pass `nextCursor` back as `cursor` for the next page. A caller without `email.view` sees only email sent from the platform. A person or organization lists its last 12 months unless `from` or `to` is given. Answers `404` while email is not turned on for the company. The policy's twin of the record route under `/entities`: policies live under the policy API. **Required permission:** `policy.view`. `email.view` shows synced email too. operationId: listPolicyEmailConversations parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/policyIdPath' - name: search in: query required: false schema: type: string description: >- Conversations with a message whose subject or body contains this text. - name: personId in: query required: false schema: type: string format: uuid description: Conversations with a message from or to this person on the record. - name: mailboxId in: query required: false schema: type: string format: uuid description: Conversations with a message found in this mailbox. - name: from in: query required: false schema: type: string format: date-time description: Conversations active at or after this time, with an offset or `Z`. - name: to in: query required: false schema: type: string format: date-time description: Conversations last active before this time, with an offset or `Z`. - name: mentionsRecord in: query required: false schema: type: boolean description: >- When `true`, only conversations that name the record's number. For an exposure, person or organization, which have no number, only conversations that name any record. - $ref: '#/components/parameters/emailCursor' responses: '200': description: A page of conversations content: application/json: schema: type: object required: - items - nextCursor properties: items: type: array items: $ref: '#/components/schemas/EmailConversationSummary' nextCursor: type: string nullable: true description: Null on the last page. examples: onePage: summary: One conversation value: items: - threadId: 7f0c2a1e-4b5d-4c8e-9a71-2d3e4f5a6b7c subject: Claim update preview: Photos of the damage are attached. participants: - address: alan@law.example name: Alan Law linkedPersonId: 550e8400-e29b-41d4-a716-446655440010 - address: bob@acme.example name: Bob messageCount: 3 attachmentCount: 2 lastActivityAt: '2026-02-15T10:00:00.000Z' mentionsRecord: true mentions: - type: Policy id: 550e8400-e29b-41d4-a716-446655440401 label: P00001184-26 nextCursor: null '400': description: Bad Request - an invalid id, date, filter or cursor content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidCursor: summary: The cursor is not one this endpoint returned value: error: code: InvalidCursor message: Invalid cursor userMessages: - Invalid cursor '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: The record does not exist, or email is not turned on for the company content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: recordNotFound: summary: Record not found value: error: code: NotFoundError message: Event 550e8400-e29b-41d4-a716-446655440301 not found userMessages: - Event 550e8400-e29b-41d4-a716-446655440301 not found '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 policyIdPath: name: policyId in: path required: true schema: type: string format: uuid description: Policy identifier emailCursor: name: cursor in: query required: false schema: type: string description: The `nextCursor` from the previous page. Omit it for the first page. schemas: EmailConversationSummary: type: object description: One conversation in a record's email list. required: - threadId - subject - preview - participants - messageCount - attachmentCount - lastActivityAt - mentionsRecord - mentions properties: threadId: type: string format: uuid subject: type: string preview: type: string description: A line from the newest message. participants: type: array description: Everyone on the conversation, people linked to the record first. items: $ref: '#/components/schemas/EmailParticipant' messageCount: type: integer attachmentCount: type: integer lastActivityAt: type: string format: date-time mentionsRecord: type: boolean description: >- A message names the record's number: a claim number, quote number, submission number or policy number. An exposure, person or organization has no number, so for them it means a message names any record, and `mentions` is not empty. 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' delivery: $ref: '#/components/schemas/EmailDeliverySummary' 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 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. 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. EmailDeliverySummary: type: object description: >- The newest send from the app among the conversation's messages on this record. required: - status - waitingOnPacket properties: 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 description: >- Why the send failed or bounced, in plain words. Set only when `status` is `failed` or `bounced`. sentAt: type: string format: date-time description: >- When the provider accepted it. Set only when `status` is `sent`, `delivered`, `bounced` or `complained`. 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.