> ## Documentation Index > Fetch the complete documentation index at: https://docs.famulor.io/llms.txt > Use this file to discover all available pages before exploring further. # Get an email conversation > Returns every inbound and outbound turn in the email thread in chronological order, including stable thread and immediate-parent IDs, full plain-text bodies, reply states/errors, and attachment metadata. Inbound audio and image attachments can include a transcript or a short image description, with media links valid for one hour. Image descriptions can include readable text; PDFs, videos and other files retain metadata only. **Required scope:** `calls:read`. Removed conversations are excluded. Their detail IDs return not found. ## OpenAPI ````yaml /api-reference/openapi.json get /history/emails/{id} openapi: 3.1.0 info: title: Famulor API version: 1.0.0 description: >- REST API for Famulor. Authenticate with an API key (`fam_...`, created under **Settings → API Keys**) or an OAuth 2.0 access token (`fam_at_...`) as a Bearer token. Every response uses a consistent envelope: `{ "data": ... , "meta": { ... } }` on success and `{ "error": { "code", "message" } }` on failure. List endpoints paginate with `?limit=` (default 50, max 200) and `?offset=`; `meta.pagination.total` carries the total match count. REST operations require API Access through the workspace plan or a recurring add-on. Without it, regular operations return `403 api_access_required`. The invoice-payment and billing-portal operations remain available with a valid `billing:write` credential after a failed plan payment so an authorized owner, admin, or billing member can recover billing. The same customer-facing capabilities are available as MCP tools at `https://app.famulor.io/mcp` (Model Context Protocol, streamable HTTP) using the same credentials, scopes, and workspace access. MCP availability is controlled separately by Connect AI / MCP, not by API Access. servers: - url: https://app.famulor.io/api/v1 description: Hosted platform. - url: https://{domain}/api/v1 description: White-label tenant domain — same paths, tenant branding. variables: domain: default: app.famulor.io description: Your white-label tenant domain. security: - bearerAuth: [] tags: - name: Account description: Self-inspection of the calling credential. - name: Migrations description: Preview and import data from supported legacy platforms. - name: Assistants description: Create and manage voice assistants. - name: Tools description: >- Reusable tools (HTTP APIs and external MCP servers) assistants can call mid-conversation. - name: Voices description: Browse the text-to-speech voice library. - name: Calls description: Start outbound calls and read call history, transcripts and recordings. - name: History description: Unified conversation history across calls, messaging and assistant emails. - name: Campaigns description: Outbound calling campaigns with a compliant power dialer. - name: Leads description: Manage Audience contacts across campaigns, channels and Call QA metrics. - name: Segments description: >- Saved, dynamic lead filters — reusable audience definitions used for Audience search and campaign lead assignment. - name: Suppression description: Cross-channel marketing opt-outs and active workspace suppression records. - name: Callbacks description: >- Scheduled callbacks booked by the Schedule callback tool across voice, chat, and email. - name: Phone Numbers description: Marketplace numbers and customer-provided numbers. - name: Famulor Loop description: >- Personal business-phone access, directory, presence, devices, and Loop call recents. - name: SIP Trunks description: Bring your own SIP provider and numbers. - name: Carrier Connections description: Connect a supported carrier account and import its existing phone numbers. - name: Knowledge Bases description: RAG knowledge bases and documents for assistants. - name: Settings description: Workspace-level settings such as caller-memory defaults. - name: Billing description: Balance and transaction ledger of the API key's workspace. - name: Automations description: >- Native workspace automations — list, create, update, trigger. Requires Automations in the workspace plan. - name: Milian Missions description: Recurring jobs that Milian runs unattended on schedule. - name: Integrations description: >- Calendar integrations (Cal.com, Calendly, Acuity Scheduling, Google Calendar, Outlook, native booking engine). Assign them to assistants to provide availability and booking tools, plus provider-supported appointment lookup, cancellation, and rescheduling. - name: Bookings description: >- Native booking engine — event types with weekly availability, public booking pages at /book/{workspace}/{slug}, and the bookings they produce. - name: Dashboards description: >- Custom analytics dashboards, reusable widgets, and tenant-scoped performance analytics. Requires Custom dashboards in the workspace plan. - name: Catalog description: >- Read-only platform catalogs — available models, supported assistant languages, and prompt templates. - name: Simulations description: Assistant simulation tests (plan-gated). - name: Versions description: Assistant configuration version history. - name: Caller IDs description: Outbound caller ID verification. - name: Widgets description: Web widget connectors. - name: Messaging description: >- Telegram, Slack, and Messenger text bots linked to assistants (Chat SDK). Includes conversation delay, inactivity end, and conversation-ended webhooks. - name: QA description: Cohort AI Quality Assurance runs over call transcripts. - name: White Label description: >- Manage white-label customer accounts, defaults, credit transfers and customer plan offers. Each endpoint documents its required scope and workspace eligibility. - name: API Keys description: >- Self-service API keys for the calling workspace or a same-brand workspace where the credential's user is owner/admin. A key can only mint further keys with a scope subset of its own. - name: Workspaces description: >- List visible workspaces, create an additional workspace for the key owner, and mint a dedicated credential for a selected owner/admin workspace. - name: SMS description: Outbound SMS from workspace phone numbers. - name: Milian description: >- Ask Milian, the AI co-worker in your workspace, and start voice sessions with it. - name: Translation description: >- Live translation sessions that interpret a conversation between two languages. paths: /history/emails/{id}: parameters: - name: id in: path required: true schema: type: string format: uuid description: >- Email message or thread-root ID. Any message ID in the thread resolves to the complete conversation. get: tags: - History summary: Get an email conversation description: >- Returns every inbound and outbound turn in the email thread in chronological order, including stable thread and immediate-parent IDs, full plain-text bodies, reply states/errors, and attachment metadata. Inbound audio and image attachments can include a transcript or a short image description, with media links valid for one hour. Image descriptions can include readable text; PDFs, videos and other files retain metadata only. **Required scope:** `calls:read`. Removed conversations are excluded. Their detail IDs return not found. operationId: getEmailHistoryItem responses: '200': description: Grouped email conversation detail. content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/EmailHistoryDetail' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/RequestProtectionUnavailable' components: schemas: EmailHistoryDetail: allOf: - $ref: '#/components/schemas/HistoryItem' - type: object required: - text_body - html_body - attachments - message_id - sendgrid_message_id - in_reply_to - messages properties: channel: type: string const: email thread_id: type: string format: uuid text_body: type: string html_body: type: - string - 'null' description: Untrusted email HTML; sanitize before rendering. attachments: type: array items: $ref: '#/components/schemas/EmailAttachment' message_id: type: - string - 'null' sendgrid_message_id: type: - string - 'null' in_reply_to: type: - string - 'null' format: uuid messages: type: array items: $ref: '#/components/schemas/EmailThreadMessage' description: >- Every inbound and outbound message in the stable thread, ordered chronologically. HistoryItem: type: object required: - id - thread_id - channel - direction - assistant_id - assistant_name - status - contact - from - to - subject - body_preview - summary - duration_sec - campaign_id - reply_status - reply_error - attachments_count - message_count - created_at - last_activity_at properties: id: type: string format: uuid thread_id: type: - string - 'null' format: uuid description: Stable email or messaging conversation ID; null for calls. lead_id: type: - string - 'null' format: uuid description: Canonical Audience contact relation. channel: type: string enum: - sms - call - avatar - email - live_chat - whatsapp_voice - whatsapp - telegram - slack - messenger - teams - discord - gchat - x - freshdesk - gmail - outlook - zendesk - servicenow - intercom - zoho_mail - agent_mail - instagram - zulip description: Channel of the conversation. Filter with the `type` query parameter. direction: type: string enum: - inbound - outbound - web assistant_id: type: - string - 'null' format: uuid assistant_name: type: - string - 'null' status: type: string enum: - queued - ringing - in_progress - completed - failed - no_answer - busy - skipped failure: $ref: '#/components/schemas/PublicCallFailure' description: >- Provider-neutral failure guidance. Present only when a call-row conversation has a normalized outbound failure. contact: type: - string - 'null' description: External phone number or email address. from: type: - string - 'null' to: type: - string - 'null' subject: type: - string - 'null' description: Email subject; null for calls. body_preview: type: - string - 'null' description: >- Compact plain-text email or messaging preview, separate from the generated summary; null for calls. summary: type: - string - 'null' description: >- Generated conversation recap; null when unavailable. Never replaced by a subject, message preview, transcript excerpt or success explanation. duration_sec: type: - integer - 'null' description: Call duration; null for emails. campaign_id: type: - string - 'null' format: uuid reply_status: type: - string - 'null' enum: - pending - replied - skipped - failed - null description: >- Raw auto-reply state for inbound emails; null for calls and outbound email rows. reply_error: type: - string - 'null' attachments_count: type: integer minimum: 0 message_count: type: integer minimum: 1 description: All inbound and outbound messages grouped into this conversation. created_at: type: string format: date-time last_activity_at: type: string format: date-time description: >- Latest message time for email threads; equal to created_at for calls. imported_from_whatsapp_history: type: boolean description: >- WhatsApp Coexistence only: true when this conversation was backfilled from the customer's WhatsApp Business app chat history rather than a live AI session. inbox_labels: type: array items: $ref: '#/components/schemas/InboxLabel' description: >- Active advisory labels. Empty while processing, when no label is assigned, or after dismissal. Absence of a label is not proof of authenticity. EmailAttachment: type: object required: - filename - type - size properties: filename: type: string type: type: string size: type: - integer - 'null' transcript: type: - string - 'null' description: >- Recognized speech from a successfully transcribed inbound audio attachment, when available. url: type: - string - 'null' format: uri description: >- Media link for retained inbound audio or images, valid for one hour. Fetch the email conversation again to refresh it. description: type: - string - 'null' description: >- Short description of an analyzed image, including readable text when possible. This is a summary rather than a complete OCR export. EmailThreadMessage: type: object required: - id - thread_id - in_reply_to - message_id - direction - from - to - subject - text_body - attachments - sendgrid_message_id - reply_status - reply_error - created_at properties: id: type: string format: uuid thread_id: type: string format: uuid in_reply_to: type: - string - 'null' format: uuid description: Immediate parent message in this conversation. message_id: type: - string - 'null' description: RFC Message-ID used by email clients for threading. direction: type: string enum: - inbound - outbound from: type: string to: type: string subject: type: string text_body: type: string attachments: type: array items: $ref: '#/components/schemas/EmailAttachment' sendgrid_message_id: type: - string - 'null' reply_status: type: - string - 'null' enum: - pending - replied - skipped - failed - null reply_error: type: - string - 'null' created_at: type: string format: date-time inbox_labels: type: array items: $ref: '#/components/schemas/InboxLabel' description: >- Active advisory labels. Empty while processing, when no label is assigned, or after dismissal. Absence of a label is not proof of authenticity. ErrorEnvelope: type: object description: Error envelope returned by every /api/v1 endpoint on failure. required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - unauthorized - forbidden - api_access_required - not_found - invalid_request - rate_limited - conflict - telephony_configuration_error - telephony_unavailable - destination_forbidden - internal_error - service_unavailable description: >- Stable, machine-readable error code. `service_unavailable` is returned by POST /bookings and GET /booking-event-types/{id}/slots specifically when the availability engine could not be reached (see AvailabilityOrProtectionUnavailable). message: type: string description: Human-readable description of the error. PublicCallFailure: type: object additionalProperties: false required: - domain - code - message - retryable - action description: >- Provider-neutral failure guidance for calls. Telephony failures also set operation. properties: domain: type: string enum: - telephony - billing - admission - runtime - config - dispatch - workspace operation: type: string enum: - outbound_call - cold_transfer - warm_transfer description: Present when domain is telephony. code: type: string enum: - busy - declined - no_answer - temporarily_unavailable - cancelled_before_answer - invalid_destination - destination_not_found - authentication_failed - destination_forbidden - caller_blocked - call_redirected - invalid_call_request - phone_account_payment_required - destination_gone - media_not_supported - connection_timeout - request_too_large - calling_feature_unsupported - call_timer_rejected - caller_identity_rejected - phone_connection_failed - routing_limit_reached - call_permission_required - call_session_not_found - destination_ambiguous - call_request_pending - call_security_rejected - phone_network_timeout - call_requirements_not_met - call_unwanted - call_blocked_by_network - routing_loop - routing_conflict - method_not_allowed - trunk_unavailable - no_outbound_trunk - transfer_unavailable - unknown - insufficient_credits - reservation_failed - outbound_quota_reservation_failed - integrated_outbound_limit_reached - quiet_hours - budget_service_unavailable - workspace_concurrency_limit - campaign_concurrency_limit - platform_unavailable - region_unavailable - capability_unavailable - capacity_exhausted - admission_unavailable - voice_unavailable - speech_unavailable - assistant_unavailable - call_runtime_failed - workspace_suspended - dispatch_failed - missing_destination - ivr_detected - voicemail_detected - mailbox_unavailable message: type: string description: Stable, provider-neutral English explanation. retryable: type: boolean description: >- Informational retry guidance. It does not change campaign retry policy. action: type: string enum: - retry_later - do_not_retry - check_destination - check_trunk_credentials - check_trunk_configuration - connect_outbound_number - continue_call - contact_support - top_up - check_assistant - check_campaign_schedule InboxLabel: type: object description: >- Advisory label. It never changes message visibility, replies, or the connected mailbox. required: - id - label - message_id - created_at properties: id: type: string format: uuid label: type: string enum: - possible_scam - advertising message_id: type: string format: uuid created_at: type: string format: date-time responses: Unauthorized: description: Missing, invalid, expired or revoked API key / access token. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: unauthorized message: Invalid API key. Forbidden: description: >- The credential lacks the required scope or role, or the workspace does not have the required capability. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: scopeDenied: summary: Required scope is missing value: error: code: forbidden message: >- This API key is missing the required scope "assistants:write". apiAccessRequired: summary: API Access is not available value: error: code: api_access_required message: >- API Access is not available for this workspace. Review Settings → Plan. NotFound: description: Resource not found (or it belongs to another workspace). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: not_found message: Assistant not found RateLimited: description: Too many requests. Retry after the indicated delay. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: rate_limited message: Too many requests. Retry after the indicated delay. RequestProtectionUnavailable: description: Request protection is temporarily unavailable. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: internal_error message: Request protection is temporarily unavailable. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- API key (`fam_...`, created under **Settings → API Keys**) or an OAuth 2.0 access token (`fam_at_...`). REST operations also require API Access for the credential's workspace. Keys can be restricted to scopes such as `assistants:read`, `calls:write`, `campaigns:write`, `automations:read`, `dashboards:read`, `dashboards:write`, `leads:write`, `segments:write`, `loop:read`, `loop:write`, `phone_numbers:write`, `sip_trunks:write`, `knowledge:write`, `voices:read`, `billing:read`, `billing:write`, `settings:write`, `platform:read`, `platform:write`; a `*:write` scope implies the matching `*:read`. Automation and dashboard endpoints also accept the legacy `calls:*` scope. Keys without scope restrictions have full access within the workspace's available capabilities. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.