Newsletters and campaigns

Contacts and consent

Every subscribed contact carries a consent_basis: how that person agreed to receive your email. Add contacts with POST /api/v1/contacts, import up to 5,000 CSV rows per request with POST /api/v1/contact-imports, or collect them with a list's hosted double opt-in form. Only add people who asked for your email. A contact can never be resubscribed through the API; only the recipient can, by confirming a signup form.

Organize contacts with free-text tags (on create, with add_tags and remove_tags, from a tags CSV column, or in bulk with POST /api/v1/contacts/bulk) and custom fields, used in content as {{fields.plan}}. Define a field's label and type (text, number, or date) with PUT /api/v1/contact-fields/:key. GET /api/v1/contacts/export returns a CSV that imports back unchanged.

Segments

A segment is a saved set of up to 20 conditions joined by all or any: tags, list membership, status, signup source and date, recent opens and clicks, open counts, broadcasts in a row without an open, country, and custom fields. Preview the count and a sample before saving with POST /api/v1/segments/preview. A broadcast's audience.segment_id sends to the list members that match when it starts.

{
  "name": "Engaged pro customers",
  "match": "all",
  "conditions": [
    {
      "field": "fields.plan",
      "op": "equals",
      "value": "pro"
    },
    {
      "field": "opened",
      "op": "in_last_days",
      "value": 90
    }
  ]
}

Write and check a broadcast

Create a draft with POST /api/v1/broadcasts: one list, a sender on a verified domain, a subject, and content as html and text, markdown, a block document in content, or a published hosted template. Markdown and block content are rendered with the design in newsletter settings. Merge tags such as {{first_name | there}} are filled per recipient and escaped in HTML. Images uploaded with POST /api/v1/uploads/images are served publicly from https://sendhq.cc/i/<id>.

GET /api/v1/broadcasts/:id/checks runs the review the dashboard shows: sender verification, subject, preview text, size against Gmail's 102 KB clipping limit, postal address, merge tags without data, empty or shortened links, missing image descriptions, and leftover placeholder text. A broadcast with a block check cannot be scheduled. POST /api/v1/broadcasts/:id/test sends a copy marked [Test] to up to five addresses you name.

Send now, later, or to more people

POST /api/v1/broadcasts/:id/send starts it now. POST /api/v1/broadcasts/:id/schedule with scheduled_at (a minute to a year ahead) runs the checks and starts it within about a minute of that time; if it can no longer send then, it returns to a draft with the reason in lastError. Unschedule it to edit it again.

Set audience.limit to send to part of the audience first, with audience.order: "engaged" to start with the people who open and click most. POST /api/v1/broadcasts/:id/send-more later sends it to more people who have not received it, including people who joined since. Every message goes through the normal checks (verified domain, marketing plan, suppressions, unsubscribes, reputation, limits), carries one-click unsubscribe from the list and your postal address, and reaches each contact at most once.

Open and click tracking

Tracking is on by default and can be turned off per broadcast with tracking: { opens: false, clicks: false }. Opens are counted from a 1-pixel image and clicks from signed redirects through https://sendhq.cc/t/c/…; the unsubscribe link is never rewritten, and a redirect goes only to the link that was signed for that recipient, so it cannot be used as an open redirect. A click also counts as an open, since many readers block images.

Opens are an estimate, never proof that someone read a message. Privacy proxies and security scanners load images and follow links on their own, so SendHQ keeps apart requests that look automated: scanner and link-preview user agents, HEAD requests, data-center networks (Gmail's image proxy is allowed for opens), Apple Mail Privacy Protection prefetches, and clicks within seconds of sending. Those appear only as machine counts in GET /api/v1/broadcasts/:id/report and are left out of every rate, segment, and contact engagement number. The report also breaks results down by inbox provider and link, shows first opens and clicks hour by hour, and compares rates with your previous five broadcasts.

List cleanup and dormant contacts

List cleanup is on by default in PATCH /api/v1/newsletter-settings. A subscriber who received several broadcasts in a row without opening or clicking (6 by default) and has not engaged for a while (90 days by default) gets one email asking whether to stay subscribed. A week later, anyone who did not click to stay becomes dormant: still on the list and still exportable, but left out of broadcasts until they open or click again. Because opens are estimates, readers whose mail app blocks or prefetches images can look inactive; confirming on the page the stay button opens keeps them subscribed (link scanners that only open the page change nothing).

Newsletter sites

Turn on a list's site to publish https://sendhq.cc/n/<slug>: a page with your title, description, accent color, and signup form, every issue sent with web.enabled at /n/<slug>/<issue> (pinned issues first), and an RSS feed at /n/<slug>/feed.xml. A site needs the list's signup form on. Pages render the issue without any recipient's personal data and run no scripts. A list's welcome email is sent once to each person who confirms a signup.