NimbusOS is an outbound sales infrastructure platform built for agencies and in-house sales teams that want to run cold email at real scale. This guide takes you from a new workspace to a live campaign. The order matters. Skipping steps leaves the sending fleet cold and the data unscored, and the platform will block campaign start in both cases.
You will learn how to create a workspace, connect a sending fleet, import and score contacts, build a sequence, and launch a campaign. If you follow the steps in order, first send happens the same day. Expect around forty five minutes of hands-on work, plus whatever warmup time the sending fleet needs before the platform allows a cold launch.
What You Need Before You Start
Three things need to be true before you begin.
You need a workspace owner account. The first email you sign up with becomes the owner of the workspace. Every additional teammate is invited as a WorkspaceMember with a role of owner, admin, member, or viewer. Roles are checked on every API call through WorkspaceSecurityMiddleware, so plan the hierarchy up front if you are onboarding an agency.
You need sending infrastructure. NimbusOS sends through ReachInbox by default. You can either let NimbusOS buy and provision fresh domains plus inboxes end to end through the outbound infrastructure pipeline, or bring existing mailboxes through BYOSMTP. Either way, an inbox has to pass a domain readiness check with a score of 80 or higher before the platform will allow campaign enrollment.
You need a contact list. NimbusOS can import from CSV, sync from HubSpot or Salesforce, or source directly through Apollo. Whatever the source, contacts flow through the same ImportJob pipeline: upload, field map, deduplicate against the GlobalContact table, suppression check, and finally insert as live Contact rows.
Step 1: Create Your Workspace
Sign up at getnimbusos.com and choose a workspace name. The workspace is the tenant boundary. Every record from contacts to campaigns to billing invoices is scoped to a workspace through the TenantScopedMixin. Nothing crosses that boundary without explicit sharing.
During sign up you will be asked whether you are running NimbusOS for one team or as an agency. Agency mode enables the Client hierarchy. A master Client record represents the agency itself, and sub clients represent each agency customer. All contact data, sending infrastructure, and reporting can be scoped down to a single client for white label reporting, or rolled up to the agency for operational dashboards.
If you are not sure which mode you want, choose single team. You can turn on agency mode later from Account Settings without data migration.
Once inside the workspace, the first thing to do is finish the onboarding checklist. The checklist is not cosmetic. It walks through the minimum configuration that the campaign launch gate requires: sending accounts, a verified domain, at least one imported contact, and one saved sequence template.
Step 2: Provision or Connect Sending Accounts
Open the Email Accounts page at /email-accounts. You have three paths.
Path A: Full Infrastructure Pipeline
If you want NimbusOS to build a fresh sending fleet for you, click "Launch Infrastructure". The form asks for a brand, a domain count, and an inbox count per domain. Under the hood this calls launch_from_brand(brand, domain_count, inbox_count_per_domain, ...). That kicks off the OutboundInfrastructureJob lifecycle: domain generation, NameSilo availability check, domain purchase, Cloudflare zone and DNS record creation, DNS verification with exponential backoff, a maturation window, ReachInbox inbox provisioning, and warmup enrollment.
The whole pipeline is asynchronous. Expect 48 to 72 hours for DNS to verify and at least 2 weeks of warmup before the deliverability brain will clear the fleet for cold outreach. You can monitor progress from the Email Accounts page. Each inbox shows a stage computed by get_inbox_stage() from days warming and cumulative warmup sends.
Path B: Connect an Existing Mailbox
If you already have a sending domain and authenticated mailboxes, click "Connect Account" and choose Gmail, Microsoft 365, or custom SMTP and IMAP. OAuth flows complete in place. For SMTP and IMAP, credentials are encrypted with Fernet at rest.
Every connected mailbox becomes an EmailAccountHealth row. The health score is a 0 to 100 composite of reputation, bounce rate, complaint rate, and engagement. The rotation engine skips accounts that fall below the campaign's health floor, so one struggling inbox will never take down a send run.
Path C: Connect to ReachInbox Directly
If you are already a ReachInbox customer with a warmed fleet, the fastest path is to paste your ReachInbox API key into Integrations. NimbusOS will sync every ReachInbox account into EmailAccountHealth, pull warmup analytics, and register the accounts as available for rotation. Every send still flows through ReachInbox, but campaign definition, contact scoring, reply classification, and analytics live in NimbusOS.
Step 3: Import and Score Contacts
Contacts live in the Contact table, scoped to the workspace and optionally to a sub Client. The import flow is the same whether you are uploading a CSV or syncing from a CRM.
Go to /contacts and click Import. You can drag and drop a CSV, paste a Google Sheet export, or pick a connected data source. The platform creates an ImportJob and opens the field mapping panel.
Field mapping is the single most important step in the import. NimbusOS stores your mapping as a reusable FieldMapping record so future imports from the same source auto fill. Map at minimum email, first name, and company domain. Company domain drives a second level of deduplication through the Company model and is what the enrichment cache uses as a lookup key.
The import pipeline runs through six stages: parse, deduplicate against GlobalContact, enrichment (optional), suppression check, ICP segmentation, and lead scoring. By the time the job completes every imported contact has an icp_tier label (A, B, C, or D), a lead_score integer, and a grade letter. That trio is what drives sequence eligibility.
If a contact is already in the GlobalContact table from another import or another workspace on the same platform, the dedup step prevents double outreach. ClientAssignment records track which client currently owns that contact with a priority number, an expiry, and an outcome field. This matters for agencies: two sub clients on the same agency cannot both put the same prospect into a campaign.
Scoring runs automatically on import if an AutomationRule is configured with the on_contact_import trigger. Otherwise trigger it manually from Lead Scoring. The scoring model combines three weighted components: fit (default 40 percent), engagement (30 percent), and intent (30 percent). You configure rules per workspace.
Step 4: Build Your First Sequence
Sequences in NimbusOS are built in a visual editor at /sequences. The editor persists full React Flow state so a sequence opens exactly as you drew it, including branching nodes and delay timers.
Start with a two step template. Step 1 is a cold opener. Step 2 is a follow up that fires three business days later if no reply. Every step has a template bound to it, a delay value and unit, and an optional send_only_if condition. Steps can also carry stop_if_replied and stop_on_domain_reply flags so the sequence self closes when a prospect or their colleague answers.
Templates use Jinja style variables. The most common are {{first_name}}, {{company}}, and {{industry}}. For agencies running account based outreach, pull in custom fields you mapped during import. If the contact has a PersonalizedLine record from the hyper personalization engine, drop in {{personalized_first_line}} to use the AI generated opener.
Save the sequence. The save triggers a schema markup generation pass, which produces the JSON-LD snippet the email engine injects for AI inbox placement scoring.
Step 5: Launch the Campaign
Go to /campaigns and click New Campaign. Pick a campaign type. For first sends, choose cold_outreach. The other three types (warmup, nurture, re_engagement) behave differently and use different throttles.
Attach the sequence you built. Attach your sending accounts. The platform suggests the right pool automatically based on EmailAccountHealth scores, but you can override per campaign.
Filter contacts. You can pick a saved Segment, a tag, or an ICP tier. A common first campaign is icp_tier in ['A', 'B'] and grade in ['A', 'B']. That bounds the first send to the two hundred or so highest fit contacts in the list, which is where you want to burn your first impressions.
Set send limits. daily_send_limit caps total sends per day. max_new_leads_per_day caps new prospects entering the sequence per day and is usually the more important number. For a fresh fleet start at 20 per inbox per day and ramp weekly.
Click Launch. At this point the deliverability brain runs the resume gate check. If the fleet does not have at least 20 inboxes at stage 3 or higher, or the 7 day bounce rate is above 2 percent, the launch is blocked with a specific reason. This is intentional. Launching cold outreach on an unwarmed fleet is how small agencies lose an entire sending domain in a week.
If the gate passes, the campaign moves to active status, sequences start enrolling contacts, and the first sends queue for the next hourly batch.
Step 6: Watch the First 24 Hours
Once the campaign is live, the unified inbox at /unified-inbox becomes your control tower. Every reply, bounce, and out of office arrives there. The ML categorizer tags each message with one of ten intents: interested, not interested, OOO, bounce, question, meeting request, positive reply, negative reply, neutral, or spam. Confidence score is shown next to each tag. You can override manually and the platform learns from the correction.
Watch for three things in the first day.
Bounce rate over 2 percent. The bounce intelligence layer classifies every bounce and feeds BouncePattern to the scheduler. Hard bounces kill the contact immediately. Soft bounces enter a retry queue with an exponential delay. If bounce rate crosses the threshold, NimbusOS auto pauses the campaign and drops an alert into the Deliverability Alerts feed.
Spam complaint rate over 0.1 percent. Same auto pause logic. Spam complaints are a hard red flag. One complaint per thousand sent is the ceiling before reputation damage is difficult to reverse.
Reply intent distribution. If you get ten replies in the first twelve hours and nine of them are not_interested, the offer or the targeting is off. The first 24 hours of a new campaign is the fastest, cheapest feedback loop you will ever get. Use it.
Frequently Asked Questions
Can I skip the warmup requirement if I connect already warmed inboxes?
Yes. The resume gate reads the current state of every inbox, not a fixed cold start period. If you connect a ReachInbox account with a warmup history of 60 days at stage 5, the gate treats it as ready. Bring evidence, not just claims.
What happens if I import duplicate contacts?
The dedup step in ImportJob checks every row against GlobalContact keyed on email. Duplicates are flagged as skipped in the job report. The existing contact record is updated with any new fields from the import rather than replaced.
Can I connect an inbox from a provider that is not on the dropdown?
For any inbox that speaks standard SMTP and IMAP, use the custom SMTP option. Credentials are encrypted with Fernet. The first send test must succeed before the account is registered. If it fails, the reason is shown in plaintext so you can fix the credential or the TLS setting.
Why does the platform refuse to launch my campaign even though every inbox looks green?
The deliverability brain checks fleet level health, not per inbox. If you only have five healthy inboxes, fleet level stage coverage does not clear the 25 percent at stage 3 threshold. The fix is to provision more inboxes, not to argue with the gate.
How do I know the first send actually happened?
Go to the campaign detail page. The live send log shows every attempt with a timestamp, the inbox that sent, the contact receiving, and the status. The campaign also emits total_sent and delivered counters that you can surface in any report.
What to Read Next
Once the first campaign is live, the most useful next pages are Email Warmup for a full picture of how the sending fleet graduates through stages, Sequence Builder for conditional branching and sub sequences, and Deliverability Overview for how the NDS score is computed and when it will auto pause a campaign.