Skip to navigation
API ReferenceMessaging

Send Message

Available by Request

Send a message to a customer or prospect. Supply exactly one of customerId or prospectId. Supplying both is not rejected: customerId takes precedence and the prospectId you sent is ignored, so the message is attributed to the customer.

Fortress resolves the recipient’s contact details and property phone number, appends the message to the existing conversation with that recipient (creating one if none exists), and hands it to the carrier.

A 201 means the message was accepted, not that it was delivered. The returned messageStatus will be PROCESSING while delivery is in flight; poll GET /messages/{messageId} until it reaches a terminal status of DELIVERED, UNDELIVERED, or FAILED.

idempotencyId is required. Reusing a key returns the message created by the original request instead of sending a duplicate, so a retry after a network timeout is always safe.

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

Authentication

x-api-keystring
API Key authentication via header

Request

The message to send
contentstringRequired1-1600 characters
The body of the message.
idempotencyIdstringRequired
Uniquely identifies this send request. Reusing a key returns the original message rather than sending a duplicate.
customerIdstringOptionalformat: "uuid"

The customer to send to. Supply exactly one of customerId or prospectId. If both are supplied, customerId takes precedence and prospectId is ignored.

prospectIdstringOptionalformat: "uuid"

The prospect to send to. Supply exactly one of customerId or prospectId. If both are supplied, customerId takes precedence and prospectId is ignored.

metadatamap from strings to anyOptional

Arbitrary key/value data to store alongside the message. Returned unchanged on reads.

Response

The message was accepted for delivery.
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
404
Not Found Error
422
Unprocessable Entity Error