--- title: Newsletters and campaigns | SendHQ Docs description: Keep consented contacts, target segments, write, test, schedule, and send broadcasts, read bot-filtered open and click reports, and publish a newsletter site. canonical: https://sendhq.cc/docs/newsletters last-updated: 2026-09-07 updated: 2026-09-07 --- # Newsletters and campaigns Keep consented contacts, target segments, write, test, schedule, and send broadcasts, read bot-filtered open and click reports, and publish a newsletter site. ## 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. ```json { "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/`. `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/`: a page with your title, description, accent color, and signup form, every issue sent with `web.enabled` at `/n//` (pinned issues first), and an RSS feed at `/n//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.