UniFi Captive Portal Setup Guide: Email Capture with CaptiFi

Why add a captive portal to your UniFi network

Guests connect to your WiFi and that is the end of the relationship. You do not know who they were, whether they came back, or how to reach them. A captive portal puts a branded sign-in page in front of the connection, so every guest who gets online gives you an email address with a marketing opt-in kept separate from the WiFi itself. From there the follow-ups run on their own: a welcome email, a Google review request after the visit, and a win-back email when a guest has not been back for a while.

UniFi has a hotspot portal of its own, and it is fine as a door: it can show a terms page, a voucher box or a password field. It does not store an email list you can export, send marketing, record consent or ask for reviews. CaptiFi sits on top of the UniFi setup you already own and adds that layer. Because the portal is configured on the controller, nothing about your access points changes.

Consoles and access points that work

CaptiFi connects to the UniFi controller, so the make of access point does not matter. U7, U6 and the older UAP-AC models all serve the same sign-in page. What does matter is the console the controller runs on, and CaptiFi supports all of them:

• UniFi Dream Machine: UDM, UDM Pro and UDM SE
• UniFi Cloud Gateway: UCG Ultra and UCG Max
• Dream Router and UniFi Express
• Cloud Key and Cloud Key Gen2 (including Gen2 Plus)
• A self-hosted UniFi Network application on your own machine, VM or server, including UniFi OS Server on Windows

The controller needs UniFi Network 6 or later. If you would rather not touch the controller at all, the alternative is the plug-and-play device CaptiFi posts to you, which broadcasts its own guest network alongside your UniFi WiFi. Both routes land in the same dashboard.

Before you start

You need four things: admin access to the UniFi controller, a CaptiFi account (the 30-day free trial is enough), five minutes at the venue or remote access to the console, and two values typed exactly as written. CaptiFi's connection address is 46.62.168.7 and its portal domain is site.app.captifi.io. A single wrong character stops the sign-in page from appearing, and it fails silently, so copy and paste them.

If you signed up today, the onboarding wizard on my.captifi.io walks through the same steps and stops at each one. This guide is the long version, with every hardware variation and the things that can go wrong. The customer documentation has the same guide with screenshots of every screen.

Step 1: Choose how CaptiFi reaches your controller

CaptiFi has to talk to your controller to write the portal settings and to authorise each guest who completes the sign-in page. There are three ways to give it that access. Pick the row that matches your situation.

Not sure whether your console can make API keys? Open the UniFi Network application, go to Settings, then Control Plane, and look for Integrations. Newer releases move Integrations to the left menu, so check both places. If it is in neither, update UniFi Network first and fall back to Path C only if the update is not possible.

For Path B, the tell-tale signs are an "Upstream NAT detected on WAN1" banner in the UniFi app, a WAN address that starts with 10., 192.168. or 172.16. through 172.31., an ISP modem and router combo in front of your gateway, or a 4G, 5G or CGNAT fibre connection. If any of those apply, skip Step 3 and read the Remote Tunnel notes in Step 4.

Step 2: Create the UniFi API key

1. In the UniFi Network application, go to Settings, then Control Plane, then Integrations
2. Type a name you will recognise later, for example CaptiFi
3. Set the role or access level to Full Control
4. Set the expiry to Never expires, unless your own policy says otherwise
5. Click Create API Key and copy the key straight away

UniFi shows the key exactly once. If you close the dialog without copying it, delete that key and create another; there is no way to read an existing key back. Full Control is required because CaptiFi has to authorise guest devices and read your WiFi networks. A read-only key connects and then fails the moment the first guest tries to sign in.

An API key beats a controller login in two ways. You can revoke it from UniFi at any time without changing a password, and multi-factor authentication on your Ubiquiti account does not get in the way. One key also covers every site on the controller.

Step 3: Let CaptiFi reach your console

CaptiFi connects to your controller from one address only, 46.62.168.7. How you allow that depends on the hardware.

Dream Machine, Cloud Gateway, Dream Router or UniFi Express

On these consoles the controller runs on the gateway itself, so you need a firewall rule, not a port forward (a port forward sends traffic to a device behind the gateway, which is not where the controller lives).

1. Go to Settings, then Policy Engine (Firewall & Security on older firmware), open Object Manager and create a port group named Captifi containing ports 80 and 443
2. Still in Policy Engine, open Firewall Rules, click Create Entry and switch the rule type to Advanced
3. Set the type to Internet Local, the action to Accept, the protocol to All, tick Before Predefined, set the source to Any, and set the destination port object to the Captifi group
4. Save the rule

Internet Local is the part people miss. UniFi splits inbound traffic into Internet In (to devices on your LAN) and Internet Local (to the gateway itself). Your controller is on the gateway, so CaptiFi's traffic is Internet Local. Scoping it to the port group opens only ports 80 and 443, and only to the gateway. On older firmware with zones, the same rule is source zone External, destination zone Gateway, destination port the Captifi group, action Allow. The rule covers IPv4; if your site runs IPv6 as well, add a matching IPv6 rule or make sure the controller is reached over IPv4.

Cloud Key or Cloud Key Gen2

A Cloud Key is a separate device on your LAN, so this is a normal port forward on whatever router sits in front of it: external port 8443 to the Cloud Key's IP on internal port 8443, protocol TCP. If an ISP router you do not control sits in front, use the Remote Tunnel instead; most Cloud Keys can now run it, and the installer tells you if yours cannot.

Self-hosted controller

Make sure port 8443 (or whichever port your controller listens on) is reachable from the internet, then restrict inbound access on that port to 46.62.168.7 only. You do not need to expose the controller to the whole internet and you should not. Enter the controller as an IPv4 address or a hostname with only an A record. You can also forward any free external port, for example 7443, and give CaptiFi the address with that port, such as unifi.example.com:7443. The Remote Tunnel is not available for self-hosted controllers, so this single-address restriction is the way to keep one private.

Check it worked

Do this from outside your network, for example on your phone with WiFi turned off. Find the venue's public IP, then visit https://YOUR_PUBLIC_IP for a Dream Machine or UCG, or https://YOUR_PUBLIC_IP:8443 for a Cloud Key or self-hosted controller. You should see the UniFi sign-in page; a browser certificate warning is normal here because the controller uses a self-signed certificate. If nothing loads and the gateway's WAN address is a private IP, you are behind double NAT: use the Remote Tunnel.

Step 4: Connect the controller in CaptiFi

If you are still in onboarding, the wizard asks for three things: a controller name for your own reference, the controller URL (the public address or hostname you tested in Step 3; CaptiFi adds https:// and finds the port, so you only type a port if you forwarded a custom one), and the API key from Step 2. Click Connect controller. CaptiFi checks the address, signs in with the key and discovers your UniFi sites.

If your account is already set up, log in to my.captifi.io, go to My Locations and click Add location. Choose Ubiquiti UniFi, name the venue, set its type and timezone, then choose Direct connection for Path A or Remote Tunnel for Path B and click Add venue. The wizard then connects the controller: Remote Tunnel asks for your API key, and Direct connection asks for the controller address and a local admin username and password. To move a Direct connection venue onto the key you made in Step 2, open Connection status on the venue card, choose Update connection, then Use an API key instead.

Every plan includes one location, and from Essentials up each additional location is charged at the extra-venue rate for your billing currency (£25, $35, €30, C$45, A$49 or NZ$59 per month), from the day you add it and prorated to your billing date. If the controller hosts several UniFi sites, pick the right one from the Controller site dropdown before you continue: it is one CaptiFi location per UniFi site, and CaptiFi cannot choose for you. One API key covers every site on the controller, so those locations share a single connection and rotating the key changes the connection for all of them.

If you chose the Remote Tunnel

The install command is unique to your venue and appears in the wizard on the Install the Tunnel step; for a venue already in CaptiFi, email hello@captifi.io and we will send the command for your venue. Turn SSH on in UniFi OS under Settings, Control Plane, Console, set an SSH password, connect with ssh root@YOUR-CONSOLE-IP, paste the command and wait about 30 seconds. The connection is outbound only, so it works behind any number of routers, and it reconnects by itself after a reboot or a power cut. Tunnel-connected consoles authenticate with the API key alone. The "Upstream NAT detected" banner stays in the UniFi app, and that is fine; do not switch your ISP router to bridge mode to make it go away. Treat the command like a password: it carries a token tied to that one venue.

If you are on the username and password path

Create a dedicated local account on the controller (Local Access Only on UniFi OS; Local admin only on a Cloud Key or self-hosted controller) with the Administrator role, which CaptiFi needs to authorise guests. Your Ubiquiti cloud login will not work, because a ui.com account always has multi-factor authentication enforced and CaptiFi cannot complete that challenge. A local account with two-factor authentication does work: tick the 2FA box when you sign in and CaptiFi asks for the six-digit code.

Step 5: Choose the guest WiFi network

CaptiFi now lists every WiFi network on your controller, with the number of devices on each, so you can say which one the sign-in page belongs to. The screen is called Go live in the wizard and WiFi network when you come back to it later from the venue card.

1. Pick your guest network, not a private or staff one. Every device on the chosen network has to complete the sign-in page, and the device counts help you spot which network your own kit is on
2. Or choose Create a new guest network, type a name, and CaptiFi adds an open guest network across your access points
3. Click Go live (or Apply)

CaptiFi gates your choice and removes the sign-in page from any other network it was on, so a private network never stays walled by mistake. If you chose an existing network, CaptiFi gates that network as it is, with your session length and any speed limits kept as configured. You can swap the gated network later at any time.

On gateways with zone-based firewalling (newer Dream Machines, UCG and EFG), the sign-in page follows the Hotspot zone. Go to Settings, then Policy Engine, then Zones, and make sure the network your guest WiFi uses is in the Hotspot zone and nothing else is. CaptiFi tells you after applying if the zone needs attention and names the setting to change.

Step 6: Configure the hotspot portal by hand (only if needed)

Skip this step if CaptiFi connected through an API key or the Remote Tunnel. It writes these settings for you, and writes them again whenever you use Re-apply settings. You only need this when CaptiFi cannot write to your controller, which happens on some older firmware and some locked-down self-hosted setups.

1. In UniFi go to Settings, then WiFi, and create or open your guest network. Set the security to Open with no password and assign it to your guest network
2. On the same WiFi network, switch Hotspot Portal on and set Authentication to External Portal Server
3. Enter CaptiFi's portal: IPv4 address 46.62.168.7, domain site.app.captifi.io
4. Under Pre-Authorization Access (the walled garden), add site.app.captifi.io, app.captifi.io, fonts.googleapis.com and fonts.gstatic.com, plus *.captifi.io if your firmware accepts wildcards. Miss one and the page loads half-broken, or on iPhones does not load at all
5. Under Post-Authorization Restrictions, add 192.168.0.0/16, 172.16.0.0/12 and 10.0.0.0/8 so guests cannot reach your own network once online
6. In the landing page settings tick Show Landing Page, HTTPS Redirection Support, Encrypted URL and Secure Portal, and set the domain to site.app.captifi.io
7. Switch off Password, Voucher, Facebook, Payment and RADIUS on the hotspot portal, so CaptiFi is the only thing that authorises guests, and leave UniFi's own portal customisation alone
8. Click Apply Changes

If you sell WiFi access through CaptiFi, your Stripe and wallet payment domains also need to be in the pre-authorisation list. Contact support to confirm the current set.

Step 7: Test it with a phone

First, deal with the devices that cannot sign in. Receipt printers, card machines, back-office iPads, music players and digital signage cannot display a sign-in page, so once the portal is live they lose internet the next time they reconnect. Either move them to a private, password-protected staff network, which is the tidiest option, or add their MAC addresses under Pre-authorized devices on the venue card.

1. On a phone, turn WiFi off and on, then join the guest network
2. Your CaptiFi page should appear by itself within a few seconds. If it does not, open a browser and visit any http:// site, for example http://neverssl.com
3. Complete the form and check the phone can browse normally
4. Open Guest Visits in your CaptiFi dashboard: the visit should be listed within a minute

The portal applies gradually. Devices already connected keep working until they reconnect, and the sign-in page appears for each one as it rejoins, so a full changeover can take a day.

After setup: keeping the connection healthy

Everything lives on the venue card under My Locations on my.captifi.io. Connection status shows three things and refreshes while it is open: Online means CaptiFi has a verified route to the controller; Controller sending RADIUS traffic turns amber and reads STALE when nothing has arrived for 15 minutes, which is normal at a venue that is closed or has no guests connected; and Guests connecting through the splash page counts sign-ins. A venue with guests and a stale row is worth a support ticket, and quoting the exact message (it includes the controller's own reply, for example an api.err code) usually gets it resolved in one step.

Moved the controller, changed its port or replaced the API key? Click Update connection. Your current connection keeps working until the new one is verified, so guest WiFi is never interrupted. If the controller was factory reset or guests start seeing UniFi's own page instead of yours, click Re-apply settings: it re-pushes CaptiFi's captive portal, the pre-authorisation list and any speed limits, recreates the guest network only if it is missing, and does not disconnect guests already online. It replaces the whole portal configuration, so any walled garden entry you added directly in UniFi is reset. To move the sign-in page to a different network, click WiFi network and pick again. Pre-authorized devices takes a MAC address and an optional label, authorises the device on the controller straight away, refreshes it every night so it survives controller reboots, and de-authorises it when removed.

What CaptiFi adds to UniFi

Venues running CaptiFi typically capture 40-60% of connecting guests as email subscribers, around 400-1,200 emails per venue each month, and see 3-5x more Google reviews within 60 days. Essentials, with the device included, starts from $69/mo, shown in your currency on the pricing page, and every plan carries a 30-day free trial. If you only want guest capture and CSV export on the kit you already run, Lite is $24.99/mo for one site. The same external-portal pattern works on TP-Link Omada, Cisco Meraki, Aruba Instant On, MikroTik and Ruckus, so a group with mixed hardware runs everything from one account.

Troubleshooting

UniFi setups vary with hardware and firmware version. If a screen does not look like the one described here, email hello@captifi.io with the console model and the UniFi Network version and we will point you at the right setting.

CaptiFi is a guest WiFi marketing and captive portal platform for restaurants, bars, pubs, cafes, hotels, gyms, salons, retail and short-term rentals, built by CaptiFi Ltd in the UK and sold in GBP, USD, EUR, CAD, AUD and NZD to venues worldwide.