Reveal URLs

Reveal URLs — User Manual

Reveal URLs is a small browser extension (and Thunderbird add-on) that shows you where a link in your email really goes, so you can spot a phishing link before you click it.

This manual explains how to install Reveal URLs and how to use it. For how your data is handled see the privacy policy; for a technical overview of how the extension is built see the architecture overview.

Found a bug, a link that was flagged wrongly (or missed), or a webmail host that should be supported? Please report it on the Codeberg issue tracker.

Contents

What it does and why

A phishing email hides a hostile destination behind trustworthy-looking link text. The text may read paypal.com, while the link actually points at paypa1.com or some other look-alike host. The visible text can lie; the real destination cannot.

Reveal URLs reads each link in the message you are reading and shows you its real destination. When the host named in the link text disagrees with the host the link actually points to, Reveal URLs flags it, so the mismatch is obvious before you click.

A Gmail message with Reveal URLs active: a deceptive link is flagged in red with its real tracking destination revealed above the link text, while an honest link is shown in green.

In the browser extension and the Thunderbird add-on, everything happens on your own device, transmitting nothing. Across every form, Reveal URLs sends none of your email data to us or to any third party — there is no analytics and no tracking. (The forms differ in where they run and how the Outlook pane's code is served; see the Privacy section and the privacy policy for the full details.)

Supported browsers and the mail client

Reveal URLs runs on:

A Safari build is not yet shipped; it is planned for a later phase.

On the browser targets, Reveal URLs annotates links in your webmail. In Thunderbird it annotates the links in the email you are reading directly in the mail client.

Installing

Once published, install Reveal URLs from the store for your browser or mail client. Publication is pending, so these listings are the intended distribution route rather than live links today:

Loading a build yourself (developers and early testing)

If you have built Reveal URLs from source, you can load the unpacked build directly. Each target is built with a make command and produced under dist/<target>/:

make build-chrome        # produces dist/chrome
make build-edge          # produces dist/edge
make build-opera         # produces dist/opera
make build-firefox       # produces dist/firefox
make build-thunderbird   # produces dist/thunderbird

Then load the resulting folder:

The settings page opens automatically the first time the extension is installed.

Using it

Out of the box, Reveal URLs annotates the links in messages on the built-in providers — no setup required:

Annotation is scoped to the message body, so the app's own chrome — its sidebar, compose window and toolbars — is left untouched. In Thunderbird, the whole rendered email is covered.

Reveal URLs annotating a Gmail message: each link's real destination is shown on its own line above the link text, with a mismatching tracking link flagged in red and an honest link in green.

The two reveal modes

You choose how the real URL is shown, under Reveal the URL on the settings page:

Mismatch highlighting

When the host named in a link's visible text disagrees with the host the link actually points to, Reveal URLs flags it as a mismatch. The comparison is done on the registrable domain, so an honest sub-domain such as mail.example.com for example.com is not flagged, while a look-alike such as paypa1.com for paypal.com is.

Two related settings control this:

The settings page: the 'Reveal the URL' mode selector, the 'Highlight mismatching links' toggle, and the mismatch and match colour fields.

The toolbar button

In Chrome, Edge, Opera and Firefox, the Reveal URLs toolbar icon is a quick on/off switch — click it to toggle annotation. When the extension is switched off, an OFF badge appears on the icon, and its tooltip tells you whether clicking will turn it on or off. The change takes effect in every open tab at once.

(Thunderbird does not have this toolbar button; use the Enable switch on the settings page instead.)

The settings page

The settings page holds every option. Open it from your browser's extensions page (for example Details → Extension options), or it opens automatically on first install.

Apart from the master Enable switch and the Active sites controls (which apply immediately), changes are saved with the Save settings button.

The lower settings: the 'Ignore these hosts' list, the maximum displayed URL length, and the optional revealed-URL and warning-badge font size and weight fields, above the 'Save settings' button.

Active sites — adding your own webmail

The Active sites section, at the top of the settings page, lists the pages Reveal URLs runs on and the container that holds each message body.

The top of the settings page: the 'Enable Reveal URLs' master switch and the 'Active sites' list, each built-in provider showing its match pattern, an 'Enabled' toggle, a 'Sub-frames' toggle and its message-body selector.

Each row shows:

The built-in providers (Gmail, Outlook and Proton) can be toggled off and re-targeted, but they cannot be removed.

To add your own webmail site:

  1. Under Add site, enter a Match URL — a match pattern such as https://mail.example.com/*.
  2. Enter a Message-body selector — a CSS selector for the container that holds the message body, for example .message-body.
  3. If the message body is rendered inside a sub-frame, tick Also run inside sub-frames.
  4. Click Add site. Your browser will ask for permission to access that site; grant it. The site is only added once you grant the permission.

Changes here apply immediately. Removing a site you added also revokes its permission, so Reveal URLs stops accessing it.

Thunderbird (and other mail clients). Thunderbird already shows every message you read, whatever the provider, so it has no need for a per-host list. The Active sites section is therefore not shown on the Thunderbird settings page — only the master switch, display language, reveal mode, colours, fonts and the ignore-list appear. Any active-sites configuration you may have set in a browser is preserved untouched: saving the Thunderbird settings never clears it.

The Outlook and Gmail add-ons

Alongside the browser extension and the Thunderbird add-on, Reveal URLs comes as a native add-on for two mail apps a browser extension cannot reach: an Outlook add-in and a Gmail add-on. Both use the same link detection as the extension, so they reveal the same real destinations and flag the same look-alike hosts.

The one difference is how they show their findings. The browser extension annotates the links in place — colouring the URL above or beside each link. The Outlook and Gmail frameworks do not allow an add-on to change the rendered message, so instead each add-on shows a side panel (Outlook) or card (Gmail) listing the links it found. For each link it shows the visible text, the real destination and the registrable host, and it flags a mismatch when the visible text names a different registrable domain than the link actually points to.

Both add-ons will be distributed through their app stores — the Outlook add-in via Microsoft AppSource, the Gmail add-on via the Google Workspace Marketplace. Publication is pending; direct install links will be added here once each listing is live.

Languages

Reveal URLs is available in English and ten more languages — Danish, German, Spanish, Finnish, French, Italian, Dutch, Norwegian, Polish and Swedish.

The non-English text is machine-translated and is pending human review, so a phrase may occasionally read awkwardly; the meaning is intended to match the English original. If you spot a mistranslation, please open an issue on the Codeberg issue tracker.

Privacy

Reveal URLs sends none of your email or message data to us or to any third party, in any of its forms — there is no analytics and no tracking. How and where the work happens depends on the form:

The only thing stored is your own settings (such as enabled/disabled, reveal mode, colours, font sizes, your ignore-list and any sites you have added), kept in your browser's, Outlook's or Google's per-user storage and never sent to us.

See the privacy policy for the full details.

Troubleshooting

A link is not being revealed.

A built-in provider stopped working after a redesign.

Webmail providers change their page markup from time to time. If a built-in provider's selector no longer matches after such a change, you can correct it yourself: in Active sites, edit that provider's message-body selector to the new container.

The tooltip URL is not showing.

In tooltip (title) mode the real URL is placed in the link's tooltip, so it only appears when you hover over the link. If you would rather see the URL without hovering, switch Reveal the URL to inline mode.

Licence and source

Reveal URLs is free software, licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only).