Message Data Model

Data Model Overview

🏗️ Primary Entities

Messages: Individual communications sent or received via email, text, or direct mail

Delivery: Scheduling, send times, and delivery status tracking

Engagement: Opens, clicks, and read status (channel-dependent)

🔗 Key Relationships

Many-to-One: Message → Customer (each message belongs to one customer)

Many-to-One: Message → Campaign (messages may be linked to a campaign)

Many-to-One: Message → Tenant (each message belongs to one tenant)

Tip

Three Endpoints, One Schema: Messages are available through three separate endpoints by channel (messages/email, messages/text, messages/direct-mail), but all return the same 23-field schema. Fields that don’t apply to a channel are returned as null.

Note

Direct Messages: If both CAMPAIGN_ID and NOTIFICATION_ID are null, the message is a direct (non-campaign, non-notification) message sent individually to the customer or from the customer.

Tip

Incoming Messages: Messages can also be inbound (received from the customer). When MESSAGE_STATUS is Incoming, the message was initiated by the customer rather than sent by the business. The INCOMING_TEXT_SOURCE field (text channel only) indicates where the incoming message originated.

Field Specifications

Message Identification

Core identification fields linking messages to tenants, shops, and customers.

Field Name	Data Type	Description	Required
STEER_TENANT_ID	String (UUID)	Unique tenant identifier (parent organization)	Yes
STEER_SHOP_ID	String (UUID)	Shop location identifier	Yes
STEER_CUSTOMER_ID	String (UUID)	Customer identifier (message recipient)	Yes
STEER_MESSAGE_ID	String (UUID)	Unique message identifier	Yes

Campaign & Notification

Campaign association and notification classification.

Field Name	Data Type	Description	Required
CAMPAIGN_ID	String (UUID)	Associated campaign identifier (null for direct messages)	No
MARKETING_TYPE	String	Communication channel type	No
CAMPAIGN_NAME	String	Campaign display name	No
CAMPAIGN_TYPE	String	Campaign frequency type	No
NOTIFICATION_ID	Number	Associated notification identifier (null for direct messages and direct mail)	No
NOTIFICATION_TYPE	String	Notification classification (null for direct messages and direct mail)	No

Timestamps

Message lifecycle timing.

Field Name	Data Type	Description	Required
CREATED_AT	Timestamp	Message creation timestamp	Yes
SCHEDULED_AT	Timestamp	Scheduled send time (null if sent immediately or for direct mail)	No
SENT_AT	Timestamp	Actual send timestamp	No
DELIVERED_AT	Timestamp	Delivery confirmation timestamp	No

Delivery & Engagement

Delivery status and engagement metrics.

Field Name	Data Type	Description	Required
MESSAGE_STATUS	String	Current delivery/engagement status	Yes
OPENS_COUNT	Number	Total open count (email only)	No
CLICKS_COUNT	Number	Total click count (email only)	No
COUNT_OF_ATTACHMENTS	Number	Number of attachments (text only)	No
IS_STEER_FAVORITE	Boolean	Conversation-level flag indicating the entire customer conversation is “starred” or bookmarked for easy retrieval (email and text only)	No

Content

Message content fields.

Field Name	Data Type	Description	Required
SUBJECT	String	Email subject line (email only, null for text and direct mail)	No
TEXT	String	Message body text. For email: plain text without HTML formatting. For text: SMS body. Null for direct mail	No
INCOMING_TEXT_SOURCE	String	Source of incoming text message. Only populated when MESSAGE_STATUS is Incoming (text channel only, null for email and direct mail)	No

Field Enum Values

Message Status (Text)

• Scheduled: Message is scheduled for future delivery
• Queued: Message is queued for processing
• Sent: Message has been sent to the carrier
• Delivered: Message was successfully delivered
• Unsent: Message was not sent
• Failed: Message delivery failed
• Incoming: Inbound message received from customer
• Unsubscribed: The system marks the message when the customer sends a stop-word (e.g., “Unsubscribe”, “Stop”, “Cancel”)
• Deactivated: Phone number was deactivated by the carrier. The system records the message as failed, deactivates the phone number on the customer record, and blocks future messages to that number
• FailedByRestriction: Blocked by Steer messaging restriction settings (e.g., maximum messages allowed per customer per day)

Message Status (Email)

• Scheduled: Message is scheduled for future delivery
• Queued: Message is queued for processing
• Sent: Message has been sent
• Delivered: Message was successfully delivered
• Unsent: Message was not sent
• Failed: Message delivery failed
• Incoming: Inbound email received from customer
• Unsubscribed: Customer clicked the unsubscribe link in the email
• Opened: Email was opened by the recipient
• Bounced: Email bounced back (invalid address or mailbox full)
• FailedByRestriction: Blocked by Steer messaging restriction settings (e.g., maximum messages allowed per customer per day)

Message Status (Direct Mail)

• Scheduled: Mail piece is scheduled for production
• Processing: Mail piece is being produced and prepared for delivery
• Delivered: Mail piece was delivered
• Failed: Mail piece delivery failed

Campaign Type

• OneTime: Campaign runs once
• Repeat: Campaign runs on a recurring schedule

Marketing Type

• Text: SMS/text message
• Email: Email message
• Postcard: Physical postcard
• Letter: Physical letter

Notification Type

• AppointmentReminder: Reminder for an upcoming appointment
• AppointmentRequestMade: Notification that an appointment request was submitted
• AppointmentConfirmed: Confirmation that an appointment was accepted
• AppointmentDeclined: Notification that an appointment was declined
• OutBoundAppointmentNotification: Outbound appointment notification
• AppointmentMissed: Notification for a missed appointment
• AbandonedBooking: Follow-up for an abandoned booking
• WebFormProspect: Notification from a web form submission

Incoming Text Source

Applies only to text messages where MESSAGE_STATUS is Incoming:

• None: Source not specified
• Crm: Message received through CRM integration
• Widget: Message received through website widget

Channel Field Availability

Not all fields are populated for every channel. The following table shows which fields contain data per channel:

Field	Email	Text	Direct Mail
NOTIFICATION_ID	Yes	Yes	—
NOTIFICATION_TYPE	Yes	Yes	—
SCHEDULED_AT	Yes	Yes	—
OPENS_COUNT	Yes	—	—
CLICKS_COUNT	Yes	—	—
COUNT_OF_ATTACHMENTS	—	Yes	—
IS_STEER_FAVORITE	Yes	Yes	—
SUBJECT	Yes	—	—
TEXT	Yes	Yes	—
INCOMING_TEXT_SOURCE	—	Yes	—

Data Quality Notes

Null Values

Note

Expected Null Values

• CAMPAIGN_ID and CAMPAIGN_NAME / CAMPAIGN_TYPE are null for direct (non-campaign) messages
• NOTIFICATION_ID and NOTIFICATION_TYPE are null for direct messages and all direct mail
• SCHEDULED_AT is null if the message was sent immediately or for direct mail
• SENT_AT and DELIVERED_AT may be null if the message has not yet been sent or delivered
• OPENS_COUNT and CLICKS_COUNT are always null for text and direct mail
• COUNT_OF_ATTACHMENTS is always null for email and direct mail
• IS_STEER_FAVORITE is always null for direct mail; this is a conversation-level flag, not a message-level flag
• SUBJECT is always null for text and direct mail
• TEXT is always null for direct mail; for email it contains the body without HTML formatting
• INCOMING_TEXT_SOURCE is always null for email and direct mail; only populated when MESSAGE_STATUS is Incoming

Sample Record

Complete API response example with an email message record:

{
  "data": [
    [
      "f2e3d4c5-b6a7-8901-2345-6789abcdef01",
      "c3d4e5f6-a7b8-9012-3456-789abcdef012",
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
      "Email",
      "Welcome Back Follow-Up",
      "Repeat",
      null,
      null,
      "2025-06-15T10:30:00Z",
      "2025-06-15T09:00:00Z",
      "2025-06-15T10:30:00Z",
      "2025-06-15T10:30:05Z",
      "Delivered",
      3,
      1,
      null,
      false,
      "We miss you! Come back for a check-up",
      "Hi Sarah, it's been a while since your last visit. We'd love to see you again for a routine check-up.",
      null
    ]
  ],
  "metadata": {
    "rowType": [
      {"name": "STEER_TENANT_ID", "type": "text"},
      {"name": "STEER_SHOP_ID", "type": "text"},
      {"name": "STEER_CUSTOMER_ID", "type": "text"},
      {"name": "STEER_MESSAGE_ID", "type": "text"},
      {"name": "CAMPAIGN_ID", "type": "text"},
      {"name": "MARKETING_TYPE", "type": "text"},
      {"name": "CAMPAIGN_NAME", "type": "text"},
      {"name": "CAMPAIGN_TYPE", "type": "text"},
      {"name": "NOTIFICATION_ID", "type": "fixed"},
      {"name": "NOTIFICATION_TYPE", "type": "text"},
      {"name": "CREATED_AT", "type": "timestamp_ntz"},
      {"name": "SCHEDULED_AT", "type": "timestamp_ntz"},
      {"name": "SENT_AT", "type": "timestamp_ntz"},
      {"name": "DELIVERED_AT", "type": "timestamp_ntz"},
      {"name": "MESSAGE_STATUS", "type": "text"},
      {"name": "OPENS_COUNT", "type": "fixed"},
      {"name": "CLICKS_COUNT", "type": "fixed"},
      {"name": "COUNT_OF_ATTACHMENTS", "type": "fixed"},
      {"name": "IS_STEER_FAVORITE", "type": "boolean"},
      {"name": "SUBJECT", "type": "text"},
      {"name": "TEXT", "type": "text"},
      {"name": "INCOMING_TEXT_SOURCE", "type": "text"}
    ]
  }
}