Managing Subscribers

Subscribers are the people you want to send emails to. Both Broadcast and Sequence emails require a subscriber to be present in the channel they are being sent from.

Transactional emails do not require a subscriber to be present in the channel they are being sent from.

Subscriber Information

For each subscriber, you can store the following information:

• Email address (required)
• First name
• Last name
• IP address
• Tags (comma separated list of tags)
• Active (true or false)
• Source (how the subscriber was added)
• Subscribed at date (required)
• Unsubscribed at date
• Custom data (JSON format)

The required values are indicated above.

For data protection reasons, you cannot alter the unsubscribed at date. For the subscribed at date, this is set automatically when a subscriber is entered manually.

When importing subscribers via a CSV or TSV file or adding subscribers via the API, the subscribed at date can be specified. The API takes ISO format: 2026-01-24 or 2026-01-24T09:30:00Z; a file import lets you declare whatever format your columns use.

Adding Subscribers

There are three ways to add subscribers to a channel:

1. Manual entry
2. CSV or TSV import (comma or tab separated values)
3. API integration

1. Adding subscribers manually

To manually add a subscriber, click on Subscribers in the sidebar, then click on Add subscriber (or use the dropdown menu and select Import subscribers).

Fill in the required fields and click Add subscriber.

2. Adding subscribers via CSV or TSV import

To add subscribers via a file, click on Subscribers in the sidebar, then click the dropdown menu next to “Add subscriber” and select Import subscribers.

Step 1: Upload your file

Choose CSV (comma separated values) or TSV (tab separated values), then upload your file. It’s easiest to export from a spreadsheet program like Google Sheets or Excel. You don’t need to match a fixed column layout: you’ll map your columns on the next step. If you’d like a starting point, download the CSV or TSV template from this page.

Broadcast reads the separator from your file’s header row, whichever box you dropped it on: a comma-separated file is read as CSV and a tab-separated one as TSV. Only when the header row does not tell (a single column, for example) does the file extension decide. The next step says how the file was read, for example Read as: comma-separated.

Step 2: Map your columns

After uploading, you’ll see a preview of your file alongside a column mapping table. For each column in your file, choose what it should become: Email, First name, Last name, Full name, Active, Source, Tags, Subscribed at, Unsubscribed at, a Custom field, or Ignore. Broadcast guesses the mapping from your header names, so review the guesses and fix anything that’s wrong.

Mapping a column to Custom field lets you store it in the subscriber’s custom data. Enter a key using dot notation for nested values (for example, country or profile.age). At least one column must be mapped to Email before you can import.

Dates: tell Broadcast what order your columns use

01/02/2026 is the 1st of February in most of the world and the 2nd of January in the United States. Nothing in a spreadsheet says which one your file means, so Broadcast will not guess: a parser that picks one is wrong for half of everyone, and it shifts every date by a month without any sign that it happened.

Instead, you say. Any column mapped to Subscribed at, Unsubscribed at, or a Custom field shows a Format dropdown next to it:

Pick the one matching your file and the dates import exactly as you intended. This is the fix for a spreadsheet that reformatted your dates on export: you no longer have to go back and re-export.

A few details worth knowing:

• Use four-digit years. 24/01/26 is refused rather than read as the year 26.
• Mixed columns are fine. An ISO value is always accepted, whatever format you chose, so a file with a few tidy rows among the messy ones imports cleanly.
• A row that doesn’t match the format you chose is reported rather than guessed at. For Subscribed at it falls back to the import date; for Unsubscribed at it is left empty; for a custom field it is stored as written.
• The import’s status page tells you how many dates it couldn’t read, so a wrongly-declared column is something you spot immediately and re-import, rather than discovering months later.

Declaring the format applies to what you are importing now. For dates already sitting in your channel from an earlier import, Channel Maintenance finds and repairs them.

Step 3: Choose a tag separator

If you map a column to Tags, choose how multiple tags are separated within that column: comma, pipe (|), or semicolon (;). For CSV files, wrap comma-separated tag values in quotes (for example, "vip,beta") so they aren’t split into separate columns; using a pipe or semicolon avoids the need for quoting.

Step 4: Preview and start the import

Review the preview of your first rows to confirm everything looks right, then click Start import. Broadcast processes the file in the background and updates the import’s status when it’s done.

3. Adding subscribers via API

Post an email address to the Subscribers API and Broadcast creates the subscriber in the channel that owns the token:

curl -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "email": "ada@example.com",
      "first_name": "Ada",
      "tags": ["newsletter"]
    }
  }' \
  https://your-broadcast-domain.com/api/v1/subscribers.json

A few behaviours are worth knowing before you wire this up:

• Posting an address that already exists returns 201 rather than an error, treats the person as resubscribed by clearing unsubscribed_at, and updates any attributes you sent.
• is_active is always set to true on create, even if the subscriber was previously deactivated.
• Pass double_opt_in: true to have Broadcast send a confirmation email instead of adding the subscriber straight to the list.

For the full parameter list, custom data handling, and how to carry over confirmation state when migrating from another platform, see Subscribers API.

4. Adding subscribers via an opt-in form

Opt-in forms are the hands-off option: you build a signup form in Broadcast, embed it on your site with a script tag, and subscribers add themselves. Forms can apply tags automatically, run double opt-in, and send a welcome email, so no code is involved beyond pasting the embed snippet.

See Opt-In Forms.

Segmentation

A segment is a dynamic group of subscribers defined by rules rather than a fixed list, so it re-evaluates every time it is used. You can match on standard subscriber fields (email, name, tags, engagement activity) and on any key stored in a subscriber’s custom data, so a segment for everyone whose plan is premium, or whose preferences.language is en, is a couple of rules.

See Segments for the rule builder, the available fields and operators, and how statistics are calculated. For custom data segmentation specifically, including supported operators and worked examples, see the Custom Data Segment Examples section of the API reference.

Viewing Subscribers

To view subscribers, click on Subscribers in the sidebar.

You can search for specific subscribers by entering their full or partial email address, or by entering their name. The system will try to find the closest match.

Search also matches any part of an email address, including the domain. Searching for gmail.com returns every subscriber on that domain, and searching a company domain such as northwind.com is a quick way to pull up everyone from one organisation.

Filtering by Tag

Subscriber tags are clickable. Select one on a subscriber’s profile to narrow the list to everyone carrying that tag, and Reset to clear it. You can also reach the same view directly with ?tag=vip on the subscribers URL.

Tag filtering combines with search, so “everyone tagged vip on a company domain” is one filter plus one search term. Both stay applied as you page through results.

Subscriber Detail Page

When you click on a subscriber, you will see their profile page with the following tabbed sections:

• Details: View and edit subscriber information including name, email, source, IP address, subscribed date, custom data, and topics
• Last Emails: See the most recent emails sent to this subscriber: broadcasts, sequence emails, and transactional emails (including ones sent with Send Email). Broadcast test sends are not tied to a subscriber, so they do not appear here
• Segments: View which segments this subscriber belongs to based on your segmentation rules
• Sequences: See which email sequences this subscriber is enrolled in and their progress

If the channel has Subscriber Topics, the profile shows each topic’s value: On, Off or Not set.

On the right side of the screen, you will see the Activity sidebar showing all recent activity associated with this subscriber, such as when they were added, updated, or received emails.

Engagement in the Activity Sidebar

The Activity sidebar records engagement as well as sends, so a single subscriber’s history answers “did they open it, and did they click?” without opening each broadcast in turn.

Alongside entries such as Sent, Added and Unsubscribed, you will see:

• Opened: the subscriber opened a specific broadcast, named in the entry
• Clicked: they clicked a link in that broadcast

Everything is ordered newest first and interleaved, so the sequence of events for that subscriber reads in order.

Two details worth knowing:

• Open and click tracking must be enabled on a broadcast for its engagement to appear here. Untracked broadcasts still show their Sent entry.
• Engagement is scoped to the channel you are viewing. If the same email address is subscribed to several of your channels, each channel’s Activity shows only its own sends and engagement.

Open tracking depends on the recipient’s email client loading images, so treat opens as an indicator rather than an exact count. See Email Metrics for how these events are collected.

Sending a One-Off Email

Send Email on a subscriber’s page writes to that one person, without creating a broadcast or a sequence. It is the right tool for answering a support question, following up on a reply, or re-sending something that bounced.

The email is sent as a transactional email, so it appears in the channel’s Transactional list and in this subscriber’s Last Emails tab, and it is delivered through whichever server handles transactional mail for the channel.

Active vs Unsubscribed Status

Subscribers can be marked as active or inactive. Subscribers can also be noted to have unsubscribed from the channel.

The difference between active/inactive and unsubscribed is important to understand:

• Active: The subscriber will receive all broadcasts, sequences, and transactional emails sent from the channel.
• Inactive: The subscriber will not receive emails. This status is set internally by you.
• Unsubscribed: The subscriber will not receive any emails sent from the channel, regardless of their active status. This status is typically set by the subscriber themselves when they click an unsubscribe link.

The easiest way to differentiate this is that the unsubscribed status is set by the subscriber themselves, while the active status is set internally by you.

For this reason, it is recommended that if you have different interactions with subscribers (e.g., transactional emails vs marketing emails), create the subscriber in two separate channels.

Mass Deactivation of Subscribers

Broadcast allows you to deactivate multiple subscribers at once by uploading a text file containing their email addresses. This feature is useful for cleaning up your subscriber list or removing inactive contacts in bulk.

How to Access Mass Deactivation

To access the mass deactivation feature:

1. Navigate to Subscribers in the sidebar
2. Click the Open options button (three dots icon) next to “Add subscriber”
3. Select Deactivate subscribers from the dropdown menu

Using the Mass Deactivation Tool

Once you click “Deactivate subscribers”, you’ll be taken to the deactivation page where you can upload your file:

File Requirements

Your email list file must meet the following criteria:

• File format: Plain text (.txt) file only
• Content: One email address per line
• Maximum addresses: 5,000 email addresses per file

Upload Process

1. Prepare your file: Create a plain text file with one email address per line
2. Upload the file: Click “Upload a file” or drag and drop your .txt file into the upload area
3. Review and process: Click “Upload and Process” to start the deactivation

Important Considerations

Before using the mass deactivation feature, be aware of the following:

• Permanent action: This action will permanently deactivate subscribers and cannot be undone
• Active subscribers only: Only active subscribers matching the email addresses will be affected
• Background processing: Processing will happen in the background and may take a few minutes
• Exact match required: Email addresses must exactly match those in your subscriber list

Best Practices for Mass Deactivation

• Backup first: Consider exporting your subscriber data before performing mass deactivations (when export feature becomes available)
• Test with small batches: For large lists, consider processing smaller batches first
• Verify email formatting: Ensure all email addresses are properly formatted and one per line
• Double-check your list: Review your email list carefully as the action cannot be undone

Deleting Subscribers (GDPR Redaction)

Broadcast provides comprehensive subscriber deletion functionality for GDPR compliance and data privacy requirements. When subscribers are “deleted,” their personally identifiable information (PII) is permanently redacted while preserving campaign statistics and analytics.

Individual Subscriber Deletion

You can delete individual subscribers directly from the subscriber details page:

1. Navigate to Subscribers in the sidebar
2. Click on the subscriber you want to delete
3. On the subscriber details page, scroll down to the Danger Zone section
4. Click the Remove Subscriber button
5. Confirm the deletion in the modal that appears

⚠️ Warning: This action is irreversible. Once deleted, subscriber personal data cannot be recovered.

Bulk Subscriber Deletion

For deleting multiple subscribers at once, Broadcast provides a bulk selection interface:

Using Bulk Selection

1. Navigate to Subscribers in the sidebar
2. Use the checkboxes next to subscriber emails to select multiple subscribers
3. Use the “Select All” checkbox in the table header to select all subscribers on the current page
4. Once subscribers are selected, a blue action bar will appear showing the number of selected subscribers
5. Click Remove to proceed with bulk deletion

Bulk Selection Features

• Selection count: The action bar displays how many subscribers are currently selected
• Clear selection: Click “Clear selection” to deselect all subscribers
• Page-level selection: The “Select All” checkbox selects all subscribers on the current page

Confirmation Process

When you click “Remove,” you’ll see a detailed confirmation modal that shows:

• Number of subscribers to be deleted
• List of subscriber emails (for selections of 10 or fewer)
• What will be removed: Email addresses, names, custom data, IP addresses, activity history
• What will be preserved: Campaign statistics, open/click rates, sequence performance data
• Warning message: Emphasizing that the action cannot be undone

What Gets Deleted vs. Preserved

Information That Gets Deleted (Redacted)

When a subscriber is deleted, the following information is permanently removed or anonymized:

• Email address: Replaced with an anonymized identifier (redacted-{id}@privacy-compliant.local)
• First and last names: Completely removed
• Custom data fields: All custom data is cleared
• IP addresses: Removed for privacy
• Personal preferences: Cleared
• Activity history details: Personal identifiers removed

Information That Gets Preserved

To maintain the integrity of your campaign analytics and reporting, the following data is preserved:

• Campaign statistics: Open rates, click rates, delivery statistics remain accurate
• Sequence performance data: Automation engagement metrics are maintained
• Aggregate reporting: Overall campaign performance and trends
• Subscriber ID and timestamps: For referential integrity in historical reports
• Revenue and conversion tracking: Business metrics remain intact

GDPR Compliance

This deletion system is designed to meet GDPR “right to be forgotten” requirements:

• Complete PII removal: All personally identifiable information is permanently deleted
• Data minimization: Only essential business data is retained
• Audit trail: Deletion actions are logged for compliance purposes
• Irreversible process: Ensures data cannot be accidentally recovered
• Statistical integrity: Maintains accurate business reporting while protecting privacy

Best Practices for Subscriber Deletion

• Verify selections carefully: Double-check your selection before confirming deletion
• Document requests: Keep records of deletion requests for compliance purposes
• Batch processing: For large deletions, consider processing in smaller batches
• Review before deletion: Use the confirmation modal to review exactly what will be deleted
• Consider alternatives: Evaluate if deactivation might be sufficient before permanent deletion

Important Considerations

• Irreversible action: Deleted subscriber data cannot be restored under any circumstances
• Campaign integrity: Historical campaign performance data remains accurate
• Legal compliance: Ideal for responding to GDPR data deletion requests
• Business continuity: Analytics and reporting functions are not disrupted
• Audit requirements: All deletion actions are logged for regulatory compliance

Purging All Subscribers

To empty a channel completely, for example to start again after a test import, go to Settings → General Channel Settings and use Purge All Subscribers in the Danger Zone at the bottom of the page. You need write access to subscribers in the channel to see it, and the System Settings permission to run it.

1. Switch on Confirm this is a broadcast channel used for testing. The purge is meant for test channels, so the button stays hidden until you do.
2. Read the list of what will be deleted, and the subscriber count in the panel’s title.
3. Click Purge All Subscribers, check the count again in the confirmation dialog, and confirm.

The purge then runs in the background, so you can leave the page:

• While it runs, the Danger Zone says a purge is in progress. Reload the page in a few minutes to check.
• Only one purge runs per channel at a time. Starting a second one while the first is running is refused.
• If it stops part-way, some subscribers may already be gone. Running the purge again is safe and removes the rest.

A purge sends the subscribers.purged webhook once when it finishes, or subscribers.purge_failed if it stops, instead of a subscriber.deleted event for every subscriber. See Webhooks.

Exporting Subscribers

Open the dropdown beside Add subscriber and choose Export subscribers (CSV). The file downloads straight away.

The export is whatever the list is currently showing. Search for northwind.com, or filter to a tag, and the export contains those subscribers and no others. To export everyone, clear the filters first. This is deliberate: the file you get should match the screen you were looking at.

One row per subscriber, with these columns:

Dates are written in ISO 8601 and always in UTC (2026-07-26T14:30:00Z), which every spreadsheet and script reads unambiguously. The dashboard itself shows dates and times in your browser’s time zone, so a time in the file can differ from the one on screen by your UTC offset.

Who can export

Exporting needs the Export subscriber data permission, granted per channel from Settings → Users. It is separate from View subscribers on purpose: reading the list a page at a time and taking the whole list away are different acts, and only the second one is worth restricting. Granting export automatically grants view, since exporting without reading makes no sense.

Large lists

An export covers up to 50,000 subscribers. Beyond that the file ends with a row telling you it was truncated: narrow the list with a search, a tag or a segment and export in pieces. The row is there so a short file is never mistaken for a complete one.

Exports are rate limited per signed-in user, across subscriber, broadcast and activity exports together: 10 a minute and 100 an hour by default. Someone downloading one file at a time never gets near it. To change the limits, set EXPORTS_PER_MINUTE and EXPORTS_PER_HOUR in /opt/broadcast/app/.env and restart.