List all messages
GEThttps://api.postpress.ai/v1/messages
Return a paginated list of messages across all chats and accounts. Optional filters narrow the result set by date, sender, or account.
Authorization
X-API-KEYstringrequired
API key from your postpress dashboard. Sent as a request header.
Query parameters
cursorstringoptional
Pagination cursor returned by the previous page. Length ≥ 1.
beforestringoptional
ISO 8601 UTC datetime. Returns messages created strictly before this moment.
afterstringoptional
ISO 8601 UTC datetime. Returns messages created strictly after this moment.
limitintegeroptional
Page size. Between 1 and 250. Default 100.
sender_idstringoptional
Filter to messages from a specific sender id.
account_idstringoptional
Filter to messages from a specific linked account id.
Response 200 OK
objectstringMessageListrequireditemsarray of objectsrequiredMessages on this page, ordered by timestamp.
items array
objectstringMessagerequiredidstringlength ≥ 1requiredmessage_idstringlength ≥ 1provider_idstringrequiredaccount_idstringlength ≥ 1requiredchat_idstringlength ≥ 1requiredchat_provider_idstringrequiredsender_idstringrequiredsender_attendee_idstringlength ≥ 1requiredtimestampstringrequiredtextstringrequiredNullable when the message has no text body.
is_sendernumberrequired01attachmentsarray of objectsrequiredattachments array
imgobjectimg object
idstringrequiredtypestringrequiredfile_sizenumberunavailablebooleanrequiredmimetypestringurlstringurl_expires_atnumbersizeobjectrequiredsize object
widthnumberrequiredheightnumberrequiredstickerbooleanrequiredvideoobjectvideo object
idstringrequiredtypestringrequiredfile_sizenumberunavailablebooleanrequiredmimetypestringurlstringurl_expires_atnumbersizeobjectrequiredsize object
widthnumberrequiredheightnumberrequiredgifbooleanrequiredaudioobjectaudio object
idstringrequiredtypestringrequiredfile_sizenumberunavailablebooleanrequiredmimetypestringurlstringurl_expires_atnumberdurationnumbervoice_notebooleanrequiredfileobjectfile object
idstringrequiredtypestringrequiredfile_sizenumberunavailablebooleanrequiredmimetypestringurlstringurl_expires_atnumberfile_namestringrequiredlinkedin_postobjectlinkedin_post object
idstringrequiredtypestringrequiredfile_sizenumberunavailablebooleanrequiredmimetypestringurlstringurl_expires_atnumbervideo_meetingobjectvideo_meeting object
idstringrequiredtypestringrequiredfile_sizenumberunavailablebooleanrequiredmimetypestringurlstringurl_expires_atnumberstarts_atnumberrequiredUnix epoch; nullable.
expires_atnumberrequiredUnix epoch; nullable.
time_rangenumberrequiredDuration in seconds; nullable.
quotedobjectquoted object
message_idstringlength ≥ 1provider_idstringrequiredsender_idstringrequiredtextstringrequiredNullable when the quoted message has no text.
attachmentsarray of objectsrequiredattachments array
imgobjectimg object
idstringrequiredtypestringrequiredfile_sizenumberunavailablebooleanrequiredmimetypestringurlstringurl_expires_atnumbersizeobjectrequiredsize object
widthnumberrequiredheightnumberrequiredstickerbooleanrequiredvideoobjectvideo object
idstringrequiredtypestringrequiredfile_sizenumberunavailablebooleanrequiredmimetypestringurlstringurl_expires_atnumbersizeobjectrequiredsize object
widthnumberrequiredheightnumberrequiredgifbooleanrequiredaudioobjectaudio object
idstringrequiredtypestringrequiredfile_sizenumberunavailablebooleanrequiredmimetypestringurlstringurl_expires_atnumberdurationnumbervoice_notebooleanrequiredfileobjectfile object
idstringrequiredtypestringrequiredfile_sizenumberunavailablebooleanrequiredmimetypestringurlstringurl_expires_atnumberfile_namestringrequiredlinkedin_postobjectlinkedin_post object
idstringrequiredtypestringrequiredfile_sizenumberunavailablebooleanrequiredmimetypestringurlstringurl_expires_atnumbervideo_meetingobjectvideo_meeting object
idstringrequiredtypestringrequiredfile_sizenumberunavailablebooleanrequiredmimetypestringurlstringurl_expires_atnumberstarts_atnumberrequiredUnix epoch; nullable.
expires_atnumberrequiredUnix epoch; nullable.
time_rangenumberrequiredDuration in seconds; nullable.
is_forwardedbooleanreactionsarray of objectsrequiredreactions array
valuestringrequiredsender_idstringrequiredis_senderbooleanrequiredseennumberrequired01seen_byobjectrequiredMap of attendee id -> seen timestamp (string) or boolean.
seen_by object
<attendee_id>string or booleanhiddennumberrequired01deletednumberrequired01editednumberrequired01is_eventnumberrequired01deliverednumberrequired01behaviornumberrequiredProvider-specific behavior code; nullable.
event_typenumber012345678910111213originalstringrequiredrepliesnumberreply_byarray of stringsreply_by array
<attendee_id>stringparentstringlength ≥ 1subjectstringNullable.
message_typestringMESSAGEINVITATIONINMAILINMAIL_DECLINEINMAIL_REPLYINMAIL_ACCEPTattendee_typestringMEMBERORGANIZATIONOTHERattendee_distancenumber1234-1sender_urnstringreply_toobjectreply_to object
idstringlength ≥ 1requiredprovider_idstringrequiredtimestampstringrequiredsender_attendee_idstringlength ≥ 1requiredsender_idstringrequiredtextstringrequiredNullable.
cursorstringrequiredCursor for the next page; `null` when there are no more results.
Example request
curl --request GET \
--url 'https://api.postpress.ai/api/v1/messages?limit=100' \
--header 'X-API-KEY: pp_live_...' \
--header 'accept: application/json'Example response
{
"object": "MessageList",
"items": [
{
"object": "Message",
"id": "msg_01HXYZ4QK3WJ8FN3M6QH7TZ8GR",
"provider_id": "urn:li:msg:2-NTRkZDA4...",
"account_id": "acc_01HXYZ4QK3WJ8FN3M6QH7TZ8GR",
"chat_id": "chat_01HXYZ4QK3WJ8FN3M6QH7TZ8GR",
"chat_provider_id": "2-NTRkZDA4M2QtZDcxZS00YzY5...",
"sender_id": "ACoAACr-1eYBl...",
"sender_attendee_id": "att_01HXYZ4QK3WJ8FN3M6QH7TZ8GR",
"timestamp": "2026-05-17T09:42:11.000Z",
"text": "Sounds good - let's chat tomorrow.",
"is_sender": 0,
"attachments": [],
"reactions": [],
"seen": 1,
"seen_by": { "att_01HXYZ4QK3WJ8FN3M6QH7TZ8GR": true },
"hidden": 0,
"deleted": 0,
"edited": 0,
"is_event": 0,
"delivered": 1,
"behavior": 0,
"original": "{...raw provider payload...}"
}
],
"cursor": "eyJza2lwIjoxMDB9"
}Errors
Every error response follows the same envelope:
titlestringrequired
Short error title.
detailstringoptional
Human-readable explanation.
instancestringoptional
Request identifier for support.
typestringrequired
Error type identifier.
statusnumberrequired
HTTP status code.
401 Unauthorized13 types
Credentials are missing, expired, or otherwise invalid.
errors/missing_credentials- Some credentials are necessary to perform the request.errors/multiple_sessions- LinkedIn limits multiple sessions on certain Recruiter accounts. Use the cookie connection method.errors/invalid_checkpoint_solution- The checkpoint resolution did not pass successfully. Retry.errors/invalid_proxy_credentials- The provided proxy credentials are invalid.errors/checkpoint_error- The checkpoint does not appear to be resolvable.errors/invalid_credentials- The provided credentials are invalid.errors/expired_credentials- Credentials have expired. Reconnect the account.errors/insufficient_privileges- This resource is out of your API-key scopes.errors/disconnected_account- The account is disconnected from the provider service.errors/disconnected_feature- The service you're trying to reach is disconnected.errors/invalid_credentials_but_valid_account_imap- IMAP/SMTP credentials are invalid but the account is otherwise valid.errors/expired_link- This link has expired. Generate a new one.errors/wrong_account- The provided credentials do not match the correct account.
403 Forbidden9 types
Authenticated but the account is restricted or the action is not allowed.
errors/account_restricted- The account has been restricted by the provider.errors/account_mismatch- This action cannot be done with your account.errors/insufficient_permissions- Valid authentication but insufficient permissions to perform the request.errors/session_mismatch- Token user id does not match client session id.errors/feature_not_subscribed- The requested feature has not been subscribed or authenticated properly.errors/subscription_required- A subscription is required to use this feature.errors/unknown_authentication_context- An additional step seems necessary to complete login.errors/action_required- An additional step is required.errors/resource_access_restricted- You don't have access to this resource.
404 Not Found2 types
The provided `account_id` or `sender_id` could not be resolved.
errors/resource_not_found- The requested resource was not found.errors/invalid_resource_identifier- The provided identifier is not valid.
500 Internal Server Error3 types
Something went wrong on our side or with the upstream provider.
errors/unexpected_error- Something went wrong.errors/provider_error- The provider is experiencing operational problems. Retry later.errors/authentication_intent_error- The current authentication intent was killed after failure.
503 Service Unavailable5 types
postpress is temporarily unable to handle the request.
errors/no_client_session- No client session is currently running.errors/no_channel- No channel to client session.errors/no_handler- Handler missing for that request.errors/network_down- Network is down on the server side. Retry shortly.errors/service_unavailable- Service temporarily unavailable. Retry later.
504 Gateway Timeout1 types
The upstream provider did not respond in time.
errors/request_timeout- Request timed out. Retry, and contact support if it persists.
Updated May 2026