All documentation

    Backlinks and Outreach

    The Backlink Builder (BacklinkBuilder.tsx) is a large dashboard page for running link-building campaigns: discovering opportunities, tracking live backlinks, generating and sending outreach emails, and pulling real domain metrics from Ahrefs.

    Campaigns

    Everything is scoped to a backlink campaign — a website URL, niche and target keywords stored in backlink_campaigns, with active/paused/completed status and an auto_run flag. The page's tabs (campaigns, opportunities, tracked backlinks, outreach templates, etc.) all operate against the currently selected campaign.

    Discovering opportunities (discover-opportunities)

    The discover-opportunities edge function takes a campaign_id (and optionally a competitor_url) and asks the AI gateway (OpenRouter, falling back to Lovable AI) to generate 15 realistic backlink opportunities for the campaign's website, niche and keywords. Each suggestion includes a source URL, an opportunity type (guest-post, directory, forum, resource-page, broken-link, skyscraper, niche-edit), estimated domain authority and relevance scores (1–100), a plausible contact email, and notes explaining the opportunity. When a competitor_url is supplied, the prompt is steered toward "sites that link to the competitor but not yet to the user" — this is the Competitor Spy workflow surfaced in the UI.

    Opportunities are stored and shown in a filterable, sortable table (by relevance score, domain authority or date, ascending/descending) with status badges (new, qualified, contacted, linked) and type badges.

    Tracking and verifying backlinks (check-backlinks)

    Once a link is placed, it's tracked in tracked_backlinks (target URL, source URL, anchor text, status, discovery/check timestamps). The check-backlinks function re-verifies tracked links: it can run under a user's JWT or as a scheduled cron job (authenticated via an x-cron-secret header), fetches up to 50 links needing a check, and for each one:

    • Validates the source URL isn't pointing at an internal, loopback, link-local, CGNAT or .internal/.local address (an SSRF guard) before fetching it.
    • Sends a HEAD request with a 10-second timeout and marks the link live or lost based on the response.
    • Skips (and just updates the checked-at timestamp) for any URL that fails the safety check, and marks links without a checkable source URL as verified.

    The function returns counts of verified, lost, errored and skipped links so the UI (or a cron dashboard) can report on link health over time.

    Sending outreach (send-outreach)

    send-outreach sends an actual email for a given opportunity_id, subject and body (with sender name/email overrides), using Lovable's email SDK (@lovable.dev/email-js) from the verified sending subdomain notify.rankpilotaiseo.co.uk. It enforces length guards (subject ≤ 998 characters, body ≤ 100,000 characters, sender name ≤ 100 characters) and requires an authenticated user who owns the opportunity. On success, the opportunity's status typically moves to contacted.

    Outreach templates

    Five default outreach templates ship with the page (Guest Post Pitch, Directory Submission, Broken Link Outreach, Resource Page Request, Skyscraper Outreach), each with a subject and body containing {{placeholder}} tokens ({{name}}, {{site}}, {{niche}}, {{keyword_1}}, {{website}}, etc.) that get filled in per opportunity before sending. Users can edit, save and manage their own templates alongside the defaults.

    Bulk selection and sending

    The opportunities table supports multi-select via checkboxes, with a "select all" toggle in the header. Once opportunities are selected, two bulk actions are available:

    • Bulk generate outreach — drafts outreach messages for every selected, eligible opportunity (must have a contact email and not already be contacted).
    • Bulk queue and send — runs through the same eligible set and sends outreach emails one by one, tracking progress with a { done, total, sent, failed } counter and a progress bar, so large batches don't need to be triggered link-by-link.

    Linkable asset generation

    For campaigns needing a link-worthy piece of content to pitch, the page can call the content-brief function in linkable-asset mode, generating a guest-post topic and outline tailored to the campaign's niche and keywords — output the user can hand to a writer or the Blog Writer tool.

    Ahrefs integration

    Users can add their own Ahrefs API key (encrypted and stored per-user, tagged service: "ahrefs"). Once a key is present, the page calls the ahrefs-metrics function to pull real Domain Rating and organic traffic numbers for the campaign's domain, shown alongside the AI-estimated scores. A dedicated AhrefsInsightsPanel component offers deeper Ahrefs data — backlinks, referring domains and organic keywords — with CSV and PDF export for each dataset, plus the ability to add a discovered Ahrefs keyword straight into the site's tracked keywords.