API Reference: Messages

List Message Studio aggregates, inspect delivery status, and read safe cross-channel constituent communication history.

Overview

The Messages API has two related read models. Message endpoints inspect the drafts, schedules, and sent aggregates coordinated by Message Studio. Record Communications endpoints inspect the canonical cross-channel delivery timeline for one Team Constituent, including sends from Studio, Conversations, Automations, Wizards, Views, constituent authentication, reports, commerce, and supported external-provider history. Message endpoints require an outgoing-message feature permission (OUTGOING_MESSAGES_VIEW or a send permission); record Communications require CONSTITUENT_MESSAGE_HISTORY_VIEW, records:read, and permission to read the record.

Key Concepts

Outgoing Message — A draft, scheduled, sending, or sent message identified by its Simply ID. status is one of DRAFT, AWAITING_APPROVAL, APPROVED, SCHEDULED, SENDING, SENT, ERROR_SENDING.
Constituent communication delivery — The canonical per-delivery record of what Simply360 sent to one constituent. An OutgoingMessage may be its coordinating source, but direct workflow and Conversation sends use the same history without creating a parallel Outgoing Message.
Delivery method — deliveryMethod is EMAIL, SMS, WHATSAPP, or FACEBOOK. Email is delivered through Amazon SES and SMS through Twilio.
Delivery status — Per-message aggregate counts (delivered / bounced / complained) derived from recipient notification records.
Completeness — Canonical history is EXACT, PARTIAL, or METADATA_ONLY. Incomplete legacy evidence includes a completenessGapReason; clients must not infer missing addresses, content, or attachments.

List Outgoing Messages

GET /v1/messages supports status and deliveryMethod filters plus limit (1–100, default 25) and offset. Each item includes id, internalName, subjectLine, deliveryMethod, contentType, status, scheduledAt, and sentAt.

const messages = await s360.messages.list({
  status: 'SENT',
  limit: 25,
});

for (const msg of messages.data) {
  console.log(`${msg.id}: ${msg.deliveryMethod} ${msg.status}`);
}

curl -s "https://api.simply360.app/v1/messages?status=SENT&limit=25" \
  -H "Authorization: Bearer $S360_API_KEY"

Get a Message and Its Status

The status endpoint returns the message's current status plus aggregate recipient counts.

const message = await s360.messages.get('MSG0-1234-ABCD');
const status = await s360.messages.getStatus('MSG0-1234-ABCD');

console.log(`Status: ${status.data.status}`);
console.log(`Recipients: ${status.data.totalRecipients}`);
console.log(`Delivered: ${status.data.delivered}, Bounced: ${status.data.bounced}, Complaints: ${status.data.complained}`);

curl -s "https://api.simply360.app/v1/messages/MSG0-1234-ABCD/status" \
  -H "Authorization: Bearer $S360_API_KEY"

List One Constituent's Communication History

GET /v1/data-records/{dataRecordSimplyId}/communications returns a newest-first, keyset-paginated timeline. Filter with channelId or currentStateId, pass limit from 1–100, and use the opaque meta.nextCursor for the next page. The SDK method is dataRecords.listCommunications.

let cursor: string | undefined;

do {
  const page = await s360.dataRecords.listCommunications('WXYZ-5678-IJKL', {
    channelId: 'EMAIL',
    limit: 25,
    cursor,
  });

  for (const delivery of page.data) {
    console.log(
      delivery.constituentMessageDeliverySimplyId,
      delivery.sourceType,
      delivery.channelId,
      delivery.currentStateId,
      delivery.completeness,
    );
  }
  cursor = page.meta.nextCursor ?? undefined;
} while (cursor);

curl -s "https://api.simply360.app/v1/data-records/WXYZ-5678-IJKL/communications?channelId=EMAIL&limit=25" \
  -H "Authorization: Bearer $S360_API_KEY"

The integration-safe response contains public delivery and constituent Simply IDs, an optional Outgoing Message Simply ID, source type/source Simply ID, channel, current state, timestamps, completeness and its gap reason, sensitive-content classification, hasProtectedContent, and attachmentCount. It never contains the rendered subject/body, exact destination or sender address, attachment manifest/bytes, storage coordinates, bearer credentials, provider payloads, or internal numeric IDs.

GET /v1/data-records/{dataRecordSimplyId}/outgoing-messages and SDK listOutgoingMessages are deprecated compatibility aliases for that same metadata projection. They are not a separate history system.

Simply360's webapp and Simply Anywhere use GET /v1/data-records/{dataRecordSimplyId}/communications/protected to display the exact destination, safe rendered content, lifecycle events, and sent-attachment manifest promised to permissioned Team users. That route and the exact-version attachment-download route accept only authenticated first-party Team users or allowlisted Simply Anywhere OAuth clients. An ordinary API key or integration OAuth client receives 403 PROTECTED_HISTORY_AUTH_REQUIRED, even when it has the history permission. Reusable verification, reset, unsubscribe, reply, signed-download, and other bearer credentials are masked before any protected snapshot is stored, so protected history never reveals the original credential.

Archived and merged constituents retain their canonical timeline; meta.mergedConstituentSimplyIds explains the record lineage included in a survivor's response. Deleted-record history is restricted to Team Admins. Normal record deletion is not a communication-history erasure.

Message Templates

Simple reusable templates are managed via the Templates client (requires the OUTGOING_MESSAGES_TEMPLATES feature permission). Template content and design are authored in Message Studio; the API manages template metadata.

const templates = await s360.messageTemplates.list();
const tmpl = await s360.messageTemplates.get('TMPL-1234-ABCD');

await s360.messageTemplates.create({
  name: 'Welcome Email',
  description: 'Sent to new constituents',
  deliveryMethod: 'EMAIL',
  subjectLine: 'Welcome aboard',
});

Endpoint reference:

GET /v1/message-templates — list (filter with deliveryMethod; paginated).
POST /v1/message-templates — create. Body: name (required), description, deliveryMethod (default EMAIL), subjectLine, designFormat.
GET /v1/message-templates/{outgoingMessageTemplateSimplyId} — get.
PUT /v1/message-templates/{outgoingMessageTemplateSimplyId} — update name, description, and subjectLine.
DELETE /v1/message-templates/{outgoingMessageTemplateSimplyId} — archive (the template is archived, not destroyed).

Full outgoing-message template authoring (design JSON/HTML, previews, thumbnails, collection links) lives on the separate /v1/outgoing-message-templates surface — see API Reference: Message Templates.

Message Senders

Senders (verified email addresses and phone numbers used as the from) are exposed at GET /v1/message-senders. Each sender includes name, emailAddress or phoneNumber, and deliveryMethod. Sender verification is managed in the Simply360 dashboard.

Outgoing-Message Workspace Endpoints

The /v1/outgoing-messages surface backs Message Studio. Its read endpoints are standard tier:

Endpoint	Description
`GET /v1/outgoing-messages`	List outgoing messages for the selected team.
`GET /v1/outgoing-messages/sent`	List sent messages.
`GET /v1/outgoing-messages/{outgoingMessageSimplyId}`	Get outgoing-message detail.
`GET /v1/outgoing-messages/{outgoingMessageSimplyId}/stats`	Deliverability stats for one message.

Composition and deliverability administration are privileged tier: creating and updating messages (POST /v1/outgoing-messages, PUT .../{id}, PUT .../{id}/status), recipient subject/field links, send-readiness checks (GET .../{id}/send-readiness), test sends (POST .../{id}/test-send), saved layouts, suppressions, send-pauses, and A2P 10DLC compliance management.

Usage Notes

Message delivery is asynchronous. Poll the status endpoint to track delivery after a message is sent.
Delivery counts are derived from recipient notification records and may continue to update after sending.
To list everything sent to one constituent, use GET /v1/data-records/{dataRecordSimplyId}/communications. The older .../outgoing-messages path returns the same metadata and is deprecated — see API Reference: Data Records.
For two-way threaded messaging (chat, inbound email/SMS), use API Reference: Conversations instead.