Installation Guide

Install Republic across your organisation

Republic is published in the Microsoft Teams store and ships with a companion Outlook add-in. Pick your platform below, or take the whole thing away as a PDF.

Download the PDF guide Already installed via manifest?

Free to add and use~10 minutes to deployMicrosoft 365 admin rights required

Installation guidePDFThe whole of this page as a PDF — Teams, Outlook, Microsoft 365 allowlisting, manifest downloads and troubleshooting.Download

Teams store upgrade guidePDFFor organisations already running Republic from an uploaded manifest who want to move to the store version.Download

Republic by Recyber

Recyber

Works in

Teams, Outlook & Microsoft 365

Cost

Free to add and use

Store

Microsoft Teams app store

Before you begin

A Teams Administrator or Global Administrator account for your Microsoft 365 tenant.
Your Republic tenant provisioned by Recyber — your onboarding contact confirms this before rollout.
A decision on scope: the whole organisation, or a pilot group first.

For administrators

Deploy Republic to your organisation

This is the recommended route. It installs Republic for everyone in scope so your people don't have to find or add anything themselves.

Open the Teams admin centre

admin.teams.microsoft.com

Find Republic in Manage apps

Go to Teams apps → Manage apps and search for "Republic by Recyber". Open the app to review its details and the permissions it requests.

Allow the app

If your organisation blocks third-party apps by default, set the app's status to Allowed. Where a permission policy is assigned to your users, make sure that policy also permits Republic.

Add Republic to a setup policy

Go to Teams apps → Setup policies and open the policy your users are assigned to — usually Global (Org-wide default). Under Installed apps select Add apps, choose Republic by Recyber, and add it. Add it under Pinned apps too so it appears in the Teams sidebar rather than behind the ellipsis.

Scope and save

Save the policy. For a pilot, create a separate setup policy and assign it to a group instead of editing the org-wide default. Microsoft can take up to 24 hours to push policy changes to every client, so schedule your launch comms accordingly.

Grant consent and confirm

The first time a user opens Republic they sign in with their work account. If your tenant requires admin consent for new applications, approve the request in Microsoft Entra ID → Enterprise applications so users aren't blocked at first launch.

Alternative

Deploy from the manifest instead

Only needed where your organisation deploys Teams apps as custom packages rather than from the store. A custom upload stays on the version you uploaded — the store version updates itself, so prefer that route where your policies allow it.

Download the app package

Download republic-teams-app.zip (Teams app v2.1.0). Upload the zip exactly as downloaded — do not unzip it first.

Download republic-teams-app.zip

Upload it as a custom app

In the Teams admin centre go to Teams apps → Manage apps, select Actions → Upload new app, and choose the zip.

Wait for it to appear

Depending on the size of your organisation the app can take up to an hour to show in the list.

Allow it and add it to a setup policy

Set the app's status to Allowed, then add it to the relevant setup policy under Installed apps and Pinned apps, exactly as with the store route.

Alternative

Let people install it themselves

If your organisation already allows users to add apps from the Teams store, no admin action is needed — staff can add Republic in under a minute.

Open the app store in Teams

In Microsoft Teams, select Apps in the left sidebar.

Search for Republic

Type "Republic" and select Republic by Recyber from the results.

Add the app

Select Add. Republic is free to add and use — there is no in-product purchase step.

Pin it

Right-click the Republic icon in the sidebar and choose Pin so it stays visible between sessions.

What your people will see

A welcome message from Republic in Teams introducing what the app does and how long it takes.
Around four short assessment questions a week, delivered in chat — under three minutes of effort in total.
After the first six weeks, personalised micro-learning based on the behaviours their answers surfaced.
Administrators get organisation-level reporting and user risk tracking in the Republic dashboard.

Troubleshooting

Republic doesn't appear in Manage apps

Newly published store apps can take up to an hour to surface in a tenant's app catalogue. Clear the search filters, confirm you are searching the Microsoft apps catalogue rather than Custom apps, and try again shortly.

Users can't see the app after a policy change

App setup policy assignments can take up to 24 hours to reach every client. Ask an affected user to sign out of Teams and back in, and confirm they are assigned the policy you edited.

Users are blocked at sign-in

This usually means your tenant requires admin consent for new applications. A Global Administrator can approve Republic in Microsoft Entra ID → Enterprise applications.

Email deliverability

Allowlist Recyber in Microsoft 365.

Republic sends phishing simulations and training email from mail.recyber.com. Microsoft 365 filters inbound mail hard — and a convincing simulation looks exactly like real phishing — so allowlist Recyber before you launch, or your people simply never see the test.

Use the advanced delivery policy — not a spam allow list

To keep tenants safe, Microsoft deliberately ignores ordinary allow lists, connection-filter IP allow lists and SCL:-1 mail flow rules for anything it scores as high-confidence phishing or malware — which is exactly what a good simulation looks like. The advanced delivery policy is the only method Microsoft supports for phishing simulations: it tells Microsoft Defender these messages are an authorised test, not a real attack, so they reach the inbox unfiltered while everything else stays protected.

Step 1 · admin

Find Recyber's current sending IP

The advanced delivery policy needs at least one sending IP. Recyber sends through a shared pool with no fixed, published IP list — so rather than us handing you a number that might change, you read the live one straight off a test message. This works without a dedicated IP.

Send yourself a test simulation

Trigger a test send to a mailbox you control — an admin can do this from the Republic dashboard. It doesn't matter that it isn't allowlisted yet; you only need its headers.

Find the message

Because Recyber isn't allowlisted yet, the test may land in Junk or be held in Quarantine (Defender portal → Review → Quarantine). Either is fine — the headers are intact wherever it lands.

Read the sending IP from the headers

The quickest route is Exchange admin centre → Mail flow → Message trace, which shows the sender IP directly. Or open the message headers (new Outlook / web: ⋯ → View → View message details; classic Outlook: File → Properties → Internet headers) and find the Authentication-Results line: spf=pass (sender IP is 12.34.56.78) smtp.mailfrom=mail.recyber.com. That IP is what you enter next.

Grab a couple more

Send two or three tests and note each distinct sending IP — a shared pool can use more than one. The policy accepts up to 10, so add them all to cover the pool.

Step 2 · Microsoft Defender portal

Add Recyber to the advanced delivery policy

You need the Security Administrator role (Email & collaboration) plus Organization Management (Exchange Online), or a Global Administrator account. It takes a couple of minutes.

Open the advanced delivery policy

In the Microsoft Defender portal, go to Email & collaboration → Policies & rules → Threat policies → Advanced delivery (under Rules). Or jump straight to the page with the link below.

security.microsoft.com/advanceddelivery

Open the Phishing simulation tab

Select the Phishing simulation tab, then Add. If Recyber already has entries there, select Edit instead and add to them.

Add the sending domain

Under Domain, enter mail.recyber.com. This is the MAIL FROM (envelope) and DKIM domain our simulations use, and it's the value that carries the trust. You can list up to 50 domains.

Add the sending IP(s) you found

Under Sending IP, enter each IP you read from your test messages. A single IP, a range (1.2.3.4-1.2.3.20) or a CIDR block (1.2.3.0/24) are all accepted, up to 10 entries. A message has to match at least one domain and one sending IP.

Add simulation link domains (only if needed)

Under Simulation URLs to allow, add the phishing-link root domains from your Republic console. This is only for links delivered in Teams messages or Office documents — links inside simulation emails are allowed automatically, so most tenants can skip it. Up to 30 entries.

Save and confirm

Select Add, then Close. The override applies across the tenant shortly after. Send one more test to confirm it now lands in the inbox. Defender leaves our simulations unfiltered, and Safe Links won't block or detonate our links (it still wraps them, which is expected).

What to enter

Sending domainmail.recyber.com

The MAIL FROM (envelope) and DKIM domain our simulations and report-forwards sign with. This is the value that carries the trust, so get it exactly right.

Sending IP addressRead it from a test message

We send through a shared pool that has no fixed published IP list, so you read the current IP straight off a test message — see the steps above. No dedicated IP is required.

Simulation link domainsFrom your Republic console

Only needed for links delivered outside email (Teams messages, Office documents). Links inside simulation emails are allowed automatically.

If your domain's MX record points somewhere other than Microsoft 365 — a secure email gateway such as Mimecast or Proofpoint — allow mail.recyber.com there too, and enable Enhanced Filtering for Connectors so Defender still sees our true sending IP rather than the gateway's.

Troubleshooting

Simulations land in Junk, or get quarantined

Check that mail.recyber.com and at least one current sending IP are both on the Phishing simulation tab, and that the test message matched one of each. A domain on its own isn't enough — Microsoft requires an IP match too.

It was working, then simulations started getting filtered again

Our shared pool can rotate onto a sending IP you haven't listed. Re-run the test-and-read-the-header check, add the new IP alongside the existing ones (up to 10), and save. If this becomes a nuisance, a dedicated sending IP would make it a one-time setup — talk to your onboarding contact.

Links are stripped, rewritten to a warning page, or blocked

That is Safe Links or a third-party gateway acting on the message. With mail.recyber.com on the advanced delivery policy, Safe Links wraps our links but won't block or detonate them. There's no need to add them to the "Do not rewrite the following URLs" list — that can actually raise spurious click alerts. If your MX points to a gateway, allow Recyber there as well.

Everything is allowlisted but mail still doesn't arrive

If your domain routes through on-premises Exchange or a gateway before Microsoft 365, Defender may see that hop's IP instead of ours, so no entry matches. Enable Enhanced Filtering for Connectors, or have simulations delivered straight to your Microsoft 365 MX record. Your onboarding contact can help you confirm which applies.

Reported simulations aren't scoring

Reporting is handled by the Republic Outlook add-in, not by this policy. Confirm the add-in is deployed — see the Outlook tab above — and that the user reported the message with the Report Phishing button.

Rollout

Telling your people.

Deployment is only half of it. Republic lands best when people know it is coming, so here is the announcement to send — copy it as it is, or make it sound like you.

Send it once the rollout has propagated

Setup policies can take up to 24 hours to reach every Teams client and a centrally deployed add-in up to six hours to reach every mailbox. Announce Republic after that window, not before — a message about an app people cannot yet see creates support tickets rather than momentum.

SubjectIntroducing Republic — your new security coach

Our organisation has partnered with Recyber to bring you Republic, a new behavioural security solution designed to help reduce human cyber risk. Accessible through Microsoft Teams and your browser, Republic acts as your personal security coach, offering support only when you need it and making security a positive, rewarding experience. By combining the latest behavioural science with storytelling and gamification, we help you build strong security habits naturally. This isn't just another training tool; it's security reimagined.

Republic also includes a phishing game called Interception. It helps you practise secure email reporting while unlocking levels with increasingly deceptive emails. Emails are delivered at a consistent pace across all levels, but you'll earn more Virtucoin for completing the harder ones. Interception is played directly from your email inbox using the Recyber add-in for Outlook — the Report Phishing button on your message ribbon — and your progress is managed through the Map section of the main Republic app in your browser, where you can view and select from available levels at any time.

You'll soon get a message from the Republic Teams bot, which will give you a quick tour and get you up and running.

If you require help or assistance you can access the Recyber Support Hub at https://recyber.atlassian.net/servicedesk.

Two things worth adding

Say who to contact internally. People who hit a problem should know whether to raise it with IT or go straight to the Recyber Support Hub.

Say plainly that Republic is not a monitoring tool. It coaches individuals and reports risk to the organisation in aggregate — stating that up front prevents the question being asked in the wrong tone later.

Files you need

Manifests and guides.

Served over HTTPS and always the current version. Download them on the machine you're running the admin centre from.

ZIPTeams app packageOnly for custom-app deploymentVersion 2.1.0. Contains the manifest and app icons. Upload the zip as-is — do not unzip it.republic-teams-app.zipDownload

XMLOutlook add-in manifestRequired to deploy the add-inOne file for classic Outlook on Windows, new Outlook, Outlook on the web and Outlook on Mac.republic-outlook-report-phishing.xmlDownload

Identifiers

Teams app ID1f518d36-07de-4ce5-860c-cc774c7bf327

Outlook add-in IDee7dee35-d48b-4221-904c-115af0017096

These are how you identify Republic in the admin centre — and how you tell the store version apart from a manually uploaded one.

Installation guide (PDF)Store upgrade guide (PDF)

Need a hand with rollout?

Our onboarding team can walk your administrators through deployment and provide staff communication templates.