Reference Data

Most integrations should begin by reading reference data before creating a broadcast.

The external API uses public keys and email addresses for cross-resource references.

Email types#

List email types#

GET /api/email-types
Copy

Required scope:

• sending-identities:read

Example response (wrapped in the standard list envelope):

{
  "data": [
    {
      "id": "5aa0c1c8-8b1a-4a8a-b88d-1f6d6c4f3c31",
      "tenant_id": "8d1b6d8d-9d8b-42f4-9d34-8f7f84b19c80",
      "type_key": "prospect_newsletter",
      "display_name": "Prospect newsletter",
      "description": "Top-of-funnel marketing email",
      "utm_campaign_prefix": "prospect",
      "category_id": null,
      "sort_order": 10,
      "active": true,
      "list_id_enabled": true,
      "created_at": "2026-04-22T16:00:00.000Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
Copy

Use in broadcast payloads:

• email_type_key (an email type’s type_key)

Sending providers#

A broadcast may name a delivery path with mta_config_key, and one is not required — SonarSend resolves an eligible path from the email type and sending identity when you omit it.

The provider configurations themselves are not readable over the API. If you do want to pin a path, copy the key from the app where sending providers are configured and store it in your own config alongside the other public keys.

Sending identities#

List sending identities#

GET /api/sending-identities
Copy

Required scope:

• sending-identities:read

Example response:

Example response (wrapped in the standard list envelope):

{
  "data": [
    {
      "id": "6a04d7ab-94f4-4f40-a0d8-8dc87eaa8a33",
      "tenant_id": "8d1b6d8d-9d8b-42f4-9d34-8f7f84b19c80",
      "email_address": "ops@example.com",
      "display_name": "Ops",
      "reply_to": null,
      "email_type_ids": ["5aa0c1c8-8b1a-4a8a-b88d-1f6d6c4f3c31"],
      "sending_domain_id": "9c2b1a0e-2f3d-4c5b-8a7e-1d2c3b4a5e6f",
      "tracking_domain": "click.example.com",
      "default_mta_config_id": null,
      "verified_mta_config_ids": [],
      "active": true,
      "created_at": "2026-04-22T16:00:00.000Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
Copy

An identity can serve several email types, so the field is email_type_ids (an array), not email_type_id.

Use in broadcast payloads:

• sending_identity_emails

Lists and segments#

Lists are static segments. Segments are dynamic audiences.

List all lists and segments#

GET /api/segments
Copy

Required scope:

• lists:read, segments:read, or both depending on what should be visible to the key

Example response for API-key callers:

[
  {
    "tenant_id": "8d1b6d8d-9d8b-42f4-9d34-8f7f84b19c80",
    "segment_key": "vip-list",
    "name": "VIP List",
    "type": "static",
    "member_count": 125,
    "member_count_total": 125,
    "member_count_evaluated_at": "2026-04-22T16:00:00.000Z"
  },
  {
    "tenant_id": "8d1b6d8d-9d8b-42f4-9d34-8f7f84b19c80",
    "segment_key": "openers-last-30-days",
    "name": "Openers last 30 days",
    "type": "dynamic",
    "member_count": 814,
    "member_count_total": 970,
    "member_count_evaluated_at": "2026-04-22T16:00:00.000Z"
  }
]
Copy

Use in broadcast payloads:

• include_segment_keys
• exclude_segment_keys

Get one list or segment#

GET /api/segments/:segment_key
Copy

Example:

GET /api/segments/vip-list
Copy

Templates#

Templates are MJML body documents with typed schemas (parameters, sections, slots). Discover available templates before creating template-mode broadcasts. See template-mode.md for the full binding flow.

List templates#

GET /api/templates
Copy

Required scope:

• templates:read

Returns a lean shape by default (slug, name, format, schema counts). Pass ?full=true for complete bodies and schemas.

Example response:

[
  {
    "id": "187d6bd1-…",
    "slug": "dog-ear-weekly",
    "name": "Dog-Ear Weekly",
    "format": "mjml",
    "parameter_count": 10,
    "section_count": 2,
    "slot_count": 1,
    "group_count": 6,
    "created_at": "2026-04-21T00:00:00.000Z",
    "updated_at": "2026-04-25T00:00:00.000Z"
  }
]
Copy

Use in broadcast payloads:

• content.template_slug

Get one template#

GET /api/templates/:slug
Copy

Example:

GET /api/templates/dog-ear-weekly
Copy