The Startwave guide

What lives where

Use the workspace to review records and run day-to-day work. Use the API when your own tools need to read or change the same workspace. The reference describes exact scopes, fields and recovery paths.

In the workspace, use ⌘ K or Ctrl K to open Go to… and jump to a destination.

A typical workflow

Click a sortable column heading to change the order; click it again to reverse it. The service orders the full result, including later pages. Columns without supported ordering remain plain headings.

Adjust daily sending

Use −, + or type a daily allocation in Campaigns. Changes save automatically within your available allowance. The ceiling includes first emails and follow-ups; zero stops new campaign sending and preparation.

Enrolled workspaces also see Sending pool in Scheduling: Mailboxes (the default), Transactional, or All. Choose which authorized capacity this campaign may use, then Save. You can preview window fit for the unsaved choice. If access is withdrawn, the saved choice stays visible until you explicitly change it. Transactional describes authorized capacity; all content and sending safeguards still apply.

Rebalance previews a split that favors ready work today, then the next sending day. Review the dated comparison and choose Apply. Preparation is shown separately. An unavailable preview has no numeric comparison or Apply; no improvement leaves your allocations unchanged. Neither a preview nor a saved allocation guarantees delivery.

For integrations, use the read-only preview and atomic allocation update. Recover an uncertain update by its original operation ID before trying another.

Inbox files and limits

The incoming limit is 10 MiB for the entire encoded email, including headers, encoding and files. There is no smaller per-file allowance, but encoding means a 10 MiB file will not fit. Larger messages and unusually large text bodies are held for operator review; mailbox originals are not deleted. Newly supported messages with more than 1 MiB of decoded text are held rather than silently clipped. Historical files can be unavailable when their originals were not retained. Download available files or the retained original from the message; files are not previewed or executed. This is not unlimited or 5 GB email support. Outgoing attachments are not supported.

Keep a campaign ready

Open a campaign’s People tab for today, the next sending day and any shortfall. The signal summarizes prepared sending coverage, including follow-ups; it is not the number of uploaded leads. Outside sending days, check the next window.

Add leads before the estimated supply runs low. Unchecked people are not guaranteed ready capacity, and estimates can change. Open details only when a hold or shortfall needs attention.

Edit a running campaign

Edit the sequence, waits, sending days or volume, then Save. Changes apply to unsent emails; sent emails keep their original content and conversation. Updating scheduled emails happens in the background.

New follow-ups apply prospectively. They do not restart old finished audiences. A completed campaign requires explicit Resume before sending again. If a response is lost, recover the original Save instead of submitting another action.

Previous contact and opt-outs

Startwave applies a 30-day workspace-wide recontact cooldown to the first email of a new sequence after recorded contact. For example, someone contacted 12 days ago waits until the exact recontact cooldown end shown in People. That date does not promise a send: fresh checks, other active campaigns, suppressions and the campaign’s sending rules still apply. Existing follow-ups keep their sequence; this cooldown does not restart after every follow-up and block the next one.

Opt-outs and suppressions have no automatic expiry. Waiting 30 days does not remove them or restart a stopped sequence. A reply or unresolved send outcome also needs its own handling.

To bring outreach history from another tool, choose External contact history when uploading a CSV or NDJSON file, when available. Map email and either map a source column or enter a shared History source, such as Cofounder October outreach. An email-only CSV works with that shared source. A row’s own source takes precedence; the shared value is fixed once upload begins. You can also map a row reference and an ISO contact date/time including its timezone, such as 2026-10-01T09:00:00Z. Review the file, approve it, then choose Record history. Keep an unknown contact date blank: the person stays held for review, with no invented contact date or expiry. This records history about a person; it does not create Contacts or opt-outs. Externally reported contact remains separate from Startwave acceptance and creates no native sends, deliveries or charges.

Read upload receipts and share exports

A file’s valid for import count checks format and fields. It does not mean every email is verified or ready to send. Keep the original file receipt: it includes input rows that may never join the campaign. Its related job shows saved Contact outcomes, including invalid or excluded rows. Campaign admission progress separately reports processed, added, held and already-admitted people. Saving a Contact, admission and current eligibility answer different questions.

Background work continues after approval even when you close the browser. Return to the original upload and Activity for progress. Pending checks are still pending; an unavailable count is not zero. Open campaign People for the latest eligibility observation. Upload does not authorize unlimited checking of the entire file.

Use More → Export people in the campaign header to share all contacts with status, contacted contacts, ineligible contacts or people needing review. The contact CSV has one row per admitted person. Choose Queued emails for one row per queued message, including its sequence step and due time. One person can appear several times. Choose Original upload results, then select the original import or admission job to export one row per input row, including invalid, duplicate, held or pending outcomes.

To include a whole connected List, choose it from More → Export people or More → Connected lists and select Export with status. Review the displayed membership revision. The file includes every List member: admitted people have current campaign eligibility, while others are explicitly Not admitted. No readiness is inferred for those members, and locked email values stay blank. Export does not buy data, verify emails, admit people or launch a campaign.

For example, share the contacted CSV with a cofounder so they can compare addresses before starting their own outreach. Preserve the recorded status and observation time. An uncertain submission is not proof that an address has never been contacted, and Startwave cannot infer outreach from another tool until you supply its history.

Include or exclude company domains

When the service advertises uploaded domain filters, open Domains in Search. Choose a saved Include or Exclude set, or import a one-column CSV or one domain per line. Website URLs are accepted; email addresses are not. Review the saved normalized count and any rejected rows before applying the filter.

Choose Include to search within the selected companies, Exclude to omit them, or both. Exclusion wins an overlap. Your other Search filters still apply. Clear a selection to remove that condition; archiving a saved set makes existing references unavailable until you restore the set, replace it or remove it from the query. Domain filters do not change email opt-outs or suppression lists.

See company-domain filters in the API reference for limits, counts and recovery. Availability follows the dataset’s advertised capabilities.

Read and manage replies

Open a conversation to read the latest message, assign it or reply. After about five continuous seconds with the latest incoming message visible, the conversation is marked read for you. Moving away, switching tabs, hiding the window or opening a dialog stops the timer. Mark unread keeps it unread until you reopen that conversation.

Read by shows current teammates who have reached the conversation’s latest attention point. It does not report whether a recipient opened an outgoing email, and it is not a historical record of every reader. Reading does not close, reassign or reply to a conversation.

Unlocks, updates and automatic top-ups

Company basics are free and remain limited to the seven approved company columns. A new People bundle costs $0.02 under the current TEST policy. Saving a preview is not an unlock; missing email or phone values are not a guarantee that those values can be purchased.

One inspector Unlock click approves one record up to its displayed unit price. Free company unlocks and funded single People unlocks complete in place without a separate estimate dialog. Bulk unlocks retain explicit approval. Already-owned exports do not need a second approval when no updates or new data are selected. Your open inspector, selected IDs, filters and page stay in place.

Visible owned rows are checked in a bounded backend batch. Update available appears only when the approved licensed content differs; unavailable evidence is not called current. A check never buys data or overwrites your saved snapshot.

Data funds and Auto top-up in an estimate open their controls without leaving the request. On means the saved approval is currently ready; Needs review means the current card, approval or limits need attention. A policy change can require renewed approval even when saved intent is enabled. Review and save the bounded terms, then continue the same original request; do not submit a replacement purchase.

New card setup visibly selects automatic data top-ups with the server-supplied refill and spending limits. Uncheck to save the card only. A previous explicit Off stays off; recovering an uncertain card setup does not grant new payment consent. Automatic data-funding limits are separate from your sequencer subscription, which has its own capacity, 30-day price and recurring approval. Paying for capacity does not guarantee sends: qualified leads, windows and mailbox readiness still apply.

A few useful terms

Data access and costs

Select records, then choose Unlock or Export. Export downloads an observed already-owned or provided selection directly from saved data. No purchase, refresh or second confirmation is needed. Other finite selections start one service-side estimate; complete unchanged zero-charge reuse proceeds automatically. Updates, new data, exclusions or a positive price open a review with the exact breakdown. Nothing new is purchased before you confirm.

Latest export checks owned data for updates and includes eligible new unlocks. An Update available label routes the selection through review, not a silent refresh. Choose Data → Export options to change columns, file format or version. Owned only exports eligible owned/provided saved data without a purchase; unavailable freshness does not mean the saved data is current. Unlock missing data and Refresh owned data are separate actions. A saved contact or List membership does not itself license every field.

A compact progress panel starts the original download once and keeps a Download button as a fallback. Hide closes only the panel, not the job; the original remains in Activity. Filters, page, selected IDs and Inspector stay in place. If a response is missing, check the original instead of starting again. Changing prepared options cancels the earlier unapproved request before a new estimate. An expired estimate needs a fresh review.

Data funds, saved payment methods and sending plans have separate controls in Billing. The dialog’s balance and auto-top-up state are observations; preparing a quote does not enable auto-top-up. The supplied environment uses Stripe TEST. Actual availability and costs come from the current service response.

Make your first API call

Start with a small read. Create a workspace key in Settings → API keys with contacts:read. Keep it in your server environment as STARTWAVE_API_KEY, then read active Lists in most-recently-updated order:

curl --fail-with-body 'https://api.startwave.io/v1/lists?limit=20&state=active&sort=updated_at&order=desc' \
  --header "Authorization: Bearer $STARTWAVE_API_KEY"

The response contains items and next_cursor. Follow the cursor with the same filters until it is null or absent, even if an intermediate page is empty. GET /v1/lists documents every parameter and the response model.

API keys belong on your server. The signed-in app uses its own browser-session contract. This page contains examples only and does not send requests.

Daily allocation and Rebalance

Daily allocation is a campaign’s outbound ceiling, not a reservation or sending promise. In API 259, 0 means no outbound sends; new drafts start unallocated. Save a positive allocation before reviewing Launch or Resume. Older zero-limit receipts retain their original meaning. Schedule change receipts identify that meaning with limit_semantics: uncapped_zero for an old uncapped original, or finite for the current limit. Recorded-window originals keep their original zero convention.

Campaigns, Dashboard campaign rows and campaign Sending/header use the same compact minus/integer/plus control. Each click changes one per day; Shift changes ten. Edits debounce for 500 milliseconds with one workspace batch in flight. Only confirmed available headroom supports an increase. An unsaved decrease may be below already spent quota and does not free headroom. Continued clicks remain local until the original settles and fresh bounds arrive. Copy and schedule drafts remain intact.

Rebalance reads a small preview before an explicit Apply. Inspect each date’s ready sends, preparing work and remaining shortfall, including tomorrow’s tradeoff. “Enables preparation” means ready coverage is unchanged and additional work could become ready after checks; it is not a ready-send or delivery promise. Expired or changed previews need a fresh review. These controls do not buy capacity, run a provider check or authorize a payment.

GET /capacity/limit supplies nullable allocation bounds and revisioned campaign rows. Its authorized_daily_capacity limit includes currently authorized sending capacity. When capacity_operation and capacity_valid_until are supplied together, the app can use that current operation in the existing launch review without requiring a new capacity purchase. Expired authority requires a fresh read; preparation and verification retain their own funding checks.

PATCH /campaigns/allocations accepts one operation ID, the exact configuration and changes with campaign/expected_revision/daily_limit. After a lost response, inspect GET /campaigns/allocations/{operation_id} using that same original. Its immutable receipt can settle even when current bounds are null; editing remains disabled until fresh bounds return. POST /campaigns/allocations/preview is a read-only computation.

When a response is lost

Keep the identity and intent of a purchase, launch, reply or verification attempt. If its response is lost, inspect the original result before trying again. Current state, an immutable receipt and ongoing job progress answer different questions.

Agent and Notification verification send an attempt ID with the code and recover using that attempt ID. Codes belong only in the code field; never save codes or their hashes for recovery. A verification receipt’s snapshot records that attempt’s outcome, not current destination authority. These verification routes require the browser session, not a workspace API key.

For public API writes, the reference explains original-operation recovery and documents the original-result GET endpoints. Support can help when the original result is still uncertain.

Current availability

Outgoing attachments, leaderboards, exact analytics drilldowns, new entitlement summaries, atomic List Move and calendar drag-to-reschedule remain deferred. Current workspace state and service terms determine which supported actions are available to you.