Broadcast Docs
Back to main site
Coming in Broadcast 3.5. Until then, this page applies only to the Upcoming (edge) build.
On this page

Web Versions and Archive

A web version is a public page for one broadcast, with its own permanent URL. Readers can open it in a browser, and you can share it on social media or link to it from your website. The web versions of a channel come together in its web archive: a page that lists every published issue, with search, an RSS feed and a sitemap.

The web version is off until you turn it on, for one broadcast or as the default for new broadcasts. The page goes live when the send starts, so the View in browser link works from the first email on.

Turn on the web version of a broadcast

  1. Open the broadcast in the composer and go to the Settings tab.
  2. In the Web version card, turn on Publish a web version.
  3. Change the fields below if you want. All of them are optional.
  4. Save or send the broadcast as usual.
Field What it does
URL The end of the page’s URL (the slug). Broadcast makes it from the subject, for example the-spring-market-returns. A merge tag in the subject gives its fallback in the URL and the page title, or nothing. Use lower-case letters, digits and dashes. It is unique in the channel: a second issue with the same subject gets -2. You can change it until the broadcast is sent. After the send it does not change, so a link you shared never breaks.
Page title The title of the page, in the browser tab, search results and link previews. Empty: the subject.
Description The text that search engines and link previews show. Empty: the preheader.
Social image URL The image that link previews show (Open Graph and Twitter card). Use an http:// or https:// address. Empty: no image.
Add a “View in browser” link to the email A small link above the email that opens the web version. On by default.

The field in front of the URL shows where the page will be: the address of your Broadcast installation with /p/<channel slug>/, or your own domain when the channel has one (see Use your own domain).

To start every new broadcast with the web version on, use Publish a web version of new broadcasts in Settings → Web Archive. A duplicated broadcast keeps the switch and the page details, and gets its own URL. A retry of the failed recipients of a send has no web version of its own: its emails link to nothing new, and the issue is published only once.

Note

The web version is the same for everybody. Merge tags show their fallback, unsubscribe links are removed, and poll buttons ask the reader to subscribe. Do not put information for one subscriber in an email that has a web version.

What readers see

The page shows the email as your subscribers saw it, rendered for nobody in particular:

  • Merge tags show their fallback. {{ subscriber.first_name | default: "there" }} shows “there”. A merge tag with no fallback shows nothing.
  • Unsubscribe and preference links are removed, with their text. {{ unsubscribe_url }} and {{ preferences_url }} are empty, and the channel footer is not added.
  • Poll vote buttons (and other links to a plugin action, for example from Polls) point at the subscribe box on the page. A vote link is personal, so it cannot work for a reader who is not a subscriber.
  • {{ web_version_url }} links to the page itself.
  • Scripts are removed. The page runs no JavaScript at all: script tags, event handlers and javascript: links in the email HTML are removed, and the page is sent with a Content Security Policy that blocks scripts.

Around the email, Broadcast adds:

  • A bar at the top with the channel’s logo (or its name), a link to All issues when the archive page is on, and a Subscribe button when the pages have a subscribe form.
  • Links to the previous and next issue under the email, with their titles. Only published issues are linked.
  • The subscribe form that you chose in Settings → Web Archive, under the email.
  • A small footer with the channel name and a link to the RSS feed.

The bar and the archive page use the colours, font and logo of your brand kit (Settings → Brand Kit, see Drag-and-Drop Email Builder).

The page is in the channel’s default language, for every visitor. Its fixed texts (“All issues”, “Subscribe” and the others) come in the same 13 languages as the other public pages (see Channels).

Each page has its own head tags:

  • <title> and <meta name="description"> from the page title and the description.
  • A canonical URL, the page’s own address.
  • Open Graph tags (og:title, og:description, og:url, og:image, og:site_name, article:published_time) and a Twitter card. The card is summary_large_image when the page has a social image, else summary.
  • <meta name="robots" content="noindex, nofollow"> when the channel does not let search engines index the pages.

Head tags of the same kind in your own email HTML are removed, so the page never has two titles or two canonical URLs.

Manage a sent broadcast

When a broadcast with a web version is sending or sent, its page shows a Web version card above the details:

  • Public or Unpublished, the state of the page.
  • The URL, with Copy and Open.
  • Unpublish takes the page down. The URL then answers 410 Gone with the message “This issue is no longer available” and a link to all issues. The issue also leaves the archive, the RSS feed and the sitemap.
  • Publish again puts the page back at the same URL.
  • Page details changes the page title, the description and the social image URL after the send.
  • Views, the number of times the page was opened in the last 30 days.

Note

How views are counted. Broadcast counts the views on the server, one number per day. It sets no cookies and keeps no data about the visitor. Search engine crawlers, link preview bots and command-line tools are not counted.

Unpublish, Publish again and Page details need permission to edit broadcasts.

The archive, the feed and the sitemap

Each channel has these public addresses on your Broadcast installation:

Address What it is
https://<your Broadcast domain>/p/<channel slug>/<slug> The web version of one issue
https://<your Broadcast domain>/p/<channel slug> The archive page
https://<your Broadcast domain>/p/<channel slug>/feed.xml The RSS feed
https://<your Broadcast domain>/p/<channel slug>/sitemap.xml The sitemap
  • The archive page lists the published issues, newest first, 20 to a page, with each issue’s title, description and send date. It has a search box that finds issues by subject, and the subscribe form at the top when you chose one.
  • The RSS feed carries the 20 newest issues. Readers can follow your newsletter in a feed reader.
  • The sitemap lists every published issue, for search engines.

An issue is in the archive when it was sent (or partly sent) with the web version on, and is not unpublished. The issue page itself is public from the start of the send, also while the send runs and after it is paused or stopped. A draft, a scheduled broadcast and a broadcast without a web version have no public page: their URL answers 404.

A channel that has never had a broadcast with the web version on has no archive page and no feed: their URLs answer 404. The archive appears when you turn on the web version of the first broadcast.

The public pages accept 120 requests a minute from one IP address. More answer 429. To change the limit, set WEB_ARCHIVE_REQUESTS_PER_MINUTE in your .env file.

Open the archive at the top of Settings → Web Archive opens the archive page.

Settings → Web Archive

Settings → Web Archive holds the settings for the web versions of the channel.

Setting What it does
Publish a web version of new broadcasts The starting value of the switch in each new broadcast, in the composer and through the API. Existing broadcasts do not change. Off by default.
Show the archive page On by default. Off: the archive page and the RSS feed answer 404, and the bar on each issue has no All issues link. Each issue page still works.
Let search engines index the pages On by default. Off: every page says noindex, nofollow (in the page and in an X-Robots-Tag header), the sitemap is empty, and on your own domain robots.txt disallows everything.
Subscribe form on the pages One of the channel’s Opt-In Forms, shown under each issue and on the archive page. No subscribe form shows none.
Custom domain Your own domain for the pages. See below.

Use your own domain

You can serve the archive on your own domain, for example news.example.com. On that domain:

  • The archive page is at /, and each issue at /<slug>, for example https://news.example.com/the-spring-market-returns.
  • The feed is at /feed.xml, the sitemap at /sitemap.xml, and /robots.txt names the sitemap (or disallows everything when indexing is off).
  • The /p/<channel slug> addresses on your Broadcast domain redirect there (302), so links you already shared keep working. The redirect is not permanent, so the links work again at once when you remove the domain.
  • Nothing else of Broadcast is served there. Sign-in, the app, the API and every other path answer 404.

Set up the domain

  1. Go to Settings → Web Archive and type the domain in Domain, for example news.example.com. Save.
  2. Broadcast shows the DNS record to add. At your DNS provider, add a CNAME record. The name is the subdomain (news), and the value is the domain of your Broadcast installation.
  3. If you use Cloudflare, set the record to DNS only (grey cloud), so your server can get the certificate.
  4. Come back to Settings → Web Archive. Broadcast checks the record and tells you when the domain points to your server. A DNS change can take up to an hour.
  5. Get the certificate for the domain. Broadcast gets a certificate for a new domain when the application reloads. Click Reload now in the certificate notice (or Reload App under Application → Host System). The reload takes about a minute. On a manual installation, add the domain to TLS_DOMAIN in your .env file (comma-separated) and restart the application (see Domain Names).
  6. When the notice says Certificate ready, the pages are live on https:// and your domain.

The domain cannot be:

  • the domain of your Broadcast installation, or
  • the tracking domain of a channel (see Domain Names). On a tracking domain, the issue URLs would sit next to the tracking, unsubscribe and sign-in paths. Use another subdomain.

Each domain can belong to one channel only. To stop using the domain, clear the field and save. The pages go back to the /p/<channel slug> addresses.

When a broadcast has a web version, the email can link to it in two ways:

  • The “View in browser” line. With Add a “View in browser” link to the email on (the default), Broadcast adds a small, centred link above the email. Its text is in the channel’s language.
  • The {{ web_version_url }} merge tag. Put the link where you want it:
Liquid
<a href="{{ web_version_url }}">Read this issue on the web</a>

{{ web_version_url }} is empty when the broadcast has no web version. The link points at the page that goes live when the broadcast is sent, so in a test email it answers 404 until the send.

API

The Broadcasts API reads and writes the web version as a web_version object: enabled, slug, title, description, image_url and view_in_browser on create and update, and unpublished to take the page of a sent broadcast down or put it back. Every broadcast in a response has the web_version object, with public, its url and unpublished_at.