Run FirstSales from the command line
A headless API and command line tool cover the same operations as the app, so you can script campaign setup, lead imports and reporting into your own tooling.
Run FirstSales from the command line
There is now a documented API and a command line tool covering the operations the app covers. Campaign setup, lead imports, reporting, and connector management can all run from a script.
What changed
Automating anything used to mean doing it by hand or not doing it. If you ran the same campaign structure every month, you built it in the interface every month. If you wanted your reply numbers in your own reporting, you exported a file and moved it yourself.
The API covers the operations the product performs, with a stable contract and published documentation. The command line tool sits on top of it for the things you would rather do in a terminal than in code.
Both use the same permission model as the interface. A token is scoped to a workspace and carries the permissions of the account that created it, so there is no path to doing something through the API that the same person could not do through the app.
How to use it
Create a token in workspace settings. Scope it to the workspace you intend to work in and store it the way you would store any other credential. It is shown once.
Install the command line tool and authenticate with the token. From there, listing campaigns, checking status, importing contacts, and pulling reports are each one command. Output comes back in a form you can pipe into other tools.
For anything beyond that, use the API directly. The documentation covers the available operations, the shape of each request, and what comes back.
Start read only. Listing campaigns and pulling a report cannot damage anything, and they are enough to confirm your token works and you are pointed at the workspace you expect. Move to operations that change things once that is confirmed.
Why it matters
Repeated manual work is where mistakes live. Building the same campaign by hand every month means every month is an opportunity to mistype a subject line, pick the wrong list, or forget a step that was in the last one.
A script does not forget. It also serves as a written record of how the campaign is actually configured, which is more reliable than anyone's memory of what they clicked.
The reporting side matters for a different reason. Most teams have a place where their numbers live, and it is rarely inside any one tool. Being able to pull campaign performance into that place means outreach numbers sit next to everything else, rather than being the one set of figures somebody checks separately.
What it covers
Campaigns: create, configure, launch, pause, and read status.
Contacts and lists: import, read, update, and manage list membership.
Reporting: performance figures, send and reply counts, and campaign level detail.
Connectors: read status and check health. Adding a mailbox still requires the interface, because it involves an authentication flow with your mail provider that has to happen in a browser.
Tokens and safety
A token is a credential with the permissions of whoever made it. Treat it accordingly. Do not commit it to a repository, do not paste it into a shared document, and do not put it in a script that others can read.
Scope narrowly. If a script only needs to read reports, create the token from an account that only has read access rather than from an owner account.
Rotate tokens when someone leaves or when one has been in place a long time. Revoking a token in workspace settings takes effect immediately.
Rate limits
Requests are rate limited per workspace, at a level generous enough for ordinary automation and low enough to prevent a runaway script from affecting the workspace.
If you are importing a large list, use the bulk import operation rather than sending contacts one at a time. It is faster, it counts as one request, and it gives you a single result to check rather than several thousand.
A rate limit response tells you how long to wait. Honour it rather than retrying immediately, since retrying into a limit extends how long you stay limited.
A reasonable first script
Start with reporting, because it is read only and the output is immediately useful. A short script that pulls last week's campaign figures and writes them somewhere your team already looks will pay for itself faster than anything else you could automate.
From there, list imports are usually next. If leads arrive from a source outside FirstSales, importing them on a schedule removes a recurring manual step and a recurring chance to import the wrong file.
Campaign creation is worth automating last. It has the most steps, the most decisions, and the most that can go wrong quietly, so it benefits from you already being familiar with how the API behaves.
Errors and what to do about them
Every failed request comes back with a reason rather than a bare failure code. A rejected import tells you which rows failed and why, so you can fix those rows instead of re-uploading the whole file blind.
Treat a five hundred response as temporary and retry it with a delay. Treat a four hundred response as a problem with the request, and read the message rather than retrying, because the same request will fail the same way.
Log what your scripts do. When something imports the wrong list at two in the morning, the log is the only way to work out what happened.
Availability
The API and command line tool are available on all plans. Tokens are created per workspace from workspace settings, and any operation available in the interface to your account is available through them.