Skip to navigation
API ReferenceMessaging

Read Message

Available by Request

Read a single message, including its current delivery status and any attachments.

Attachment url values are generated per request and expire 15 minutes after the response is issued. Fetch the attachment promptly or re-read the message to obtain a fresh URL.

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

Field selection is not available on this endpoint. The fields query parameter is ignored.

Authentication

x-api-keystring
API Key authentication via header

Path parameters

messageIdstringRequired
The id of the message

Response

Expected response to a valid request
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

404
Not Found Error