Email Broadcasting

Broadcasting sends one email to many recipients from a subscriber list. Each recipient gets a personalized email with their own merge tags. Forge handles batching, unsubscribe compliance, and bounce tracking automatically.

Lists

Lists are named groups of recipients. Each recipient stores:

• Email address (unique per list)
• Custom fields (JSON) — used for merge tags like {{first_name}} or {{plan}}
• Status — subscribed, unsubscribed, bounced, or complained

Creating a List

Go to System Settings → Email → Broadcasts → Lists → Create List.

Name your list (e.g., “Newsletter”, “Product Updates”) and add an optional description.

Adding Recipients

Single add: Use the Add Recipient form — enter email and any custom fields.

CSV import: Upload a CSV file. The first column must be email. All other columns become custom fields:

email,first_name,plan,company
alice@example.com,Alice,pro,Acme Inc
bob@example.com,Bob,free,Beta LLC
carol@example.com,Carol,pro,Gamma Co

Forge shows a preview of detected columns before importing. Duplicate emails are skipped.

Exporting

Click Export CSV to download all subscribed recipients — useful for backup or migration.

Sending a Broadcast

1. Go to System Settings → Email → Broadcasts → New Broadcast
2. Select a list
3. Write your subject and body with merge tags:

Subject:  Hey {{first_name}}, check out Forge v2!
Text:     Hi {{first_name}},\n\nWe just shipped some big updates...
HTML:     <h1>Hey {{first_name}}!</h1><p>We just shipped...</p>

4. Preview with a sample recipient to verify merge tags render correctly
5. Click Send Broadcast

Forge queues the broadcast and begins sending in batches. Progress updates in real-time.

How Batch Sending Works

1. Broadcast is queued → status: queued
2. Worker picks it up → status: sending
3. Recipients are processed in batches of 50 (configurable)
4. Each batch is sent concurrently
5. 1-second delay between batches (configurable) to avoid overwhelming the SMTP server
6. All batches complete → status: completed

You can cancel a broadcast while it is queued or sending. Already-sent emails cannot be recalled.

Unsubscribe Handling

Every broadcast email includes:

1. List-Unsubscribe Header (RFC 8058)

List-Unsubscribe: <mailto:unsubscribe@forge.yourdomain.com?subject=unsub%20list_abc%20alice@example.com>,
  <https://forge.yourdomain.com/api/v1/email/unsubscribe?list=list_abc&recipient=rec_xyz&token=sha256...>

Many email clients show an “Unsubscribe” button based on this header — no click into the email needed.

2. Unsubscribe Link in Body

Use the {{{unsubscribe_url}}} merge tag to include a one-click unsubscribe link:

<p>Don't want these emails? <a href="{{{unsubscribe_url}}}">Unsubscribe</a>.</p>

This is a required merge tag for all broadcasts. Forge validates that it is present in the template.

What Happens on Unsubscribe

• Recipient status changes to unsubscribed
• They are permanently excluded from future broadcasts to that list
• No confirmation page or “are you sure?” — one click, done (RFC 8058 compliant for bulk mail)
• Cannot be re-subscribed through CSV import (must use a dedicated re-subscribe flow)

Bounce Handling

Forge tracks SMTP delivery failures. After a recipient bounces:

Bounce #	Action
1	Logged, status unchanged
2	Logged, status unchanged
3	Auto-unsubscribed, status → bounced

This prevents repeatedly sending to invalid addresses and protects your domain’s sender reputation.

Broadcast Stats

While sending, the dashboard shows:

• Sent: 1,234 / 5,000
• Failed: 12
• Progress bar with percentage
• Estimated time remaining

After completion, the Deliveries tab shows per-recipient status: sent, failed, or skipped (unsubscribed/bounced).

Limits

Limit	Value
Max recipients per broadcast	50,000 (configurable)
Default batch size	50 recipients
Default batch delay	1,000 ms
Max concurrent broadcasts per identity	1
Unsubscribe source	One-click, RFC 8058 compliant

Example: Product Update Newsletter

1. Create list “All Users” with CSV import of your user database
2. Write the broadcast:

Subject:  {{first_name}}, Forge v2.0 is here

Text:
Hi {{first_name}},

We're excited to announce Forge v2.0! Here's what's new for {{plan}} plan users:

- Feature A
- Feature B

See the full changelog: https://forge.yourdomain.com/changelog

{{{unsubscribe_url}}}

3. Preview renders: “Alice, Forge v2.0 is here” / “Bob, Forge v2.0 is here”
4. Send → 5,000 recipients processed in ~100 seconds
5. Dashboard shows: 4,987 sent, 3 failed, 10 skipped (unsubscribed/bounced)