# How to send a topic digest email How to send a topic digest email: one campaign, where each subscriber gets the sections for the topics they follow. A topic digest is one campaign whose email is put together per subscriber. You upload a section for every topic — a postcode area, a job category, a town, a product line — and each subscriber receives the sections for the topics they follow, in one email. A property site can send "new sold prices in your areas" to thousands of people following thousands of areas as a single campaign, with one report, instead of a campaign and a segment per area. ## How it works A subscriber follows a topic by holding a [tag](https://sendbeam.io/docs/tags) of the same name — the topic `Area: AL1` goes to everyone tagged `Area: AL1` (upper or lower case makes no difference). Where the email says `{{digest}}`, each recipient gets their sections, one after another. Everything else is an ordinary campaign: the audience you choose (everyone, a list or a segment) is narrowed to the people following at least one topic, and unsubscribe links, suppressions, sending pace, tracking and the report work as they always do. ## Letting people choose topics The simplest way is a signup form with a **Tag subscribers** rule. On the form's settings, pick the field that holds the topic and how to name the tag — `Area: {value}` with upper case turns a visitor's `al1` into the tag `Area: AL1`. Tags build up: when the same person signs up again for another area, they get a second tag and follow both. The field itself keeps only the latest answer, which is why the digest goes by tags. You can also tag people any other way — by hand, in an [import](https://sendbeam.io/docs/contacts/importing), from an automation, or through the API. Through the API, a form's rules are its `tag_rules`: `[{"field": "district", "template": "Area: {value}", "case": "upper"}]`. ## Creating the digest Create a campaign with a `digest` setting and a `{{digest}}` tag in its HTML. `max_sections` caps how many sections one email carries (1 to 50, 10 if you leave it out); people following more get the first ones by position, and `{{digest_more}}` tells them how many more there were. ``` curl -X POST https://sendbeam.io/api/v1/campaigns \ -H "x-api-key: $SENDBEAM_API_KEY" -H "Content-Type: application/json" \ -d '{ "name": "Area updates · October", "subject": "New sold prices in {{digest_titles}}", "from_email": "updates@example.com", "send_to_type": "all", "digest": { "max_sections": 5 }, "html_content": "

Hi {{first_name|there}},

{{digest}}

Unsubscribe

" }' ``` An existing draft becomes a digest with `PATCH /api/v1/campaigns/{id}` and `{"digest": {"max_sections": 5}}`; `{"digest": null}` turns it back into an ordinary campaign. ## Uploading the sections Send the sections to `PUT /api/v1/campaigns/{id}/topics`, up to 500 per request — a large digest is several requests. Uploading a topic again replaces it. Each section has the `topic` (the tag name), its `html`, an optional `title` (for `{{digest_titles}}` and the report), optional plain `text`, and an optional `position` to order sections within an email. ``` curl -X PUT https://sendbeam.io/api/v1/campaigns/$CAMPAIGN_ID/topics \ -H "x-api-key: $SENDBEAM_API_KEY" -H "Content-Type: application/json" \ -d '{ "topics": [ { "topic": "Area: AL1", "title": "AL1", "html": "

3 new sold prices in AL1

…" }, { "topic": "Area: MK5", "title": "MK5", "html": "

12 new sold prices in MK5

…", "position": 1 } ] }' ``` `GET` on the same address lists what is uploaded, and `DELETE` removes topics by name, or all of them with `?all=true`. Sections can change while the campaign is a draft or scheduled. If your workspace [requires approval](https://sendbeam.io/docs/campaigns/sending), any change to the sections sends the campaign back for approval, the same as an edit to the email. > Only upload sections that have something to say. Someone whose topics have no section this > time is simply not in this send — they never get an empty email. > ## Checking before you send - **Who it reaches.** The campaign page and `GET /api/v1/campaigns/{id}/audience` count only the people following at least one uploaded topic. - **What one person gets.** A [test send](https://sendbeam.io/docs/campaigns/sending) to a chosen contact carries that contact's own sections; without a contact, it carries the first sections by position. - **The send gate.** A digest without a `{{digest}}` tag, or without any sections, is refused with `code: "digest_incomplete"`. ## Merge tags These work in a digest's subject, HTML and text, alongside every ordinary [merge tag](https://sendbeam.io/docs/campaigns/merge-tags): - `{{digest}}` — the recipient's sections. In the text version, each section's `text`, or its HTML as plain text when it has none; in the subject, their titles. - `{{digest_titles}}` — the titles of the sections in this email, comma-separated. Good in a subject line: *New sold prices in AL1, MK5*. - `{{digest_count}}` — how many sections this email carries. - `{{digest_more}}` — how many more topics the person follows beyond `max_sections`; `{{digest_more|0}}` sets what to show when there are none. Sections can use ordinary merge tags too, such as `{{first_name}}`. The [web version](https://sendbeam.io/docs/campaigns/merge-tags) of a digest shows each reader the sections their email carried. ## The report The campaign page adds a **Topic digest** panel: for each topic, how many people's emails carried it, and how many of them opened and clicked. The full list is in `GET /api/v1/campaigns/{id}/report` under `topics`. Totals, links and devices are the campaign's, as for any campaign. ## Limits - Up to 10,000 topics per digest, and 500 per upload request. - A section's HTML up to 100,000 characters, its text up to 50,000, a topic name up to 100. - Up to 50 sections per email (`max_sections`). - [Duplicating](https://sendbeam.io/docs/campaigns/duplicating) a digest keeps the digest setting but not the sections: they belong to that send, so upload the new send's. --- Source: https://sendbeam.io/docs/campaigns/topic-digests