Skip to navigation
API ReferenceMessaging

List Messages

Available by Request

List messages, narrowed by conversation or by one of the identifiers assigned when the message was created. Supply exactly one of conversationId, idempotencyId, or messageSid.

Use idempotencyId to confirm whether a send you issued was recorded, and messageSid to resolve a carrier identifier from a delivery receipt back to the Fortress message. To read a message whose Fortress id you already hold, use GET /messages/{messageId} instead.

This endpoint is part of our evolving API ecosystem. To explore availability for your integration, please contact our team.

Filtering, sorting, field selection, and pagination are not available on this endpoint. The fields, sort, filter, page, and limit query parameters are ignored.

Authentication

x-api-keystring
API Key authentication via header

Query parameters

conversationIdstringOptional
Return every message on this conversation, oldest first.
idempotencyIdstringOptional
Return the message created with this idempotency key.
messageSidstringOptional

Return the messages matching this carrier-assigned identifier.

Response

Expected response to a valid request. Returns an empty array when nothing matches.
isReactionboolean

True when an inbound message is a phone tapback reaction (for example Loved "See you at 3") rather than a written message (same rule as message.received isReaction). Always present on GET /messages and GET /messages/{messageId}; false for outbound messages.

idstringOptional
Unique identifier for the message.
conversationIdstringOptional
The conversation this message belongs to. Messages to the same recipient from the same property are grouped into a single conversation.
typeenumOptional

Direction and origin of the message. Messages created through POST /messages are always OUTBOUND.

Allowed values:
contentstringOptional
The body of the message. Limited to 1600 characters on send.
messageStatusstringOptional

Current delivery status. Statuses reported by the downstream carrier or email provider are passed through verbatim, so this is an open set rather than a fixed enum.

Statuses set by Fortress: CREATED, PROCESSING, FAILED, INVALID_PHONE_NUMBER, INVALID_EMAIL, RECEIVED, AUTOMATED, MASS_COMMUNICATION.

Statuses reported by the carrier: QUEUED, SENT, DELIVERED, UNDELIVERED, FAILED.

The terminal statuses for SMS are DELIVERED, UNDELIVERED, and FAILED. For email they are DELIVERED, FAILED, and REJECTED.

messageStatusReasonstring or nullOptional
Explanation for the current status. Populated when a message fails to send.
messageSidstringOptional
Identifier assigned by the downstream SMS carrier. Absent until the message has been accepted for delivery.
customerStatusstringOptional
Status of the recipient at the time the message was created, as recorded in Fortress.
idempotencyIdstringOptional

Caller-supplied key that uniquely identifies the send request. Reusing a key returns the original message rather than sending a duplicate.

isAutomatedbooleanOptional
True when the message was generated by a Fortress automation rather than a person.
needsHelpboolean or nullOptional

True while this message has an open needs-help flag. Absent on messages that have never been flagged.

needsHelpDetailsobject or nullOptional

Who raised the needs-help flag, why, and who resolved it. Absent on messages that have never been flagged. The flag details survive resolution, so this still describes the original request after needsHelp returns to false.

subjectstringOptional
Subject line. Email messages only.
emailAddressstringOptional
Recipient email address. Email messages only.
attachmentslist of objectsOptional
Media attached to the message.
metadatamap from strings to anyOptional

Caller-supplied metadata, plus sentAt and sentBy recorded by Fortress at send time.

organizationIdstringOptionalformat: "uuid"
customerIdstringOptionalformat: "uuid"
Set when the recipient is a customer.
prospectIdstringOptionalformat: "uuid"
Set when the recipient is a prospect.
userIdstringOptionalformat: "uuid"
The Fortress user the message was sent on behalf of.
createdAtdatetimeOptional
updatedAtdatetimeOptional

Errors

400
Bad Request Error