Developer API, CLI and MCP Server

Why this exists

Outreach checks are easy to need and slow to build well.

Most teams end up rebuilding the same small checks: is this address real, is this domain set up, will this email look like spam. Each one takes longer than it looks.

DNS checks have many edge cases

SPF, DKIM and DMARC each have their own record format, selectors and lookup rules. A quick script works on your domain and fails on the next one.

Agents scrape when they cannot call

An AI agent without a proper tool reads web pages and guesses. That is slow, breaks when a page changes and gives answers you cannot trust.

Account data is stuck in the app

When the only way to add contacts or read a campaign is the browser, every import, report and sync becomes a manual job for someone on the team.

Six ways in,split by whether you need an account.

The public surfaces answer deliverability and copy questions for anyone, with no key. The account surfaces act on your own FirstSales workspace: contacts, campaigns, deals and more.

Public, no key
Public REST API
Eighteen operations for email checks, DNS and domain lookups, copy scoring and tutorials, described by one OpenAPI 3.1 document.
Open /openapi.json
Public, no key
Public MCP server
Twelve of the same checks as MCP tools over Streamable HTTP, so an agent can call them directly instead of scraping pages.
Open the MCP manifest
Public, no key
Markdown for agents
A content map at /llms.txt and a clean Markdown copy of site pages for LLMs and crawlers that prefer text to HTML.
Open /llms.txt
Your account
Developer API
The authenticated API for your own workspace. It covers account workflows and is separate from the public diagnostics API on this site.
Read the Developer API docs
Your account
firstsales CLI
The npm package @firstsales.io/cli installs a binary called firstsales, so you can run account workflows from a terminal or a script.
Read the CLI reference
Your account
App MCP server
An OAuth-protected MCP server for in-app actions and account data, so an agent can work inside your FirstSales account with your permission.
Read the app MCP guide

Connect the public MCP server

Add this to Claude Desktop, Claude Code or any MCP client that speaks Streamable HTTP. The tools show up in your agent right away.

{
  "mcpServers": {
    "firstsales": {
      "url": "https://firstsales.io/mcp/"
    }
  }
}

From first call to your own account

Start with one public call, then connect your account when you need it.

You do not need an account to try the public API or MCP server. Sign in only when you want to act on your own workspace.

01
Read the spec
Open /openapi.json or /api/openapi.yaml and import it into your client generator, API explorer or agent framework. Every operation, field and limit is in it.
02
Make a public call
POST an email address to /api/v1/email/validate, or add the MCP server to your agent. No key, no sign-up. Read the RateLimit headers to pace yourself.
03
Connect your account
For contacts, campaigns and deals in your own workspace, use the Developer API, the firstsales CLI or the OAuth-protected app MCP server.

What you get

Clear contracts, so your code and your agents keep working.

The public API is built to be read by machines first: one spec, stable paths, honest limits and plain errors.

One spec for everything
A single OpenAPI 3.1 document describes every public operation, its request body, its response and its limit. Generate a client in the language you use.
MCP tools for agents
Twelve tools over Streamable HTTP, listed in a discovery manifest at /.well-known/mcp.json, so an agent finds and calls them without custom glue.
Versioned paths
Every endpoint lives under /api/v1. A breaking change ships under a new prefix, and v1 keeps its contract.
Limits you can see
Each response carries RateLimit headers with the limit, what is left and when the window resets, so your client can slow down before it is refused.
Plain errors
Over the limit, you get a 429 with Retry-After in seconds and a JSON body with error, message and hint fields that say what to do next.
Your account from code
The Developer API, the firstsales CLI and the app MCP server reach your own workspace, so imports, reports and syncs do not need a browser.

How a developer usesthe FirstSales API and MCP server

Four steps, from reading the spec to handling a limit. The examples use sample data.

Spec
Import the OpenAPI spec
Start from the machine-readable spec. It lists every public operation under /api/v1 with its method, request fields and response shape. Import it into your API explorer or client generator and you have typed calls in a minute.
- OpenAPI 3.1. JSON at /openapi.json, YAML at /api/openapi.yaml.
- Every schema. Request and response fields for each call.
- Limits in the spec. Each operation's limit under x-rateLimit.
openapi.jsonOpenAPI 3.1.0
FirstSales Public API
POST/api/v1/email/validate20/min
POST/api/v1/dns/validate10/min
POST/api/v1/domain/age10/min
POST/api/v1/analyze/subject-line30/min
GET/api/v1/public/tutorials
Request
Make your first call
Send a JSON body to the operation you need. Email validation returns 200 even when the address is bad, so read the valid field rather than the status code. The response also says whether the domain exists, has mail servers or is disposable.
- JSON in, JSON out. Plain POST bodies with one or two fields.
- No key. Public operations work without sign-up.
- Useful detail. MX records, free-provider and disposable flags.
curl -X POST \ https://firstsales.io/api/v1/email/validate \ -H "Content-Type: application/json" \ -d '{"email":"maya@brightloop.example"}'
200 OK
{ "valid": true, "domain": "brightloop.example", "domainExists": true, "hasMx": true, "isDisposable": false, "isFreeProvider": false }
MCP
Give your agent the same checks
Add the public MCP server to your agent with one line of config. Your agent can then validate an address, check a domain's DKIM or score a subject line as a tool call, and read a tutorial when it needs to explain a step.
- Streamable HTTP. One URL: https://firstsales.io/mcp/.
- Discovery manifest. Tools listed at /.well-known/mcp.json.
- Twelve tools. Email, DNS, domain, copy and tutorials.
Limits
Pace yourself with the headers
Every response tells you where you stand: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy. If you go over, the 429 response has a Retry-After header, so your client knows exactly how long to wait.
- Per-IP windows. Limits reset every 60 seconds.
- IETF header fields. Throttle before you are refused.
- Retry-After on 429. Wait time in seconds, plus a hint.
Response headers
RateLimit-Limit
20
RateLimit-Remaining
3
RateLimit-Reset
41
RateLimit-Policy
20;w=60
429 Too Many RequestsRetry-After: 41
{ "error": "...", "message": "...", "hint": "..." }

Endpoint reference

Every public operation, with its path and its limit.

All paths sit under https://firstsales.io/api/v1. Limits are per IP over a 60-second window. The OpenAPI spec has the request and response schema for each one.

Email checks
Operation	What it does	Limit
POST/api/v1/email/validate	Check that an address has a real domain, mail servers and a valid format.	20/min
POST/api/v1/email/disposable	Score an address's domain for disposable or temporary inbox risk.	20/min
POST/api/v1/email/catchall	Find out whether a domain accepts mail for any mailbox (catch-all).	20/min

DNS checks
Operation	What it does	Limit
POST/api/v1/dns/check	Run one DNS, email authentication or security check against a domain.	10/min
POST/api/v1/dns/dkim	Look up and check a domain's DKIM record for a selector.	10/min
POST/api/v1/dns/validate	Run SPF, DKIM, DMARC and MX checks together, with a confidence score.	10/min
POST/api/v1/dns/reverse	Reverse DNS (PTR) lookup for an IPv4 address, with a forward check.	10/min

Domain lookups
Operation	What it does	Limit
POST/api/v1/domain/age	Get a domain's registration age and expiry date through RDAP.	10/min
POST/api/v1/domain/dns-records	Fetch every DNS record type for a domain in one call.	10/min
POST/api/v1/domain/subdomains	Find subdomains through Certificate Transparency logs.	5/min

Copy scoring
Operation	What it does	Limit
POST/api/v1/analyze/spam	Score email content for spam-trigger risk.	30/min
POST/api/v1/analyze/subject-line	Score a cold email subject line and suggest a better one.	30/min
POST/api/v1/analyze/cold-email	Grade a full cold email draft across eight dimensions.	See spec
POST/api/v1/analyze/email-body	Score a cold email body and suggest improvements.	30/min
POST/api/v1/analyze/personalization	Find and score the personal details in a cold email.	See spec

Tutorials and health
Operation	What it does	Limit
GET/api/v1/public/tutorials	List every public FirstSales tutorial.	See spec
GET/api/v1/public/tutorials/{slug}	Get the full content of one tutorial by its slug.	See spec
GET/api/v1/health	Check that the service is up.	See spec

Versioning, deprecation and limits,written down so your code can rely on them.

These are the same rules the OpenAPI spec declares under x-apiVersioning, x-deprecationPolicy and x-rateLimit. The spec links straight to this section.

Versioning

The API is versioned in the URL path. The current version is v1, so every endpoint is reachable at https://firstsales.io/api/v1/<operation>.

A breaking change ships under a new prefix, and v1 keeps its contract. The unprefixed /api/<operation> form is an alias for the current version and may change without notice, so call the /api/v1/ form.

Deprecation policy

A version is supported for at least 180 days after its replacement is announced.

Once a version is deprecated, its responses carry Deprecation: true and a Sunset header with the retirement date (RFC 8594), plus a Link header pointing at the migration notes. Retirements are announced on this page. No version is deprecated today.

Rate limits

Every endpoint is rate limited per IP over a 60-second window: 20 a minute for email checks, 10 for DNS and domain lookups and 30 for copy scoring. Every response carries the IETF RateLimit header fields, so a client can throttle itself without waiting for a refusal.

RateLimit-Limit: Requests allowed in the current window
RateLimit-Remaining: Requests still available
RateLimit-Reset: Seconds until the window resets
RateLimit-Policy: The policy, as <limit>;w=60

Over the limit

The endpoint answers 429 with a Retry-After header in seconds and a JSON body carrying error, message and hint.

HTTP/1.1 429 Too Many Requests
Retry-After: 41
Content-Type: application/json

{ "error": "...", "message": "...", "hint": "..." }

Simple guide

How to build on the FirstSales API without surprises later.

Seven habits that keep integrations working when traffic grows and versions change.

01
Pick the right surface first
If you only need checks that do not touch an account, such as email validation, DNS checks or copy scoring, use the public API or public MCP server. If you need contacts, campaigns or deals in your own workspace, use the Developer API, the firstsales CLI or the app MCP server. Mixing them up is the most common first mistake.
02
Always call the /api/v1 form
The unprefixed /api/<operation> form is an alias for the current version and may change without notice. Call https://firstsales.io/api/v1/<operation> so your code keeps the v1 contract when a new version ships.
03
Generate your client from the spec
Hand-written clients drift. Generate one from /openapi.json and regenerate it when the spec changes. You get the right field names, the right types and the limit for each operation in one step.
04
Read the result, not just the status
Some checks answer 200 for a bad input because the check itself worked. Email validation is one: an invalid address still returns 200 with valid set to false. Branch on the fields in the body.
05
Throttle from the headers
Read RateLimit-Remaining and RateLimit-Reset on every response. Slow down when the remaining count gets low instead of waiting for a 429. Email checks allow 20 calls a minute, DNS and domain lookups 10, and copy scoring 30.
06
Handle 429 and back off
When you do hit the limit, wait for the number of seconds in Retry-After before you try again. The JSON body's hint field says what to change. Do not retry in a tight loop; it only keeps the window full.
07
Watch for deprecation headers
A version is supported for at least 180 days after its replacement is announced. Once a version is deprecated, responses carry Deprecation: true, a Sunset header with the retirement date and a Link header to the migration notes. No version is deprecated today.

Before and after

Outreach checks built by hand, and called from FirstSales

The same checks, done two ways.

Built by hand

Scripts you keep alive.

A script per checkSPF, DKIM, DMARC and MX each coded separately.
No shared contractFields change when the script changes.
Agents scrape pagesSlow, fragile and hard to trust.
Silent failuresErrors with no hint of what went wrong.
Guessing at limitsUpstream services refuse without warning.
Account work by handImports and reports done in the browser.

FirstSales API

One spec, one base URL.

Eighteen operationsEmail, DNS, domain, copy and tutorials.
OpenAPI 3.1 specGenerate a typed client from it.
MCP toolsAgents call checks directly.
Plain errorsError, message and hint in every refusal.
Visible limitsRateLimit headers on every response.
Account access from codeDeveloper API, CLI and app MCP server.

At a glance

Developer access: building it yourself vs FirstSales

What it takes to run outreach checks and account workflows from code, by hand and with FirstSales.

Building outreach checks yourself compared with the FirstSales API
What you get	Building it yourself	FirstSales
Email address checks	Your own MX lookups	Validate, disposable and catch-all calls
SPF, DKIM and DMARC	A parser per record type	One call or all together, with a score
Copy scoring	Word lists you maintain	Spam, subject line, body and full draft
Machine-readable contract	Whatever the code does	OpenAPI 3.1 in JSON and YAML
Agent access	Page scraping	Public MCP server with twelve tools
Rate limits	Found out the hard way	Per IP, shown in headers
Versioning	None	/api/v1 with a 180-day deprecation window
Your account from code	The browser	Developer API, CLI and app MCP server
		Start your $1 trial

Before you ship

Ten checks for a FirstSales integration

Run through these before your integration goes live.

You picked the public or the account surface on purpose
Every call uses the /api/v1 path
Your client is generated from the current spec
Results are read from the body, not only the status
RateLimit headers are logged and respected
429 responses wait for Retry-After
Errors log the hint field
Deprecation and Sunset headers raise an alert
Agents use the MCP server, not page scraping
Account keys and tokens stay out of your code

What people say

From people who use it

Real words from real users. No paid reviews.

“User Interface, Ease of Use, Able to hit the inbox in the first attempt.”

Sadashiv B.

Founder, small business

G2

“One of the biggest pains in cold email is making sure that you have your DNS setup correctly. Firstsales has created a system to make sure you have done this correctly.”

Mike O

Trustpilot review

Trustpilot

“I have always struggled in cold outreach. However, Firstsales has provided an excellent tool for cold outreach.”

Kaushal S.

Founder, small business

G2

Read all reviews

Questions,answered plainly.

Can’t find yours? Write to us.

01Do I need an API key for the FirstSales API?

Not for the public API or the public MCP server. They cover email checks, DNS and domain lookups, copy scoring and tutorials. You need your own account only for the Developer API, the firstsales CLI and the app MCP server.

02Where is the OpenAPI spec?

The public spec is OpenAPI 3.1, at /openapi.json in JSON and /api/openapi.yaml in YAML. The authenticated Developer API has its own spec on developer.firstsales.io.

03How do I connect the MCP server to Claude?

Add a server called firstsales with the URL https://firstsales.io/mcp/ to your MCP client config. It uses Streamable HTTP, and the tools are listed in the manifest at /.well-known/mcp.json.

04What are the rate limits?

Limits are per IP over a 60-second window: 20 calls a minute for email checks, 10 for DNS and domain lookups and 30 for copy scoring. The exact limit for each operation is in the spec under x-rateLimit, and every response carries RateLimit headers.

05What happens when I go over the limit?

The endpoint answers 429 with a Retry-After header in seconds and a JSON body with error, message and hint fields. Wait for Retry-After before you call again.

06How is the API versioned?

The version is in the path. The current version is v1, so call https://firstsales.io/api/v1/<operation>. A breaking change ships under a new prefix, and a version is supported for at least 180 days after its replacement is announced.

07How do I install the FirstSales CLI?

Install the npm package @firstsales.io/cli. It adds a binary called firstsales. The CLI reference on developer.firstsales.io lists every command.

08Can I try FirstSales before I build on it?

Yes. The public API works without an account. To try the app and your own account surfaces, start a trial for $1 for 3 days. Plans start at $29/mo with unlimited mailboxes and workspaces.

Outreach that keeps going after you log off.Leads, emails, follow-ups and replies, handled.

Connect unlimited mailboxes and let AI agents find leads, write each email and follow up. Or send your own templates in manual mode. From $29/mo.

Start your $1 trial See pricing

$1 for 3 days · Cancel anytime · No contract

The FirstSales Developer API, CLI and MCP server, for people and agents who build.

Outreach checks are easy to need and slow to build well.

DNS checks have many edge cases

Agents scrape when they cannot call

Account data is stuck in the app

Six ways in,split by whether you need an account.

Public REST API

Public MCP server

Markdown for agents

Developer API

firstsales CLI

App MCP server

Connect the public MCP server

Start with one public call, then connect your account when you need it.

Read the spec

Make a public call

Connect your account

Clear contracts, so your code and your agents keep working.

One spec for everything

MCP tools for agents

Versioned paths

Limits you can see

Plain errors

Your account from code

How a developer usesthe FirstSales API and MCP server

Import the OpenAPI spec

Make your first call

Give your agent the same checks

Pace yourself with the headers

Every public operation, with its path and its limit.

Versioning, deprecation and limits,written down so your code can rely on them.

Versioning

Deprecation policy

Rate limits

Over the limit

How to build on the FirstSales API without surprises later.

Pick the right surface first

Always call the /api/v1 form

Generate your client from the spec

Read the result, not just the status

Throttle from the headers

Handle 429 and back off

Watch for deprecation headers