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 common questions, see the FAQ; for how your data is handled see the privacy policy; for a technical overview 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. Sometimes it is a look-alike host: the text reads paypal.com while the link points at paypa1.com. Often it is subtler, routing through a tracker or redirector, so where you land is nothing like the brand named in the text.

This is not hypothetical. The message below is a real phishing email dressed up as a parcel-delivery notice from a postal service:

A phishing email impersonating a postal service, claiming a parcel is held until unpaid customs charges are paid and urging payment via a "Go to payment" button. Reveal URLs shows the button does not point to that postal service but to parcel-pay.custom.co.xa, an unrelated site, exposing the message as a scam.
Reveal URLs exposes the "Go to payment" button: it points to parcel-pay.custom.co.xa, not the postal service it impersonates.

Note: This screenshot shows a fraudulent phishing email impersonating a postal service. The impersonated service is not affiliated with Reveal URLs and does not endorse it.

Reveal URLs reads each link in the message you are reading and shows you the URL it points to. In the browser extension and Thunderbird, it flags misleading web, email, phone and other links, so the mismatch is obvious before you click.

Reveal URLs reveals and flags; it does not vet. It does not follow redirects: a link that passes through a tracker or redirector is revealed as the redirector URL it actually names, and Reveal URLs cannot tell where that redirect finally lands. A link with no warning has had no applicable mismatch detected, not confirmed as safe, so read the revealed URL before you trust a link even when nothing is flagged. To keep that in mind, the revealed URL on an unflagged link is shown in an amber "review" colour rather than a reassuring green.

A Gmail message with Reveal URLs active: a deceptive link is flagged in red with the tracking URL it points to revealed above the link text, while a non-mismatching link's URL is revealed without a warning.

Note: email addresses, URLs and names in this screenshot have been masked with asterisks for privacy.

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 mail apps

Reveal URLs runs on:

Web browsers:

Mail applications:

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

Installing

Install Reveal URLs from the store for your browser or mail client. Every listing is available now.

Web browsers:

Mail applications:

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-firefox       # produces dist/firefox
make build-gmail         # produces dist/gmail
make build-opera         # produces dist/opera
make build-outlook       # produces dist/outlook
make build-safari        # produces dist/safari
make build-thunderbird   # produces dist/thunderbird

Then load the resulting folder:

The Safari extension, Outlook add-in and Gmail add-on are not loaded as unpacked browser extensions. Build them as above, then:

make deploy-gmail        # deploy the Gmail add-on to Apps Script (it runs on Google's
                         # servers, so it is deployed rather than loaded locally)
make safari-xcode        # scaffold the Safari Xcode project, then run the extension
                         # from Safari's Develop menu (macOS)
                         # Outlook: sideload dist/outlook — see The Outlook and Gmail add-ons

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 URL is shown on its own line above the link text, with a mismatching tracking link flagged in red and a non-mismatching link revealed without a warning.

Note: email addresses, URLs and names in this screenshot have been masked with asterisks for privacy.

How the real URL is shown

The real URL of each link is shown on its own line, just above the link text. It is also placed in the link's tooltip (title), so the full URL is always there when you hover over the link.

Mismatch highlighting

For web links, Reveal URLs compares URL or host names in a link's visible text with the URL it points to. The comparison is done on the registrable domain, so a non-mismatching 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. The browser extension and Thunderbird also assess email, phone and opaque links; javascript:, data: and vbscript: links are always flagged.

The check looks only at the URL the link itself names; redirects are never followed, so a link that passes through a tracker or redirector is compared as the redirector URL it names, not the page it ultimately reaches.

A mismatch is shown in your chosen mismatch colour and in bold.

Two related settings control this:

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

The toolbar button

In Chrome, Edge, Opera, Firefox and Thunderbird, 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. In the browsers the change takes effect in every open tab at once; in Thunderbird it applies to the next message you open.

While Reveal URLs is switched on, the browser toolbar icon also tells you, per tab, what it found on the current page. If the page has any mismatching (look-alike) links, the icon shows that count on a red badge; if the page has links but none of them mismatch, it shows the total number of analysed links on a grey badge; a matched page with no analysable links shows no count. On a page Reveal URLs is not active on (one you have not added to Active sites), the toolbar icon itself appears in a muted, light grey instead of its normal colour, so you can tell the extension is switched on but simply not watching this page. Each tab keeps its own badge and icon, so switching tabs updates them, and navigating away or closing the tab clears the badge. (Counts above 99 show as 99+.)

The grey count is not a safety verdict: it is how many links were analysed on a page with no look-alike mismatch, not a guarantee that those links are safe. Read the revealed URLs before you trust them.

On Safari, only a mismatching-link badge is shown. Safari deliberately suppresses the grey safe-page count because it renders every badge as a warning colour.

The badge in its states (the browser draws it, so exact placement varies a little by browser): a red mismatch count, a grey analysed-links count, and the OFF badge while the extension is disabled; its logo is also muted light grey. On a page the enabled extension is not active on there is no badge; the missing OFF badge distinguishes that same muted logo from the disabled state.

These illustrations show representative states, not every no-badge outcome. An enabled active page with no analysable links keeps the normal-colour icon without a badge; the muted icon below means the enabled extension is not active on this page.

Toolbar icon showing a red badge with the number of mismatching links on the current page Toolbar icon showing a grey badge with the number of analysed links on the current page Toolbar icon showing a muted light-grey logo with no badge while the enabled extension is not active on this page Toolbar icon showing the red OFF badge while the extension is disabled

(In Thunderbird the button shows only its icon, so it stays compact in the unified toolbar. You can also turn Reveal URLs on and off with the Enable switch on the settings page.)

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.

On Safari, reopen settings from the right-click Reveal URLs — settings menu on the toolbar icon or a page. Do not reload a stale settings tab: Safari can show it as an empty document.

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 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. It now stays a fixed height: choose one site from the dropdown, then edit only that site's settings in the panel below.

The top of the settings page: the 'Enable Reveal URLs' master switch and the 'Active sites' section, with an 'Active site' dropdown above one selected-site editor showing the match pattern, an 'Enabled' toggle, a 'Sub-frames' toggle and its message-body selector.

The dropdown shows one entry per site rule:

The selected-site editor shows:

The built-in providers (FastMail, Gmail, Outlook Live, Outlook 365, Proton, Tuta, Yahoo and Zoho) can be toggled off and re-targeted, but they cannot be removed. Their names can also be renamed here; clearing a built-in name restores its default friendly name.

To add your own webmail site:

  1. Under Add site, enter a Match URL — a match pattern such as https://mail.example.com/*.
  2. Optionally enter a Name for the dropdown. Leave it blank to fall back to the match URL.
  3. Enter a Message-body selector — a CSS selector for the container that holds the message body, for example .message-body.
  4. If the message body is rendered inside a sub-frame, tick Also run inside sub-frames.
  5. 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. To change a site's match URL, remove it and add it again: the match stays read-only because it is the rule's identity.

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, 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. They share the browser extension's http/https URL/host detection, but do not analyse its additional link schemes.

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 http/https link it shows the visible text and destination URL, and flags a mismatch only when the visible text contains a URL or host name whose registrable domain does not match the one the link actually points to.

The Outlook add-in is published on Microsoft Marketplace and can be installed from its listing (linked from the Reveal URLs website and the project README). It is available for Outlook on the web and the Outlook desktop app; Outlook mobile is not yet available and is planned for a later update. The Gmail add-on is available now through the Google Workspace Marketplace for Gmail on the web, Android and iOS.

Languages

Reveal URLs is available in English and many other languages.

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, 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.

Licence and source

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

Safari notes

Safari shows a badge only when links mismatch; it has no grey safe-page count. Reopen settings with the right-click Reveal URLs — settings menu, rather than reloading a stale settings tab.