Common ways they break

• Typos. mailto:sales@exmaple.com looks fine at a glance.
• Old addresses. A team inbox was retired, but the footer still links to it.
• Domain changes. After a rebrand, mailto: links still use the old domain, whose mail records may be gone.
• Formatting mistakes in tel: links. Spaces, letters or missing country codes make some phones refuse to dial.
• Encoding problems. Subjects and bodies with unencoded spaces or & characters get cut off.

Collect them from your pages

import re, requests
from urllib.parse import unquote

def contact_links(url):
    html = requests.get(url, timeout=15, headers={"User-Agent": "Mozilla/5.0"}).text
    return set(re.findall(r'href=["\']((?:mailto|tel):[^"\']+)', html, re.I))

for link in contact_links("https://example.com/contact"):
    print(unquote(link))

Run it over every URL in your sitemap and you'll have a full inventory. Usually it's a short list, which makes it easy to review by eye.

Check mailto: links

Strip the address from any query string:

from email.utils import parseaddr
import dns.resolver  # pip install dnspython

def check_mailto(link):
    addr = unquote(link[7:].split("?")[0])
    name, email = parseaddr(addr)
    if "@" not in email:
        return "invalid address"
    domain = email.rsplit("@", 1)[1]
    try:
        dns.resolver.resolve(domain, "MX")
        return "ok"
    except Exception as e:
        return f"no MX for {domain}: {type(e).__name__}"

A missing MX record means mail to that domain will almost certainly fail. A valid MX doesn't prove the mailbox exists. The only reliable test for that is to send a real message to every address on your site once in a while and see whether it arrives.

Check tel: links

The format is simple: the RFC recommends the full international number, with an optional + and digits, and visual separators like - and . are allowed:

import re
TEL_OK = re.compile(r'^tel:\+?[0-9][0-9\-\.\(\) ]{5,}$')

def check_tel(link):
    raw = unquote(link)
    if not TEL_OK.match(raw):
        return "unusual format"
    if not raw.startswith("tel:+"):
        return "no country code"
    return "ok"

Writing numbers in international form (tel:+442071234567) makes them work for visitors calling from any country. The visible text can still show the local format.

Check the encoded parts

For mailto: links with a subject or body, encode spaces as %20, not +:

<a href="mailto:hello@example.com?subject=Demo%20request&body=Hi%2C%20I%27d%20like%20a%20demo.">

Test by clicking it on desktop and mobile; mail apps are less forgiving than browsers.

Watch for obfuscation side effects

Sites often hide email addresses from scrapers with JavaScript or CDN features. That's fine, but it means the address in the HTML isn't the one visitors get. Check the link in a real browser after the script runs, not just in the source.

A quick manual review list

• Every contact address belongs to a mailbox someone reads
• Every phone number dials from a mobile phone
• Numbers use international format in the tel: link
• No old brand domains in mailto: links
• Contact links in emails and PDFs match the site

Keep the rest of the links in check

mailto: and tel: links need occasional manual review. The rest of your links can be checked automatically: linkbruno.com crawls your pages on a schedule and alerts when a link or image breaks.

Related reading

• Changed a URL slug? A cleanup plan for every link that pointed to it
• How to find broken links inside PDFs and downloadable files
• Check links in Markdown docs with a 60-line Python script

Why PDF links break more often

• A PDF can't be edited in place. Fixing a link means regenerating and re-uploading the file.
• PDFs are often created by people outside the web team, with links to internal drafts or staging URLs.
• They live for years. A link that was fine on publication day may not survive a site redesign.
• Copies of the old file keep circulating, so even after a fix, the old version still has the broken link.

Extract links with Python

The pypdf library can read link annotations, which is where clickable links live:

from pypdf import PdfReader

def pdf_links(path):
    reader = PdfReader(path)
    for page_num, page in enumerate(reader.pages, start=1):
        for annot in page.get("/Annots") or []:
            obj = annot.get_object()
            action = obj.get("/A")
            if action and action.get("/URI"):
                yield page_num, action["/URI"]

for page, uri in pdf_links("report.pdf"):
    print(page, uri)

Some PDFs also contain URLs as plain text that aren't clickable. To catch those, extract the text and search it:

import re
text_urls = set()
for page in PdfReader("report.pdf").pages:
    text_urls.update(re.findall(r'https?://[^\s)>\]]+', page.extract_text() or ""))

Text extraction can split a long URL across lines, so treat these results as hints to check by hand.

Check the URLs

import requests

def status(url):
    try:
        r = requests.head(url, allow_redirects=True, timeout=10,
                          headers={"User-Agent": "Mozilla/5.0"})
        if r.status_code in (403, 405):
            r = requests.get(url, allow_redirects=True, timeout=15, stream=True,
                             headers={"User-Agent": "Mozilla/5.0"})
        return r.status_code
    except requests.RequestException as e:
        return type(e).__name__

for page, uri in pdf_links("report.pdf"):
    s = status(uri)
    if s != 200:
        print(f"page {page}: {uri} -> {s}")

Check every PDF on your site

Gather all PDF URLs first. If they're linked from your pages, your sitemap or a crawl will find them. If you have server access:

find /var/www -name '*.pdf' > pdfs.txt

Then loop over the files with the functions above and write a CSV of page, link and status that the content owner can work through.

Don't forget Word, Excel and slides

Office files (.docx, .xlsx, .pptx) are ZIP archives with XML inside. Hyperlinks are stored in relationship files:

unzip -p guide.docx 'word/_rels/document.xml.rels' | grep -o 'Target="http[^"]*"'

That's enough to list the external links for checking.

Fixing broken PDF links

You have three options:

1. Regenerate the PDF from the source document with corrected links and replace the file at the same URL. Readers who download it again get the fix.
2. Redirect the broken target. If the dead link points to your own site, a 301 from the old URL fixes every existing copy of the PDF at once, including ones already downloaded. This is often the best fix.
3. Use stable short paths in future PDFs. Links like example.com/go/pricing that you redirect on your own server can be updated forever without touching the PDF.

Don't skip the links pointing to PDFs

The other direction breaks too: pages that link to a PDF that was renamed or deleted. A regular crawl of your pages catches those. linkbruno.com checks every link on your pages on a schedule, including links to files, and tells you which page the broken link is on.

Related reading

• How to find mixed content (http:// links) on an HTTPS site
• Changed a URL slug? A cleanup plan for every link that pointed to it
• Too many broken links? How to decide which to fix first
• Why links in old email newsletters break, and how to prevent it
• Trailing slashes: the small URL detail that creates redirects
• How to check mailto: and tel: links before they cost you leads

Step 1: write down the old and new URL

Sounds obvious, but when several pages change at once, a simple two-column list saves hours later:

old,new
/blog/broken-link-tips,/blog/find-broken-links
/pricing-old,/pricing

Keep it in the repo or wherever your redirects live.

Step 2: add a 301 redirect before you change anything else

The redirect is what protects external links and bookmarks you can't edit. In nginx:

location = /blog/broken-link-tips { return 301 /blog/find-broken-links; }

In Apache .htaccess:

Redirect 301 /blog/broken-link-tips /blog/find-broken-links

Most CMSs and hosts (WordPress plugins, Netlify _redirects, Vercel redirects in config) have an equivalent. Test it:

curl -sI https://example.com/blog/broken-link-tips | grep -iE '^(HTTP|location)'

You want one 301 and a location pointing straight to the new URL.

Step 3: avoid chains

If this page was renamed before, an old redirect may now point to the URL you just retired:

/2019-post -> /blog/broken-link-tips -> /blog/find-broken-links

Update the oldest rule so it points directly to the final URL. Each extra hop adds latency and is one more thing that can break.

Step 4: update internal links

A redirect makes internal links work, but they should still point to the real address. Search your content for the old path:

grep -rn '/blog/broken-link-tips' content/ templates/

In WordPress, WP-CLI can search the database:

wp db search '/blog/broken-link-tips' --all-tables

Don't forget menus, footers, sidebar widgets, and "related posts" blocks that store URLs separately from the post body.

Step 5: update the sitemap and canonical

Your XML sitemap should list only the new URL. If it's generated automatically, check it regenerated. Make sure the new page's canonical tag points to itself, not to the old address.

Step 6: the links you don't control

You can't edit other sites, but you can ask. For a page with important backlinks, find the sites linking to the old URL (Search Console's Links report shows top linking sites), and send a short note to the ones that matter most. The redirect covers you either way; the update just removes a hop.

Also update the places you do control outside the site: social profiles, email signatures, email templates, documentation, app store listings, and ad campaigns.

Step 7: check again a week later

Redirect rules get overwritten by deploys, plugins get updated, and someone else renames a page that links to yours. A quick re-check after a week catches most problems:

• Old URL still returns 301 to the new one
• New URL returns 200
• No internal links to the old URL remain
• Sitemap lists only the new URL

When to skip the redirect

If the old page had no traffic, no backlinks and was never shared, a redirect is still cheap insurance. The only real reason to skip it is when the content is gone for good with no replacement, in which case a 410 is more honest than redirecting to the homepage.

Automate the boring part

Steps 4 and 7 are exactly what a scheduled link check is for. linkbruno.com crawls a site on a schedule, follows redirects hop by hop to show each chain, and alerts when an internal link breaks, with the page it's on.

Related reading

• Check links in Markdown docs with a 60-line Python script
• How to find mixed content (http:// links) on an HTTPS site
• Too many broken links? How to decide which to fix first
• Why links in old email newsletters break, and how to prevent it
• Trailing slashes: the small URL detail that creates redirects
• How to check mailto: and tel: links before they cost you leads

What Selenium is for here (and what it isn't)

Selenium can't read HTTP status codes; WebDriver doesn't expose them. So the job splits in two:

1. Selenium loads the page in a real browser and collects the links, including ones added by JavaScript.
2. An HTTP client (requests) checks each link's status.

Setup

pip install selenium requests

Selenium 4.6+ downloads a matching browser driver automatically, so no manual chromedriver setup is needed.

Step 1: collect the links

from urllib.parse import urldefrag
from selenium import webdriver
from selenium.webdriver.common.by import By

START_URL = "https://staging.example.com/"

options = webdriver.ChromeOptions()
options.add_argument("--headless=new")
driver = webdriver.Chrome(options=options)

driver.get(START_URL)
hrefs = {a.get_attribute("href") for a in driver.find_elements(By.TAG_NAME, "a")}
driver.quit()

links = sorted({urldefrag(h)[0] for h in hrefs if h and h.startswith("http")})
print(f"{len(links)} unique links")

get_attribute("href") returns the resolved, absolute URL, so relative links are handled. The filter drops empty hrefs and mailto:, tel: and javascript: links. urldefrag removes #section parts, because the server never sees them and you'd otherwise check the same page repeatedly.

Step 2: check each link properly

import time
import requests

session = requests.Session()
session.headers["User-Agent"] = "Mozilla/5.0 (link check; +internal QA)"

def check(url):
    try:
        r = session.head(url, allow_redirects=True, timeout=15)
        if r.status_code in (403, 405, 501):          # HEAD refused: try GET
            r = session.get(url, allow_redirects=True, timeout=15, stream=True)
            r.close()
        return r.status_code, len(r.history), r.url
    except requests.RequestException as e:
        return 0, 0, type(e).__name__

What this fixes compared with the usual tutorial:

• allow_redirects=True. requests.head() does not follow redirects by default, so a moved page reports 301 and looks fine even if the destination is a 404.
• GET fallback. Many servers answer HEAD with 405 or 403. stream=True avoids downloading the whole body.
• Timeouts. Without one, a single dead server can hang the run.
• len(r.history) tells you how many redirects it took, so you can spot long chains worth updating.

Step 3: be polite and avoid rate limits

Checking 200 links on the same host as fast as possible will earn you a 429 Too Many Requests. Add a short delay per host:

from urllib.parse import urlparse

last_hit = {}

def polite_check(url, gap=1.0):
    host = urlparse(url).netloc
    wait = gap - (time.time() - last_hit.get(host, 0))
    if wait > 0:
        time.sleep(wait)
    last_hit[host] = time.time()
    return check(url)

Step 4: classify the results

Not every non-200 response means broken. Separate them:

BLOCKED = {401, 403, 429, 999}     # 999 is LinkedIn refusing automated requests

broken, blocked, slow_chains = [], [], []
for url in links:
    status, hops, final = polite_check(url)
    if status == 0 or (status >= 400 and status not in BLOCKED):
        # Re-check once before calling it broken: servers hiccup.
        time.sleep(5)
        status, hops, final = check(url)
        if status == 0 or (status >= 400 and status not in BLOCKED):
            broken.append((status, url, final))
            continue
    if status in BLOCKED:
        blocked.append((status, url))
    elif hops >= 3:
        slow_chains.append((hops, url, final))

for s, u, f in broken:
    print(f"BROKEN {s}  {u}  -> {f}")
for s, u in blocked:
    print(f"COULD NOT VERIFY {s}  {u}")
for h, u, f in slow_chains:
    print(f"{h} REDIRECTS  {u}  -> {f}")

The single re-check removes most false alarms caused by a server that blinked. The "could not verify" bucket is important: those links usually work for people, and failing a test because of them trains everyone to ignore the test.

Step 5: make it a test

Wrap it in pytest so it runs with the rest of your suite:

def test_no_broken_links():
    assert not broken, "\n".join(f"{s} {u}" for s, u, _ in broken)

Things a status check won't catch

• Soft 404s: a page that answers 200 but says "Page not found". Check the response text for your site's not-found wording.
• Missing anchors: /docs#install returns 200 even after the install heading is gone. Load the page with Selenium and check driver.find_elements(By.ID, "install").
• Parked domains: a link to an expired domain often returns 200 with an ad page.

One run vs. monitoring

This script tells you what is broken today. Links on a live site break gradually, long after the test passed, as other sites move or disappear. Run the script on a schedule, or use a hosted monitor such as linkbruno.com that re-crawls your site and alerts by email or Slack when a link stops working.

Either way, the three fixes above (follow redirects, fall back to GET, re-check before failing) are what turn the textbook Selenium exercise into a check you can trust.

Related reading

• Why links in old email newsletters break, and how to prevent it
• How to find mixed content (http:// links) on an HTTPS site
• How to find broken links inside PDFs and downloadable files
• Trailing slashes: the small URL detail that creates redirects