Attrove Messages API
The Messages API from Attrove — 2 operation(s) for messages.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/attrove-com:attrove-com-messages-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Attrove Messages API
description: Attrove public API, partner, and A2A endpoints
version: v1
servers:
- url: http://0.0.0.0:3000
tags:
- name: Messages
paths:
/v1/users/{user_id}/messages:
get:
summary: List messages
tags:
- Messages
description: 'Returns messages for the authenticated user with optional filtering.
**Primary use case**: After calling `/v1/users/:user_id/query`, use `used_message_ids` to fetch full message content.
For non-message sources, use `used_meeting_ids` with `/v1/users/:user_id/meetings/:meeting_id` and `used_event_ids` with `/v1/users/:user_id/events/:event_id`.
**Response fields**:
Every message includes `sender_name` (human-readable name, null if unresolved) and `sent_by` (platform-specific sender identifier: email address for Gmail/Outlook, Slack user ID for Slack, Microsoft Graph user ID or email address for Microsoft Teams; returns ''unknown'' if unresolved).
**Expand parameter**:
Heavy fields are not included by default to keep list payloads small. Request them via `expand=`:
- `body_text` — plain-text body
- `body_html` — original HTML body (emails only)
- `raw` — RFC 5322 wire format (emails only; null for non-email providers and messages synced before this was supported)
- `headers` — parsed internet message headers as `[{ name, value }]` (emails only; null when unavailable)
Example: `expand=body_text,raw,headers`.
**Thread bundle (always included)**: `thread_id`, `parent_message_id`, `thread_position`, `conversation_id`, `primary_entity_id`, `entity_ids`. Use these to group messages and cross-reference contacts without extra queries.
**Note on expand behavior**: Single-item endpoints (`GET /v1/users/:user_id/messages/:id`) always return all fields.
List endpoints require `expand` for detailed fields to keep payloads lightweight.
**Filtering**:
- `ids`: Comma-separated message IDs (msg_xxx format) to fetch specific messages
- `integration_id`: Filter to a specific integration (int_xxx format)
- `conversation_id`: Filter to a specific conversation (conv_xxx format)
- `sent_by`: Exact sender identifier (email address for Gmail/Outlook, Slack user ID for Slack, Microsoft Graph user ID or email for Teams)
- `entity_id`: Filter by resolved contact (ent_xxx format from `GET /entities`, or raw UUID)
- `entity_scope`: Controls how `entity_id` matches: "sender" (default) returns messages sent BY entity, "conversation" returns messages where entity is sender or recipient. Requires `entity_id`.
- `start_date`: Messages received after this date (YYYY-MM-DD)
- `end_date`: Messages received before this date (YYYY-MM-DD)
- `exclude_bots`: Exclude bot/automated messages (true/false, default: false)
**Pagination (cursor-only)**:
- `limit`: Maximum number of messages per page (default: 50, max: 100)
- `cursor`: Opaque token from `pagination.next_cursor` of a prior response. Pass it back unchanged to fetch the next page. Omit on the first page.
The response `pagination` object contains `limit`, `has_more`, and (when `has_more=true`) `next_cursor`. There is no `offset` and no `total_count` — partners walk pages forward via cursor and use `has_more` to detect the last page.
**Polling for new messages**:
Use `GET /v1/users/:user_id/sync-stats` to check if new data has arrived (non-metered), then call this endpoint
with `start_date` to fetch recent messages — this endpoint is not metered, unlike `/v1/users/:user_id/query`.
**Examples**:
```
# List messages (lightweight, no body_text)
GET /v1/users/:user_id/messages
# List messages with content
GET /v1/users/:user_id/messages?expand=body_text
# Fetch specific messages with content
GET /v1/users/:user_id/messages?ids=msg_1Z,msg_2B,msg_3C&expand=body_text
# Filter by sender
GET /v1/users/:user_id/messages?sent_by=john@acme.com&expand=body_text
# Filter by resolved contact
GET /v1/users/:user_id/messages?entity_id=ent_xxx&expand=body_text
# Filter by contact - all messages where contact is sender or recipient
GET /v1/users/:user_id/messages?entity_id=ent_xxx&entity_scope=conversation&expand=body_text
```'
parameters:
- schema:
type: string
in: query
name: ids
required: false
description: Comma-separated message IDs (msg_xxx format)
- schema:
type: string
in: query
name: integration_id
required: false
description: Filter to a specific integration (int_xxx format)
- schema:
type: string
in: query
name: conversation_id
required: false
description: Filter to a specific conversation (conv_xxx format)
- schema:
type: string
minLength: 1
in: query
name: sent_by
required: false
description: Exact sender identifier (email address for Gmail/Outlook, Slack user ID for Slack)
- schema:
type: string
in: query
name: entity_id
required: false
description: Filter by resolved contact (ent_xxx format or UUID)
- schema:
type: string
enum:
- sender
- conversation
default: sender
in: query
name: entity_scope
required: false
description: 'Controls how entity_id matches. "sender" (default): messages sent BY entity. "conversation": messages where entity is sender or recipient (per-message match). Requires entity_id.'
- schema:
type: string
format: date
in: query
name: start_date
required: false
description: Messages after this date (YYYY-MM-DD format)
- schema:
type: string
format: date
in: query
name: end_date
required: false
description: Messages before this date (YYYY-MM-DD format)
- schema:
type: string
enum:
- 'true'
- 'false'
in: query
name: exclude_bots
required: false
description: 'Exclude bot/automated messages from results (default: false)'
- schema:
type: string
pattern: ^[0-9]+$
in: query
name: limit
required: false
description: Number of items to return (1-100, default 50)
- schema:
type: string
in: query
name: cursor
required: false
description: Opaque pagination cursor returned as `pagination.next_cursor` from a prior response. Pass it back unchanged to fetch the next page. Cursors are sort-key bound — a cursor from one endpoint cannot be reused on another.
- schema:
type: string
in: query
name: expand
required: false
description: 'Comma-separated list of fields to include. Valid options: body_text, body_html, raw, headers'
- schema:
type: string
format: uuid
in: path
name: user_id
required: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- true
data:
type: array
items:
type: object
additionalProperties: false
properties:
id:
type: string
pattern: ^msg_[A-Za-z0-9]+$
integration_id:
type: string
pattern: ^int_[A-Za-z0-9]+$
body_text:
anyOf:
- type: string
- type: 'null'
body_html:
anyOf:
- type: string
- type: 'null'
raw:
anyOf:
- type: string
- type: 'null'
headers:
anyOf:
- type: array
items:
type: object
additionalProperties: false
properties:
name:
type: string
value:
type: string
required:
- name
- value
- type: 'null'
subject:
anyOf:
- type: string
- type: 'null'
received_at:
type: string
parent_message_id:
anyOf:
- type: string
- type: 'null'
thread_id:
anyOf:
- type: string
- type: 'null'
thread_position:
anyOf:
- type: number
- type: 'null'
is_bot:
type: boolean
conversation_id:
anyOf:
- type: string
- type: 'null'
primary_entity_id:
anyOf:
- type: string
- type: 'null'
entity_ids:
type: array
items:
type: string
sender_name:
anyOf:
- type: string
- type: 'null'
sent_by:
type: string
minLength: 1
display_source:
anyOf:
- type: string
- type: 'null'
required:
- id
- integration_id
- subject
- received_at
- parent_message_id
- thread_id
- thread_position
- is_bot
- conversation_id
- primary_entity_id
- entity_ids
- sender_name
- sent_by
- display_source
pagination:
type: object
oneOf:
- type: object
additionalProperties: false
properties:
limit:
type: number
has_more:
type: boolean
enum:
- true
next_cursor:
type: string
required:
- limit
- has_more
- next_cursor
- type: object
additionalProperties: false
properties:
limit:
type: number
has_more:
type: boolean
enum:
- false
required:
- limit
- has_more
required:
- success
- data
- pagination
'400':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- false
error:
type: object
additionalProperties: false
properties:
code:
type: string
description: Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)
message:
type: string
description: Human-readable error message
details:
description: Optional additional error context
required:
- code
- message
required:
- success
- error
'403':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- false
error:
type: object
additionalProperties: false
properties:
code:
type: string
description: Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)
message:
type: string
description: Human-readable error message
details:
description: Optional additional error context
required:
- code
- message
required:
- success
- error
'404':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- false
error:
type: object
additionalProperties: false
properties:
code:
type: string
description: Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)
message:
type: string
description: Human-readable error message
details:
description: Optional additional error context
required:
- code
- message
required:
- success
- error
'500':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- false
error:
type: object
additionalProperties: false
properties:
code:
type: string
description: Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)
message:
type: string
description: Human-readable error message
details:
description: Optional additional error context
required:
- code
- message
required:
- success
- error
operationId: getV1UsersByUserIdMessages
x-operation-id-source: derived
/v1/users/{user_id}/messages/{id}:
get:
summary: Retrieve a message
tags:
- Messages
description: 'Retrieves a specific message by its ID (msg_xxx format). The message must belong to the authenticated user.
**Response fields**:
- `id`: Message ID (msg_xxx opaque format)
- `integration_id`: ID of the integration this message came from (int_xxx format)
- `body_text`: The message content
- `subject`: Email subject (for email messages)
- `received_at`: When the message was received
- `sender_name`: Human-readable sender name (null if unresolved)
- `sent_by`: Platform-specific sender identifier (email address for Gmail/Outlook, Slack user ID for Slack, Microsoft Graph user ID or email address for Microsoft Teams; ''unknown'' if unresolved)
- `parent_message_id`: Parent message ID for threaded replies (msg_xxx format, null for top-level)
- `thread_position`: Position within the thread (null for non-threaded messages)
- `is_bot`: Whether this message was from a bot/automated sender
- `conversation_id`: Conversation ID if applicable (conv_xxx format)'
parameters:
- schema:
type: string
format: uuid
in: path
name: user_id
required: true
- schema:
type: string
in: path
name: id
required: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- true
data:
type: object
additionalProperties: false
properties:
id:
type: string
pattern: ^msg_[A-Za-z0-9]+$
integration_id:
type: string
pattern: ^int_[A-Za-z0-9]+$
body_text:
anyOf:
- type: string
- type: 'null'
body_html:
anyOf:
- type: string
- type: 'null'
raw:
anyOf:
- type: string
- type: 'null'
headers:
anyOf:
- type: array
items:
type: object
additionalProperties: false
properties:
name:
type: string
value:
type: string
required:
- name
- value
- type: 'null'
subject:
anyOf:
- type: string
- type: 'null'
received_at:
type: string
parent_message_id:
anyOf:
- type: string
- type: 'null'
thread_id:
anyOf:
- type: string
- type: 'null'
thread_position:
anyOf:
- type: number
- type: 'null'
is_bot:
type: boolean
conversation_id:
anyOf:
- type: string
- type: 'null'
primary_entity_id:
anyOf:
- type: string
- type: 'null'
entity_ids:
type: array
items:
type: string
sender_name:
anyOf:
- type: string
- type: 'null'
sent_by:
type: string
minLength: 1
display_source:
anyOf:
- type: string
- type: 'null'
required:
- id
- integration_id
- subject
- received_at
- parent_message_id
- thread_id
- thread_position
- is_bot
- conversation_id
- primary_entity_id
- entity_ids
- sender_name
- sent_by
- display_source
required:
- success
- data
'400':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- false
error:
type: object
additionalProperties: false
properties:
code:
type: string
description: Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)
message:
type: string
description: Human-readable error message
details:
description: Optional additional error context
required:
- code
- message
required:
- success
- error
'404':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- false
error:
type: object
additionalProperties: false
properties:
code:
type: string
description: Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)
message:
type: string
description: Human-readable error message
details:
description: Optional additional error context
required:
- code
- message
required:
- success
- error
'500':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- false
error:
type: object
additionalProperties: false
properties:
code:
type: string
description: Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)
message:
type: string
description: Human-readable error message
details:
description: Optional additional error context
required:
- code
- message
required:
- success
- error
operationId: getV1UsersByUserIdMessagesById
x-operation-id-source: derived