So you downloaded OutreachOS. Let me walk you through it.
I wrote this to be the guide I wish every tool came with — no marketing, just how things actually work.
This is v0.1. I shipped it when the core things worked well — contacts, pipeline, email, templates — rather than waiting for everything to be perfect. This guide covers what's live today, and is honest about what's not there yet.
Before you start
Supported operating systems:
- macOS — Apple Silicon (M1 and later)
- Windows 10 or later (64-bit)
- Linux (x86_64) — AppImage, .deb, and .rpm packages available
Not supported yet:
- macOS on Intel (x86_64)
- Mobile (iOS / Android)
I built this as a desktop app deliberately — your data stays on your machine, no account needed, no cloud dependency. The only time you need internet is when you're sending emails or connecting your email account for the first time.
I develop primarily on a Mac with Apple Silicon, so that's where things are most tested. Windows and Linux builds are generated from the same codebase and should work well, but if you hit something platform-specific, let me know.
Download & install
macOS (Apple Silicon)
Head to the GitHub Releases page and download the .dmg file for the latest
version.
Open the .dmg, drag OutreachOS into your Applications folder, and launch it.
"OutreachOS is damaged and can't be opened" — here's the fix
macOS will show this error on Ventura (13) and later when you try to open the app. It sounds worse than it is. The app isn't actually damaged — macOS is blocking it because it isn't signed with an Apple Developer certificate yet.
The fix takes about 30 seconds and you only need to do it once.
-
Open Terminal Press ⌘ + Space to open Spotlight, type "Terminal", and press Enter.
-
Run this command Copy and paste the following line into Terminal and press Enter:You won't see any output. That's normal — it means it worked.
xattr -cr /Applications/OutreachOS.app -
Open the app Go back to your Applications folder and open OutreachOS normally. The error won't appear again.
What does that command actually do?
When you download anything from the internet, macOS attaches an invisible tag to the file called a
quarantine attribute. On unsigned apps, newer versions of macOS refuse to open files with this tag.
The xattr -cr command removes it. That's all it does — it doesn't change the app itself in
any way.
Intel Macs are not supported in the current release.
Windows (64-bit)
Download the .exe installer from the GitHub
Releases page and run it.
Windows may show a SmartScreen warning that says "Windows protected your PC." This happens for the same reason as the macOS warning — the app isn't signed yet. Click "More info" and then "Run anyway."
The installer will place OutreachOS in your Start menu and optionally on your desktop.
Linux (x86_64)
Three package formats are available from the GitHub Releases page:
OutreachOS_0.1.3_amd64.AppImage— runs on any distro, no installation needed. Make it executable (chmod +x) and run it.OutreachOS_0.1.3_amd64.deb— for Debian, Ubuntu, and derivativesOutreachOS-0.1.3-1.x86_64.rpm— for Fedora, RHEL, openSUSE, and derivatives
Where does my data live?
On macOS: ~/Library/Application Support/com.outreachos.app/
On Windows: C:\Users\YourName\AppData\Roaming\com.outreachos.app\
On Linux: ~/.local/share/com.outreachos.app/
Your entire contact database lives in that folder as an encrypted file called outreach.db.
I chose SQLCipher (encrypted SQLite) specifically so your data is protected even if someone gets access to
this file. OutreachOS never phones home — nothing leaves your machine.
Your first look at the app
When OutreachOS opens, you'll see a mostly empty interface. That's intentional — I didn't want to fill it with fake sample data. Here's what you're looking at:
Sidebar (left): This is how you navigate. I kept it minimal — People (your contacts) and Templates are where you'll spend most of your time. The other pages — Emails, Tasks — exist as placeholders. I'm building those next.
People page: Your contact database. Starts empty. Supports two views — a table and a Kanban board. Toggle between them with the icons in the top right.
Dashboard: Partially built. I have plans for it, but I wanted to ship the core workflow first. For now, go straight to People.
Settings (bottom of sidebar): This is where you connect your email, configure your pipeline stages, and manage security. You'll visit it once during setup, and probably forget it exists after that — which is the goal.
Before you do anything else, go to Settings and connect your email account. Everything else depends on that.
Connecting your email account
OutreachOS sends emails through your existing Gmail or Outlook account — I didn't want to run a mail server or ask you to trust me with your credentials. Instead, it uses OAuth, which means you log in directly with Google or Microsoft and grant specific permissions. Your password never touches OutreachOS.
There's one setup step that takes a bit of effort: creating OAuth credentials through Google or Microsoft's developer console. I know that sounds intimidating — I spent a while figuring out how to make this simpler and unfortunately this is the simplest it gets without me paying for Google's app verification (which I'm working on). The steps below walk you through it exactly.
Setting up Gmail
-
Go to Google Cloud Console Open console.cloud.google.com in your browser. Sign in with the Google account you want to use for sending emails.
-
Create a new project Click the project dropdown at the top of the page (it might say "Select a project" if this is your first time). Click "New Project." Name it anything — "OutreachOS" works. Click "Create."
-
Enable the Gmail API In the search bar at the top, search for "Gmail API." Click it in the results, then click "Enable."
-
Set up the OAuth consent screen In the left sidebar, go to "APIs & Services" → "OAuth consent screen." Choose "External" for User Type and click "Create." Fill in the App Name ("OutreachOS" is fine), your email for the support email, and your email again for the developer contact. Everything else can be left blank. Click "Save and Continue" through the Scopes and Test Users screens without changing anything. On the Summary screen, click "Back to Dashboard."
I know this feels like a lot of clicking through Google's console. The good news is you only do this once.
-
Add yourself as a test user Still on the OAuth consent screen, scroll down to "Test Users" and click "Add Users." Enter the Gmail address you'll be sending from. Save.
-
Create OAuth credentials In the left sidebar, go to "APIs & Services" → "Credentials." Click "Create Credentials" → "OAuth client ID." Set Application type to Desktop app, name it anything, and click "Create." A popup will show your Client ID and Client Secret. Copy both — you'll need them in the next step.
-
Enter credentials in OutreachOS Open OutreachOS and go to Settings → Email Integration. Click "Configure Gmail Credentials." Paste your Client ID and Client Secret into the fields and save.
-
Connect your account Click "Connect Gmail Account." Your browser will open with a Google sign-in screen. Sign in with the same account you added as a test user in Step 5. You may see a warning saying "Google hasn't verified this app" — click "Advanced" then "Go to OutreachOS (unsafe)." This is normal for apps in testing mode. Grant the requested permissions. Your browser will redirect and OutreachOS will confirm the connection.
If you see an "Access blocked" error, it usually means you forgot to add your email as a Test User in Step 5. Go back to the OAuth consent screen, add your email, and try again.
Until the app is fully verified by Google — which costs money and takes weeks of review that I'm working through — it runs in "testing mode." That's why you need to add yourself as a test user. It's a Google limitation, not a security issue. Add your own email and you're good.
Setting up Outlook
The Outlook setup follows a similar pattern through Microsoft Azure.
-
Go to Azure Portal Open portal.azure.com and sign in with your Microsoft account.
-
Register a new application Search for "App registrations" in the top search bar and select it. Click "New registration." Name it "OutreachOS," set Supported account types to "Accounts in any organizational directory and personal Microsoft accounts," and set the Redirect URI to Public client/native with the value
http://localhost:8080. Click "Register."
-
Copy your Application (Client) ID On the app overview page, copy the Application (client) ID. This is your Client ID.
-
Create a client secret In the left sidebar, click "Certificates & secrets." Click "New client secret." Add a description (anything) and set an expiry (24 months is fine). Click "Add." Copy the Value immediately — it won't be shown again.
-
Add API permissions In the left sidebar, click "API permissions." Click "Add a permission" → "Microsoft Graph" → "Delegated permissions." Search for and add:
Mail.Send,Mail.ReadWrite,offline_access. Click "Grant admin consent" if the button is available — that's fine if it's not, depending on your account type. -
Enter credentials in OutreachOS Open OutreachOS and go to Settings → Email Integration. Click "Configure Outlook Credentials." Enter your Client ID and Client Secret and save.
-
Connect your account Click "Connect Outlook Account." Your browser will open with a Microsoft sign-in. Sign in and grant permissions. OutreachOS will confirm the connection.
Once your account is connected, OutreachOS will sync your recent email threads so it can show you email history per contact. This happens in the background and may take a minute on first sync.
Microsoft's Azure portal is honestly more confusing than Google's console, but once you get through it, the connection is solid. If you get stuck on any step, open an issue and I'll help you through it.
Adding contacts
Add one manually
Click the "Add Contact" button in the top right of the People page, or press ⌘N (Mac) / Ctrl+N (Windows).
Only First Name and Last Name are required. Everything else — email, company, title, LinkedIn URL — is optional and can be filled in later.
Click Save. The contact appears in your list immediately.
Importing from LinkedIn
If you have a list of contacts from LinkedIn, a spreadsheet, or anywhere else, you can import them all at once via CSV or Excel. See the Importing Contacts section below for a full walkthrough.
What those fields actually mean
Intelligence Summary — This is my favorite field in the whole app. It's freeform — write whatever context matters to you: how you met them, what they mentioned in a call, what role you're targeting, what to say in a follow-up. I built it because every CRM I've used buries the actually useful context behind structured fields that never quite fit.
Pipeline Status — Where this contact sits in your outreach process. More on this in the next section.
Tags — Optional labels for grouping contacts. I use things like "Series A", "Engineering", "Warm Lead", "Follow Up" — whatever categories make sense for how you think about your pipeline.
Understanding the pipeline
Every contact has a status — a label that tells you where the relationship stands. I set up five defaults that match a typical cold outreach flow:
- New — Just added, haven't reached out yet
- Contacted — You've sent an initial message
- Replied — They've responded
- Interested — Things are moving forward
- Not Interested — They passed or went cold
These are starting points, not rules. I wanted the pipeline to be yours, not mine — rename them, change their colors, create new ones, delete ones you don't use. All from Settings → Pipeline.
Kanban vs. Table
The People page has two views:
Table view — A spreadsheet-style list of all your contacts. Good for scanning, bulk editing, and filtering.
Kanban view — A board where each column is a status and each card is a contact. Drag a card to a new column to update their status. Good for visualising your pipeline at a glance.
Both views show the same data. Use whichever feels right for what you're doing. I personally switch between table view for bulk work and Kanban when I want to see the big picture.
Tip: The Kanban view is most useful once you have 20+ contacts spread across different stages. If you're just getting started, the table view is simpler.
Sending an email
Open any contact's profile by clicking their name. From the profile, click "Compose Email" to open the compose window.
The compose window lets you:
- Write a subject and body
- Choose which connected email account to send from (if you have multiple)
- Send immediately or schedule for a future date and time
Sent emails appear in the Emails tab of the contact's profile, so you always have a record of what you sent and when.
Scheduling
To schedule an email, click the dropdown arrow next to the Send button and select "Schedule." Pick a date and time. The email will sit in your queue and send automatically — as long as OutreachOS is running on your machine at that time.
One honest limitation: scheduled emails only send if OutreachOS is running on your machine at that time. I haven't built a background service yet — it's the thing I most want to fix. For now, schedule emails for times when you'll have the app open.
Templates and mail merge
If you're sending the same type of email to many people — cold outreach, follow-ups, thank-you notes — templates keep you from rewriting the same thing every time. I built the merge system to be dead simple: you write the structure once, and OutreachOS fills in the personal details automatically.
Creating a template
Go to Templates in the sidebar. Click "New Template."
Give it a name (this is just for your reference — the recipient never sees it). Write your subject line and body.
Variables
Templates support merge variables — placeholders that get replaced with real contact data
when you send. Variables look like this: {{firstName}}
| Variable | What it becomes |
|---|---|
{{firstName}} |
Contact's first name |
{{lastName}} |
Contact's last name |
{{fullName}} |
Contact's full name |
{{companyName}} |
Contact's company |
{{title}} |
Contact's job title |
Example subject line:
{{firstName}}, quick question about your role at {{companyName}}
When sent to Sarah Chen at Stripe, this becomes:
Sarah, quick question about your role at Stripe
Using a template
When composing an email, click "Choose Template" to load one. The variables will be pre-filled based on the contact's saved data.
You can edit the email after loading a template — it's not locked. I designed templates as a starting point, not a straitjacket.
If a variable is blank (for example, the contact has no company saved), OutreachOS will insert an empty string. Before sending to a large list, make sure the relevant fields are filled in on each contact.
Importing contacts from LinkedIn (or any spreadsheet)
This was one of the first features I built, because I knew nobody wants to manually type in 200 contacts. If you have a spreadsheet from LinkedIn, a CSV you built yourself, or anything with headers, you can import everything at once.
How to export from LinkedIn
-
Go to linkedin.com and click your profile picture → "Settings & Privacy"
-
Click "Data privacy" → "Get a copy of your data"
-
Select "Connections" and request the archive
-
LinkedIn will email you a download link, usually within 10 minutes
-
Download and unzip the file — you want the file called
Connections.csv
Running the import
In OutreachOS, click the Import button in the top bar of the People page (or press ⌘I).
Step 1 — Column mapping: Select your CSV or Excel file. OutreachOS will read the column headers and ask you to map each one to a contact field. For a LinkedIn export, the mapping usually looks like this:
| LinkedIn column | Map to |
|---|---|
| First Name | First Name |
| Last Name | Last Name |
| Email Address | |
| Company | Company |
| Position | Title |
| LinkedIn Profile URL | LinkedIn URL |
Step 2 — Duplicate check: OutreachOS will scan for contacts already in your database and tell you how many new contacts it found vs. how many duplicates. I built three options because different situations call for different approaches:
- Skip duplicates — Only import new contacts. Existing records are untouched.
- Merge — Import new contacts, and fill in any missing fields on existing contacts (without overwriting anything you've already entered).
- Import all — Insert everything, ignoring duplicates.
For most people, Skip or Merge is the right choice.
Supported file formats
.csv(any spreadsheet exported as CSV).xlsx(Excel files)
Files must have a header row. Columns don't need to be in any particular order — you'll map them manually in Step 1.
What's working in v0.1
I want to be upfront about where things stand. Here's what's fully built, what's partially there, and what's next.
Fully working
- Contact management (add, edit, delete, search)
- Pipeline statuses — including custom stages from Settings
- Tags — create, assign, and filter by tags
- Kanban and table views
- CSV and Excel import with duplicate detection
- Email templates with mail merge variables
- Compose, send, and schedule individual emails
- Gmail and Outlook OAuth integration
- Email sync — threads linked to contacts automatically
- App lock with PIN (Settings → Security)
- Data export as JSON (Settings → Data)
- Command palette — press ⌘K to search or jump anywhere
Partially built
- Dashboard — The page exists but shows placeholder stats. Real data is coming.
- Activity timeline — The timeline on a contact's profile currently only shows when the contact was added. It will eventually show every email sent, opened, and replied.
Placeholders only (not built yet)
- Emails page — Will become a lightweight unified inbox.
- Tasks page — Will be a job-search to-do list tied to contacts.
- Notes page — Similarly a placeholder.
The next thing I'm building is multi-step email campaigns — sequences of follow-ups that send automatically based on whether the previous one got a reply. After that, email open and click tracking. Both are in progress.
Known issues in v0.1
Background email sending isn't supported yet.
Emails scheduled for a future time only send if OutreachOS is open and running at that time. If the app is closed, the email won't send until you reopen the app. This one bugs me the most — I'm actively working on a background service to fix it.
Gmail "app not verified" warning.
When connecting Gmail for the first time, Google will show a warning screen. This is because the app is in testing mode and hasn't been through Google's verification process yet. It's safe to proceed — click "Advanced" and then "Go to OutreachOS." See Setting up Gmail for full details.
Activity timeline is hardcoded.
The timeline on every contact's profile shows "Contact created" and nothing else, regardless of what you've done. Dynamic events (emails sent, status changes, replies) will appear there in the next release.
Intel Mac (x86_64) is not supported.
The current release only ships a native Apple Silicon (aarch64) build for macOS. Intel Mac support is not planned for the near term.
Platform-specific issues may exist.
I develop and test primarily on macOS Apple Silicon. If you hit a Windows or Linux bug that isn't listed here, please report it — it's almost certainly something I can fix once I know about it.
Got a question or found a bug?
OutreachOS is a personal project — it's just me building this. I genuinely want to hear from people using it, whether it's a bug report, a feature idea, or just telling me something felt confusing.
Want to contribute?
OutreachOS is fully open source — the code is on GitHub and I'd genuinely love help from other developers. There's no formal process, no contributor agreement to sign. If you see something you want to fix or build, open a PR. Even small things: typos, a cleaner query, a UI detail that's been bugging you. All of it is welcome.
The developer wiki has the architecture overview, setup instructions, and a breakdown of how the Rust + React layers fit together. The stack is Tauri 2 (Rust) + React + TypeScript + SQLite — if any of that excites you, come take a look.
The features I most want help on right now: the background email service, the activity timeline, and the Emails page. If you've built something like that before and want to take a crack at it, I'm here to review and ship fast.