SonarSend API Reporting & examples Examples

Examples

This page provides complete examples you can copy into Postman, curl, or an integration test.

Variables#

For examples below, assume:

BASE_URL=https://app.example.com
TENANT_SLUG=acme
API_KEY=sonar_xxxxx

1. Discover email types#

curl -X GET \
  "$BASE_URL/t/$TENANT_SLUG/api/email-types" \
  -H "X-API-Key: $API_KEY"

2. Discover sending identities#

curl -X GET \
  "$BASE_URL/t/$TENANT_SLUG/api/sending-identities" \
  -H "X-API-Key: $API_KEY"

3. Discover lists and segments#

curl -X GET \
  "$BASE_URL/t/$TENANT_SLUG/api/segments" \
  -H "X-API-Key: $API_KEY"

4. Discover templates#

curl -X GET \
  "$BASE_URL/t/$TENANT_SLUG/api/templates" \
  -H "X-API-Key: $API_KEY"

5. Create a content-first draft#

curl -X POST \
  "$BASE_URL/t/$TENANT_SLUG/api/broadcasts" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "name": "April newsletter",
    "email_type_key": "prospect_newsletter",
    "mta_config_key": "primary-mail",
    "include_segment_keys": ["vip-list"],
    "exclude_segment_keys": ["recent-unsubscribers"],
    "sending_identity_emails": ["ops@example.com"],
    "tags": ["newsletter", "subscriber"],
    "metadata": {
      "newsletter_type": "subscriber",
      "post_ids": [4729, 5102],
      "send_date": "2026-04-29"
    },
    "content": {
      "subject": "April updates",
      "body_html": "<html><body><h1>Hello</h1></body></html>",
      "body_text": "Hello"
    }
  }'

6. Create a template-mode draft#

curl -X POST \
  "$BASE_URL/t/$TENANT_SLUG/api/broadcasts" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "SB Newsletter — week of Apr 28",
    "email_type_key": "weekly_newsletter",
    "include_segment_keys": ["all-subscribers"],
    "tags": ["newsletter"],
    "metadata": { "post_ids": [4729, 5102] },
    "content": {
      "template_slug": "dog-ear-weekly",
      "subject": "Pricing strategies that actually move the needle",
      "template_binding": {
        "parameters": { "preview_text": "Pricing strategies that actually move the needle" },
        "sections": {
          "secondary_articles": [
            { "headline": "Why dashboards lie", "url": "https://example.com/dashboards", "description": "Most pricing dashboards…", "cta": "Read more" }
          ]
        },
        "slots": {}
      }
    }
  }'

7. Create a simple A/B draft#

curl -X POST \
  "$BASE_URL/t/$TENANT_SLUG/api/broadcasts" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "name": "April newsletter subject test",
    "email_type_key": "prospect_newsletter",
    "mta_config_key": "primary-mail",
    "include_segment_keys": ["vip-list"],
    "sending_identity_emails": ["ops@example.com"],
    "content": {
      "subject": "Fallback subject",
      "body_html": "<html><body>Fallback</body></html>",
      "body_text": "Fallback"
    },
    "variants": [
      {
        "id": "a",
        "name": "Variant A",
        "weight": 50,
        "content_overrides": {
          "subject": "April updates",
          "body_html": "<html><body>A</body></html>",
          "body_text": "A"
        }
      },
      {
        "id": "b",
        "name": "Variant B",
        "weight": 50,
        "content_overrides": {
          "subject": "What’s new this month",
          "body_html": "<html><body>B</body></html>",
          "body_text": "B"
        }
      }
    ]
  }'

8. Read the draft#

curl -X GET \
  "$BASE_URL/t/$TENANT_SLUG/api/broadcasts/BROADCAST_ID" \
  -H "X-API-Key: $API_KEY"

9. Update the audience#

curl -X PUT \
  "$BASE_URL/t/$TENANT_SLUG/api/broadcasts/BROADCAST_ID" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "include_segment_keys": ["vip-list", "openers-last-30-days"],
    "exclude_segment_keys": ["recent-unsubscribers"]
  }'

10. Schedule the broadcast#

curl -X POST \
  "$BASE_URL/t/$TENANT_SLUG/api/broadcasts/BROADCAST_ID/schedule" \
  -H "X-API-Key: $API_KEY"

11. List broadcasts with filters#

# Completed broadcasts from the last 6 months containing post 4729
curl -X GET \
  "$BASE_URL/t/$TENANT_SLUG/api/broadcasts?status=completed&metadata=%7B%22post_ids%22%3A%5B4729%5D%7D&since=2025-10-29" \
  -H "X-API-Key: $API_KEY"

# Draft and scheduled broadcasts tagged "newsletter"
curl -X GET \
  "$BASE_URL/t/$TENANT_SLUG/api/broadcasts?status=draft,scheduled&tags=newsletter" \
  -H "X-API-Key: $API_KEY"

12. Example list response shape (lean)#

For API-key callers, the lean list uses human-friendly keys and boolean content flags:

{
  "id": "33333333-3333-4333-8333-333333333333",
  "name": "April newsletter",
  "status": "draft",
  "tags": ["newsletter", "subscriber"],
  "metadata": { "newsletter_type": "subscriber", "post_ids": [4729, 5102] },
  "email_type_key": "prospect_newsletter",
  "mta_config_key": "primary-mail",
  "include_segment_keys": ["vip-list"],
  "exclude_segment_keys": ["recent-unsubscribers"],
  "sending_identity_emails": ["ops@example.com"],
  "content": {
    "subject": "April updates",
    "template_slug": "dog-ear-weekly",
    "template_binding": { "parameters": {}, "sections": {}, "slots": {} },
    "has_body_html": true,
    "has_body_mjml": true,
    "has_body_text": true,
    "has_template_snapshot": true
  }
}

13. Example detail response shape (full)#

{
  "id": "33333333-3333-4333-8333-333333333333",
  "name": "April newsletter",
  "status": "draft",
  "tags": ["newsletter", "subscriber"],
  "metadata": { "newsletter_type": "subscriber", "post_ids": [4729, 5102] },
  "email_type_key": "prospect_newsletter",
  "mta_config_key": "primary-mail",
  "include_segment_keys": ["vip-list"],
  "exclude_segment_keys": ["recent-unsubscribers"],
  "sending_identity_emails": ["ops@example.com"],
  "content": {
    "subject": "April updates",
    "template_slug": "dog-ear-weekly",
    "template_binding": { "parameters": { "preview_text": "…" }, "sections": {}, "slots": {} },
    "body_html": "<html>…</html>",
    "body_mjml": "<mjml>…</mjml>",
    "body_text": "…"
  }
}

14. Read the numbers after the send#

# One send, in full
curl -X GET \
  "$BASE_URL/t/$TENANT_SLUG/api/broadcasts/BROADCAST_ID/report" \
  -H "X-API-Key: $API_KEY"

# Which link did the work
curl -X GET \
  "$BASE_URL/t/$TENANT_SLUG/api/broadcasts/BROADCAST_ID/links" \
  -H "X-API-Key: $API_KEY"

# Headline KPIs for everything at once, freshly recomputed
curl -X GET \
  "$BASE_URL/t/$TENANT_SLUG/api/broadcasts/metrics-bulk?refresh=true" \
  -H "X-API-Key: $API_KEY"

See reporting.md for what the numbers mean and where the deeper views live.