Control engagement tracking

Samva records provider-observed Open and Click events for HTML email. Use organization defaults for your normal policy, per-send overrides for exceptions, and recipient opt-outs when an address must not be tracked. Suppression is separate: it decides whether a message may send at all.

Set organization defaults

Open and click tracking each default to enabled. Read or update them independently:

samva email tracking defaults get
samva email tracking defaults set --opens on --clicks off

The REST endpoints are GET /v1/email/tracking/defaults and PATCH /v1/email/tracking/defaults.

Override one send

Pass only the fields you want to override. An omitted field inherits its organization default.

await samva.messages.send({
  to: [{ email: "ada@example.com" }],
  channel: "email",
  email: {
    subject: "Your weekly report",
    html: '<p>Your report is ready.</p><a href="https://example.com/report">Open report</a>',
    tracking: {
      opens: false,
      clicks: true,
    },
  },
});

The same tracking object is available for transactional messages, scheduled messages, and campaign content. The CLI exposes --track-opens on|off and --track-clicks on|off on those send surfaces.

Honor a recipient opt-out

A recipient opt-out disables both Open and Click tracking for that normalized email address. It survives contact deletion and takes precedence over every send override and organization default.

samva email tracking recipient set ada@example.com --state opted-out
samva email tracking recipient get ada@example.com

The effective order is:

1. Recipient opt-out
2. Explicit per-send field
3. Organization default
4. Product default, enabled

Tracking opt-out does not suppress delivery. Use the suppression controls when an address must not receive mail.

Understand what Samva records

The email provider inserts the open pixel, rewrites eligible links, handles redirects, and publishes Open and Click observations. Samva supplies a tenant-specific HTTPS tracking hostname, applies your tracking policy, and stores the observations in the message timeline.

Raw observations are intentionally not collapsed. A provider retry is deduplicated, but separate provider observations remain separate timeline events. In one controlled proof, a single inbox open produced two raw Open observations. Image proxies, privacy features, caches, security scanners, and prefetching can all create or hide observations. An Open or Click is directional telemetry, not proof that a person intended the action.

Analytics reports two explicitly unique-message metrics:

• unique messages with at least one Open / delivered messages admitted with Open tracking enabled
• unique messages with at least one Click / delivered messages admitted with Click tracking enabled

Repeated observations for one message do not inflate these rates. A cohort with no eligible delivered messages returns 0, with a visible 0 / 0 eligible delivered denominator.

Provider constraints

• Engagement attribution requires one recipient per provider send. Samva enforces this on the engagement delivery path.
• Open tracking works only for HTML email. Include at most one {{ses:openTracker}} placeholder if you choose its position; otherwise the provider inserts the pixel.
• Click tracking works only for eligible HTML links and supports at most 250 tracked links in one message. Samva rejects content over that ceiling before provider send.
• The provider continues collecting Open and Click observations for 60 days after a send. Samva's retained timeline is the product history after ingestion.
• Tracking links use a tenant-specific samva.sh hostname and require HTTPS. The hostname carries no Samva session cookies or application state. On the Growth and Scale plans you can serve these links from a subdomain of your own domain instead; see Brand your tracking links.

See Deliverability for how to interpret engagement alongside authentication, bounces, complaints, and recipient consent.