Skip to content
APIs.Dev
Get started

Broadcasts

View as Markdown
Open in

A broadcast is one message to an audience the file names, sent only to people who consented, and posted to a feed agents read.

A broadcast, from draft to sent

Filled: a state someone outside the run sees. Hollow: a private state, a step inside the run.

Broadcast or transactional

A message that delivers what a Customer bought, or answers its call, is a transactional send. Anything else to many people is a broadcast.

The messageIt isSo it
A receipt, a renewal notice, an edition a member paid forTransactionalGoes to each entitled reader, with no unsubscribe from what was bought
A price change, a sunset, a security noticeTransactional, by law or by the termsReaches every Customer it affects, whatever its choices
News of the product, an offer, a launchA broadcastReaches only contacts and Customers who consented, each copy with its unsubscribe

Each copy, and the feed

A copy is queued, sent, then delivered or bounced; a delivered copy may become opened, unsubscribed or complained.

Sending runs in each reader's timezone and locale. A send that would pass the plan's contacts or the spend cap waits, and nothing is cut short.

With feed, each sent broadcast also posts to the product's news page and its JSON feed. A Customer's agent reads it there, or through a Watch on Broadcast.sent, and never needs an inbox.

Audiences and consent

An audience is a list of plans and arrival routes. A plan name reaches its paying Customers; customers reaches all of them.

interest, forms and preorders reach contacts by how each arrived. Every audience is filtered at send time by consent and by suppression, never by a list you upload.

Each copy carries a one-click unsubscribe in its headers and its footer. An unsubscribe or a complaint suppresses the address within the minute, across every broadcast.

One announcement

The weekly brief tells members and its interest list about a new Issue type, approved by an editor and posted to its feed.

definition.ts
29 lines
import { define, generative } from 'apis.dev'

/** A weekly brief on the software companies that changed headcount, for members and their agents. */
export default define({
  name: 'briefs', domain: 'briefs.apis.dev',
  sources: {
    firms: { api: 'companyfacts.apis.dev', cost: { 'Company.search': 0.005 } },
  },
  Issue: {
    week: 'string!#', title: 'string', body: 'markdown',
    status: {
      draft:   { run: generative('This week in {firms}: who hired, who shrank') },
      review:  { in: 'drafted', role: 'editor' },
      publish: { in: 'reviewed', role: 'editor' },
      send:    { in: 'published', to: 'Member' },
    },
  },
  on: { 'every Mon 06:00': 'Issue.draft', 'Issue.published': 'Issue.send' },
  offer: {
    'Issue.list': 0, 'Issue.read': 0.25,
    Member: { month: 8, includes: { 'Issue.read': 'all' } },
  },
  broadcasts: {
    from: 'news',                                         // news@ on the product's Host
    audiences: { members: ['Member'], everyone: ['customers', 'interest'] },
    review: 'editor',
    feed: true,
  },
})

Your team reads each send with Broadcast.get on the Operator plane.

Response
HTTP/1.1 200 OK
Content-Type: application/json
X-Cost: price=0, currency="USD"
X-Request-Id: req_d14a7c0e93b2f6851a2c

{
  "id": "bc_4",
  "subject": "Hiring signals, now daily",
  "audience": "everyone",
  "state": "sent",
  "approvedBy": "editor",
  "reached": 1840,
  "filtered": { "noConsent": 212, "suppressed": 31 },
  "delivered": 1822,
  "bounced": 18,
  "complained": 1,
  "unsubscribed": 9,
  "feed": "https://briefs.apis.dev/news/bc_4"
}

Lead capture and the interest list

Forms on the generated site, and a tool for agents, that turn a visitor into a contact: confirmed, enriched at its price, synced to your CRM, kept with consent.

Legal pages and consent

Your terms and privacy notice rendered from your own text and the file's facts, accepted by digest, and a site that asks before any tag loads.