Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Find content risks before sending, measure delivery truth at aggregate level, and export recipient evidence for reconciliation.

​
Prerequisites

  • A StackShift API key
  • A template and version for diagnostics
  • Mail activity for meaningful analytics or exports

​
Workflow

1
Render template diagnostics with representative data before activating or sending a version.
2
Query analytics over 24 hours, 7, 30, or 90 days, or a custom range up to 90 days.
3
Filter by sender domain, template, or event and compare MTA acceptance with recipient delivery evidence.
4
Create an asynchronous recipient-delivery JSONL export, wait for ready, verify its checksum, and download it before expiry.

​
Rendered template diagnostics

  • Checks include long or all-capital subjects, missing text or HTML, oversized HTML, and no visible content.
  • Active elements, invalid or unsafe links, insecure links, missing image alternative text, and remote-image risk are reported.
  • Findings have info, warning, or error severity and do not send a message.

​
Analytics meaning

  • Summary and series cover queued, MTA-accepted, delivered, delayed, bounced, failed, suppressed, and complained recipients.
  • The response also covers OTP, scheduling, batches, attachments, inbound intake, webhook reliability, comparisons, rates, template usage, and insights.
  • Delivery rate is delivered divided by MTA-accepted. Delivered means recipient MX acceptance, not guaranteed inbox placement or human reading.

​
Optional open and click tracking

  • Tracking is off by default and available only when enabled by your deployment. Mail Analytics manages workspace defaults; campaign settings and the tracking.opens / tracking.clicks send fields override them independently.
  • API, template, batch, scheduled, and SMTP messages share tracking behavior. Plain-text emails, OTPs, and template/campaign tests do not collect engagement.
  • GET /mail/messages/{id}/engagement and GET /mail/campaigns/{id}/engagement return total/unique counts, suspected automated counts, top links, and first/last timestamps. Open counts are approximate and never prove a human read the email.
  • The dashboard rate uses engaged delivered messages divided by delivered messages with that tracking type enabled, restricted to messages created in the past 90 days. Zero denominators show unavailable. Automated activity is included and separately identified.
  • Single-recipient messages report recipient scope; shared To/Cc/Bcc messages report message scope. IP, raw user-agent, device, and location are not stored in engagement reports.
  • Engagement events are mail.message.opened and mail.message.clicked. Subscribe through the existing signed webhook system; events use stable IDs and consumers must deduplicate retries.
  • Details and internal webhook copies expire after 90 days. Campaign aggregates remain. Click redirects retain an encrypted destination so old links can work, without a message/campaign association after expiry. Your own webhook copies remain your responsibility.
  • Only HTTP(S) links are rewritten, with a maximum of 100 distinct tracked links per email. Fragments, mailto, tel, unsubscribe links, and anchors with data-ss-no-track are excluded.

​
Branded tracking domains

  • Mail Domains can add one dedicated tracking subdomain beneath a verified sending domain when branded tracking is available.
  • Publish the displayed DNS-only CNAME and ownership TXT at _stackshift-mail.<tracking-host>, then verify DNS and HTTPS. Certificate issuance is limited to verified hostnames.
  • New sends use an active branded host or fall back to the shared tracking host. Disabling the domain for new sends preserves existing links while DNS ownership remains valid. Revocation intentionally disables existing links.
  • Keep the CNAME and TXT records in place; health is rechecked automatically. Changing DNS or deleting the sending domain can stop old links.

​
Recipient-delivery exports

  • Exports are asynchronous recipient_delivery JSONL records with recipient status and SMTP disposition evidence.
  • Ready exports include record count, byte size, checksum, completion time, and expiry.
  • Objects are encrypted with the production mail-export KMS key and removed after seven days.

​
Expected result

Operators can distinguish content quality, aggregate delivery health, and recipient-level SMTP evidence without conflating MTA acceptance with delivery.

​
Common failures

  • Missing template variables
  • Requesting more than 90 days
  • Downloading an export before ready or after expiry
  • Treating MTA acceptance as inbox placement

Templates and OTP

Create versioned templates, preview and test them, send from a template, and use the built-in one-time-code challenge flow.

Events, webhooks, and timelines

List mail events, inspect per-message timelines, subscribe webhooks, rotate secrets, retry deliveries, and verify webhook signatures.

Bounces, suppressions, and reputation

Handle hard and soft bounces, workspace-scoped suppressions, sending limits, warmup stage, domain reputation, and reputation events.