Plugin Reference

This page lists everything in one place. To learn the ideas, start with Plugin Core Concepts.

Package files

A .broadcast-plugin file is a zip file.

Rules for dist/main.js:

• One ES module with export default definePlugin({ ... }). definePlugin is a global.
• No import, export ... from, import() or import.meta. Put all code in this file.
• No eval, Function() or new Function().
• No line longer than 2,000 characters, so no minified code.
• JavaScript only. Compile TypeScript first.

Manifest fields

Icon and listing

Both are optional. They go through review with your code, and the signature covers them.

{
  "icon": "assets/icon.png",
  "listing": {
    "features": ["One short line per feature"],
    "support": "help@example.com",
    "privacy": "https://example.com/privacy",
    "changelog": "What changed in this version."
  }
}

SVG is not accepted. Leave the corners square, because Broadcast rounds them. Use no words in the icon, and do not copy another brand.

A plugin with no icon shows its first letter on a colour tile.

Hooks

A name has 1 to 40 characters: lower case letters, digits and _, starting with a letter.

In a map hook, an entry is a function, or an object with a run function. mergeTags and liquidFilters can also be one function for all names.

Settings

ctx

Your own things

Subscribers

All are under ctx.broadcast.

A subscriber has these fields: id, email, first_name, last_name, is_active, subscribed_at, unsubscribed_at, confirmed_at, tags, custom_data, source, signup_ref, created_at and updated_at.

Good to know:

• Without a limit, subscribers.list gives up to 100 people.
• A limit over 100 or a cursor needs the export permission. Then one page can have 1,000 people.
• update merges custom_data with the old value. It cannot change the email or consent.
• A custom_data key that holds a topic is refused with forbidden, in update and bulkUpsert. See Topics.
• bulkUpsert items have email, first_name, last_name, custom_data and tags. It updates people who exist. To create people, it needs create, and a suppressed address is stored as inactive.

Tags

Topics

A topic is a subscriber’s consent, and it is stored in a tag or a custom_data key. No plugin can change it. If a tag matches a topic tag of the channel, without regard to case, Broadcast refuses the write with the code forbidden:

• tags.add and tags.remove throw, and change nothing. This is also true if only one tag in the list is a topic.
• tags.bulkAdd, tags.bulkRemove and subscribers.bulkUpsert refuse that item, and go on with the others. The item has "ok": false and the code.

Catch the error if the rest of your work must go on:

try {
  await ctx.broadcast.tags.add({ subscriber_id: id, tags: [tag] });
} catch (error) {
  if (error.code !== "forbidden") throw error;
  ctx.log.warn(`Tag ${tag} was refused.`);
}

Tag changes are safe to repeat.

Broadcasts, sequences and segments

Summaries have no email bodies and no recipient lists.

Events

fetch

fetch(url, options) works as usual, for declared hosts only. The call goes through Broadcast’s network gate, which refuses private addresses and does not follow redirects.

Permissions

Basic

Every plugin has these. Do not declare them: its own settings, storage, logs and events, and the channel name.

With no subscribers permission, a plugin’s event.data holds only fields that are not personal. See Events Hook.

Standard

Sensitive

Elevated

An admin must turn these on for each channel.

Never available

sql, files, env, process, subscribers:resubscribe, suppressions:write, email:recipients and email:unsubscribe. If you declare one, the manifest is refused.

Network hosts

A host must be a public DNS name with at least two parts. These are refused: IP addresses, localhost, and names that end in .local, .localhost, .internal, .lan, .home, .corp, .intranet, .test, .invalid, .example or .arpa. Write the host only, with no https://.

Limits

Time

Size

Rates

Storage

Memory

Logs

Packages

Draft tests