Control engagement tracking

Samva records Open and Click observations 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 defaultsCopy Anchor Link

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 sendCopy Anchor Link

Pass only the fields you want to override. An omitted field inherits the template, sending-domain, or organization setting, in that order.

import { createClient } from "samva";

const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });

await samva.email.send({
  to: [{ email: "ada@example.com" }],
  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.

Set a template's defaultCopy Anchor Link

A template can carry its own tracking default, which applies to every send of that template unless the send overrides it. Set only the fields the template should decide; an omitted field inherits the sending-domain or organization setting. Send null to clear the template's default.

In the dashboard, open the template in the editor and choose Sending defaults in the toolbar. Open tracking and click tracking each offer Inherit, On, and Off, and Inherit shows the value the field resolves to and where it comes from. The same block sets the template's default sender and reply-to. Hosted MCP exposes the field through templates_update.

samva templates update tmpl_abc123 --data '{"trackingDefault":{"opens":false,"clicks":false}}'
samva templates update tmpl_abc123 --data '{"trackingDefault":null}'

The REST endpoint is PATCH /v1/templates/{id} with the same trackingDefault field in data. The template response returns the current value as trackingDefault.

Honor a recipient opt-outCopy Anchor Link

A recipient opt-out disables both Open and Click tracking for that normalized email address. It survives contact deletion and takes precedence over send, template, sending-domain, and organization settings.

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. Template field
4. Sending-domain field
5. Organization default
6. Product default, enabled

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

Understand what Samva recordsCopy Anchor Link

When tracking applies, Samva inserts an open pixel, rewrites eligible links through your HTTPS tracking hostname, redirects each click, and records Open and Click observations in the message timeline.

Raw observations are intentionally not collapsed. A repeated report of the same observation is deduplicated, but separate observations remain separate timeline events, and a single inbox open can produce more than one Open observation. 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.

Samva flags likely automatic observations with machine: true and a machineReason, based on image proxies, security scanners, and unusually fast requests. These heuristics can misclassify activity. Flagged observations remain in the timeline and webhooks.

Analytics reports two explicitly unique-message metrics:

• unique messages with at least one non-machine Open / delivered messages admitted with Open tracking enabled
• unique messages with at least one non-machine 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.

Tracking dataCopy Anchor Link

Tracking records the full IP address seen on the request, its available country, city and network information, user agent, and observation time. A proxy can supply its own address instead of the recipient's. Samva retains this data under the same retention policy as other message events; it does not truncate the IP address. Include this collection in your own privacy disclosures and honor the recipient's tracking preference.

Tracking limitsCopy Anchor Link

• Each recipient's copy is delivered separately, so every Open and Click belongs to exactly one recipient.
• Open tracking works only for HTML email. To choose where the pixel goes, include at most one {{samva:openTracker}} placeholder; otherwise Samva places it for you.
• Click tracking works only for eligible HTML links, and at most 250 links in one email can be tracked. A send over that limit is rejected when you submit it, before anything is sent.
• Opens and clicks keep arriving for a while after a send; the message timeline keeps every observation Samva records.
• 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.