FirstSales API & Developer Resources

Developer API and CLI

The authenticated Developer API covers account-scoped product workflows and is separate from this site's public diagnostics API.

• Developer platform introduction
• Canonical Developer API OpenAPI JSON
• FirstSales CLI reference — npm package @firstsales.io/cli, binary firstsales
• OAuth-protected product MCP guide

OpenAPI spec

The full REST surface is described by a machine-readable OpenAPI 3.1 document, so any client generator, agent framework, or API explorer can import it directly.

• /openapi.json — OpenAPI 3.1 spec, JSON
• /api/openapi.yaml — the same spec, YAML

MCP server

FirstSales runs a Model Context Protocol (MCP) server over Streamable HTTP, so any MCP client — Claude Desktop, Claude Code, or your own agent — can call these tools directly without scraping the site.

• /mcp/ — the Streamable HTTP MCP endpoint
• /.well-known/mcp.json — discovery manifest

Client configuration

Add this to your Claude Desktop (or any Streamable HTTP-compatible) MCP client config:

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

REST endpoints

The same capabilities exposed as MCP tools are also available as plain REST endpoints under /api/v1:

• validate_email

  Validate an email's format, MX records, and domain existence.

• check_disposable_email

  Check whether an email uses a disposable/temporary domain.

• check_catchall_domain

  Detect whether a domain's mailbox is configured as catch-all.

• check_domain_dns

  Run an SPF, DKIM, DMARC, MX, blacklist, or other DNS/deliverability check.

• check_dkim

  Look up and validate a domain's DKIM record(s).

• get_domain_age

  Get a domain's registration date and age via RDAP/WHOIS.

• get_dns_records

  Fetch a domain's A, AAAA, MX, NS, TXT, CNAME, and SOA records.

• analyze_spam_score

  Score email body content for spam-trigger words and patterns.

• analyze_subject_line

  Analyze a subject line for spam risk and open-rate best practices.

• analyze_cold_email

  Analyze cold outreach copy for personalization, length, and CTA clarity.

• list_tutorials

  List all public FirstSales tutorials.

• get_tutorial

  Get the full content of one tutorial by slug.

Versioning and deprecation policy

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; 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 currently deprecated.

Rate limits

Every endpoint is rate limited per IP over a 60-second window. Limits are 20/min for the email checks, 10/min for the DNS and domain lookups, and 30/min for the content analysers; each operation's exact limit is in the OpenAPI spec under x-rateLimit.

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.

Markdown for agents

Every page on firstsales.io has a clean Markdown mirror for LLMs and crawlers that prefer structured text over HTML.

• /llms.txt — full content map
• /raw/*.md — Markdown mirror of any page, e.g. /raw/why.md

Product documentation

For the Developer API, CLI, and agent workflows, see developer.firstsales.io.