How to send a topic digest email

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 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, 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": "[email protected]",
    "send_to_type": "all",
    "digest": { "max_sections": 5 },
    "html_content": "<p>Hi {{first_name|there}},</p>{{digest}}<p><a href=\"{{unsubscribe_url}}\">Unsubscribe</a></p>"
  }'

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": "<h2>3 new sold prices in AL1</h2>…" },
      { "topic": "Area: MK5", "title": "MK5", "html": "<h2>12 new sold prices in MK5</h2>…", "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, any change to the sections sends the campaign back for approval, the same as an edit to the 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 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:

• {{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 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 a digest keeps the digest setting but not the sections: they belong to that send, so upload the new send's.