API para desenvolvedores, CLI e servidor MCP

Por que isto existe

Checagens de prospecção são fáceis de precisar e demoradas de construir bem.

A maioria dos times acaba refazendo as mesmas checagens pequenas: esse endereço é real, esse domínio está configurado, esse email vai parecer spam. Cada uma leva mais tempo do que parece.

Checagens de DNS têm muitos casos especiais

SPF, DKIM e DMARC têm cada um seu formato de registro, seus seletores e suas regras de consulta. Um script rápido funciona no seu domínio e falha no próximo.

Agentes leem páginas quando não podem chamar

Um agente de IA sem a ferramenta certa lê páginas da web e chuta. É lento, quebra quando a página muda e dá respostas em que você não pode confiar.

Os dados da conta ficam presos no app

Quando o único jeito de adicionar contatos ou ler uma campanha é o navegador, cada importação, relatório e sincronização vira trabalho manual para alguém do time.

Seis formas de entrar,separadas por precisar ou não de uma conta.

As superfícies públicas respondem perguntas de entregabilidade e de texto para qualquer pessoa, sem chave. As superfícies de conta agem no seu próprio workspace do FirstSales: contatos, campanhas, deals e mais.

Público, sem chave
API REST pública
Dezoito operações para checar emails, consultar DNS e domínios, avaliar textos e ler tutoriais, descritas em um único documento OpenAPI 3.1.
Abrir /openapi.json
Público, sem chave
Servidor MCP público
Doze dessas mesmas checagens como ferramentas MCP sobre Streamable HTTP, para um agente chamá-las direto em vez de ler páginas.
Abrir o manifesto MCP
Público, sem chave
Markdown para agentes
Um mapa de conteúdo em /llms.txt e uma cópia limpa em Markdown das páginas do site para LLMs e crawlers que preferem texto a HTML.
Abrir /llms.txt
Sua conta
Developer API
A API autenticada para o seu próprio workspace. Ela cobre fluxos da conta e é separada da API pública de diagnóstico deste site.
Ler a documentação da Developer API
Sua conta
CLI firstsales
O pacote npm @firstsales.io/cli instala um binário chamado firstsales, para você rodar fluxos da conta a partir de um terminal ou script.
Ler a referência do CLI
Sua conta
Servidor MCP do app
Um servidor MCP protegido por OAuth para ações dentro do app e dados da conta, para um agente trabalhar na sua conta do FirstSales com a sua permissão.
Ler o guia do MCP do app

Conecte o servidor MCP público

Adicione isto ao Claude Desktop, ao Claude Code ou a qualquer cliente MCP que use Streamable HTTP. As ferramentas aparecem no seu agente na hora.

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

Da primeira chamada à sua própria conta

Comece com uma chamada pública, e conecte sua conta quando precisar.

Você não precisa de conta para testar a API pública ou o servidor MCP. Entre só quando quiser agir no seu próprio workspace.

01
Leia a spec
Abra /openapi.json ou /api/openapi.yaml e importe no seu gerador de clientes, explorador de APIs ou framework de agentes. Cada operação, campo e limite está nela.
02
Faça uma chamada pública
Envie um endereço de email via POST para /api/v1/email/validate, ou adicione o servidor MCP ao seu agente. Sem chave, sem cadastro. Leia os headers RateLimit para controlar o ritmo.
03
Conecte sua conta
Para contatos, campanhas e deals do seu próprio workspace, use a Developer API, o CLI firstsales ou o servidor MCP do app protegido por OAuth.

O que você recebe

Contratos claros, para o seu código e seus agentes continuarem funcionando.

A API pública foi feita para ser lida primeiro por máquinas: uma spec, caminhos estáveis, limites honestos e erros claros.

Uma spec para tudo
Um único documento OpenAPI 3.1 descreve cada operação pública, seu corpo de requisição, sua resposta e seu limite. Gere um cliente na linguagem que você usa.
Ferramentas MCP para agentes
Doze ferramentas sobre Streamable HTTP, listadas em um manifesto em /.well-known/mcp.json, para um agente encontrá-las e chamá-las sem código extra.
Caminhos com versão
Cada endpoint fica sob /api/v1. Uma mudança incompatível sai com um prefixo novo, e a v1 mantém seu contrato.
Limites que você vê
Cada resposta traz headers RateLimit com o limite, o que sobra e quando a janela reinicia, para o seu cliente desacelerar antes de ser recusado.
Erros claros
Acima do limite, você recebe um 429 com Retry-After em segundos e um corpo JSON com os campos error, message e hint que dizem o que fazer a seguir.
Sua conta pelo código
A Developer API, o CLI firstsales e o servidor MCP do app chegam ao seu próprio workspace, então importações, relatórios e sincronizações não precisam de navegador.

Como um desenvolvedor usaa API e o servidor MCP do FirstSales

Quatro passos, de ler a spec a lidar com um limite. Os exemplos usam dados de amostra.

Spec
Importe a spec OpenAPI
Comece pela spec legível por máquina. Ela lista cada operação pública sob /api/v1 com método, campos de requisição e formato da resposta. Importe no seu explorador de APIs ou gerador de clientes e você terá chamadas tipadas em um minuto.
- OpenAPI 3.1. JSON em /openapi.json, YAML em /api/openapi.yaml.
- Cada schema. Campos de requisição e resposta de cada chamada.
- Limites na spec. O limite de cada operação em 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
Requisição
Faça sua primeira chamada
Envie um corpo JSON para a operação de que você precisa. A validação de email devolve 200 mesmo quando o endereço é ruim, então leia o campo valid em vez do código de status. A resposta também diz se o domínio existe, se tem servidores de email ou se é descartável.
- JSON de ida e volta. Corpos POST simples com um ou dois campos.
- Sem chave. Operações públicas funcionam sem cadastro.
- Detalhes úteis. Registros MX, indicadores de provedor grátis e descartável.
curl -X POST \ https://firstsales.io/api/v1/email/validate \ -H "Content-Type: application/json" \ -d '{"email":"[email protected]"}'
200 OK
{ "valid": true, "domain": "brightloop.example", "domainExists": true, "hasMx": true, "isDisposable": false, "isFreeProvider": false }
MCP
Dê ao seu agente as mesmas checagens
Adicione o servidor MCP público ao seu agente com uma linha de configuração. Assim ele pode validar um endereço, conferir o DKIM de um domínio ou avaliar um assunto como chamada de ferramenta, e ler um tutorial quando precisar explicar um passo.
- Streamable HTTP. Uma URL: https://firstsales.io/mcp/.
- Manifesto de descoberta. Ferramentas listadas em /.well-known/mcp.json.
- Doze ferramentas. Email, DNS, domínio, textos e tutoriais.
Limites
Controle o ritmo pelos headers
Cada resposta diz onde você está: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset e RateLimit-Policy. Se passar do limite, a resposta 429 traz um header Retry-After, então seu cliente sabe exatamente quanto esperar.
- Janelas por IP. Os limites reiniciam a cada 60 segundos.
- Headers do IETF. Desacelere antes de ser recusado.
- Retry-After no 429. Tempo de espera em segundos, mais uma dica.
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": "..." }

Referência de endpoints

Cada operação pública, com seu caminho e seu limite.

Todos os caminhos ficam sob https://firstsales.io/api/v1. Os limites são por IP em uma janela de 60 segundos. A spec OpenAPI traz o schema de requisição e resposta de cada uma.

Checagem de emails
Operação	O que faz	Limite
POST/api/v1/email/validate	Confere se um endereço tem um domínio real, servidores de email e formato válido.	20/min
POST/api/v1/email/disposable	Avalia o domínio de um endereço quanto ao risco de caixa descartável ou temporária.	20/min
POST/api/v1/email/catchall	Descobre se um domínio aceita email para qualquer caixa (catch-all).	20/min

Checagens de DNS
Operação	O que faz	Limite
POST/api/v1/dns/check	Roda uma checagem de DNS, autenticação de email ou segurança em um domínio.	10/min
POST/api/v1/dns/dkim	Busca e confere o registro DKIM de um domínio para um seletor.	10/min
POST/api/v1/dns/validate	Roda SPF, DKIM, DMARC e MX juntos, com uma nota de confiança.	10/min
POST/api/v1/dns/reverse	Consulta de DNS reverso (PTR) para um endereço IPv4, com confirmação direta.	10/min

Consultas de domínio
Operação	O que faz	Limite
POST/api/v1/domain/age	Mostra a idade de registro e a data de vencimento de um domínio via RDAP.	10/min
POST/api/v1/domain/dns-records	Traz todos os tipos de registro DNS de um domínio em uma chamada.	10/min
POST/api/v1/domain/subdomains	Encontra subdomínios pelos logs de Certificate Transparency.	5/min

Avaliação de textos
Operação	O que faz	Limite
POST/api/v1/analyze/spam	Avalia o conteúdo de um email quanto ao risco de palavras de spam.	30/min
POST/api/v1/analyze/subject-line	Avalia um assunto de cold email e sugere um melhor.	30/min
POST/api/v1/analyze/cold-email	Dá nota a um rascunho completo de cold email em oito dimensões.	Ver spec
POST/api/v1/analyze/email-body	Avalia o corpo de um cold email e sugere melhorias.	30/min
POST/api/v1/analyze/personalization	Encontra e avalia os detalhes pessoais de um cold email.	Ver spec

Tutoriais e status
Operação	O que faz	Limite
GET/api/v1/public/tutorials	Lista todos os tutoriais públicos do FirstSales.	Ver spec
GET/api/v1/public/tutorials/{slug}	Traz o conteúdo completo de um tutorial pelo slug.	Ver spec
GET/api/v1/health	Confere se o serviço está no ar.	Ver spec

Versões, descontinuação e limites,por escrito para o seu código poder confiar.

São as mesmas regras que a spec OpenAPI declara em x-apiVersioning, x-deprecationPolicy e x-rateLimit. A spec aponta direto para esta seção.

Versões

A API tem a versão no caminho da URL. A versão atual é v1, então cada endpoint fica em https://firstsales.io/api/v1/<operation>.

Uma mudança incompatível sai com um prefixo novo, e a v1 mantém seu contrato. A forma sem prefixo /api/<operation> é um alias da versão atual e pode mudar sem aviso, então chame a forma /api/v1/.

Política de descontinuação

Uma versão tem suporte por pelo menos 180 dias depois do anúncio da sua substituta.

Quando uma versão é descontinuada, as respostas trazem Deprecation: true e um header Sunset com a data de desligamento (RFC 8594), além de um header Link para as notas de migração. Os desligamentos são anunciados nesta página. Nenhuma versão está descontinuada hoje.

Limites de uso

Cada endpoint tem limite por IP em uma janela de 60 segundos: 20 por minuto para checar emails, 10 para consultas de DNS e domínio e 30 para avaliar textos. Cada resposta traz os campos de header RateLimit do IETF, para um cliente se controlar sem esperar uma recusa.

RateLimit-Limit: Requisições permitidas na janela atual
RateLimit-Remaining: Requisições ainda disponíveis
RateLimit-Reset: Segundos até a janela reiniciar
RateLimit-Policy: A política, no formato <limit>;w=60

Acima do limite

O endpoint responde 429 com um header Retry-After em segundos e um corpo JSON com error, message e hint.

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

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

Guia simples

Como construir sobre a API do FirstSales sem surpresas depois.

Sete hábitos que mantêm as integrações funcionando quando o tráfego cresce e as versões mudam.

01
Escolha primeiro a superfície certa
Se você só precisa de checagens que não mexem em uma conta, como validar emails, checar DNS ou avaliar textos, use a API pública ou o servidor MCP público. Se precisa de contatos, campanhas ou deals do seu próprio workspace, use a Developer API, o CLI firstsales ou o servidor MCP do app. Confundir as duas é o erro inicial mais comum.
02
Chame sempre a forma /api/v1
A forma sem prefixo /api/<operation> é um alias da versão atual e pode mudar sem aviso. Chame https://firstsales.io/api/v1/<operation> para o seu código manter o contrato v1 quando sair uma versão nova.
03
Gere seu cliente a partir da spec
Clientes escritos à mão ficam desatualizados. Gere um a partir de /openapi.json e gere de novo quando a spec mudar. Você recebe os nomes de campo certos, os tipos certos e o limite de cada operação de uma vez.
04
Leia o resultado, não só o status
Algumas checagens respondem 200 para uma entrada ruim porque a checagem em si funcionou. A validação de email é uma delas: um endereço inválido volta 200 com valid igual a false. Decida pelos campos do corpo.
05
Controle o ritmo pelos headers
Leia RateLimit-Remaining e RateLimit-Reset em toda resposta. Desacelere quando sobrar pouco em vez de esperar um 429. A checagem de emails permite 20 chamadas por minuto, as consultas de DNS e domínio 10 e a avaliação de textos 30.
06
Trate o 429 e espere
Quando bater no limite, espere os segundos de Retry-After antes de tentar de novo. O campo hint do corpo JSON diz o que mudar. Não tente de novo em um loop apertado; isso só mantém a janela cheia.
07
Fique de olho nos headers de descontinuação
Uma versão tem suporte por pelo menos 180 dias depois do anúncio da sua substituta. Quando uma versão é descontinuada, as respostas trazem Deprecation: true, um header Sunset com a data de desligamento e um header Link para as notas de migração. Nenhuma versão está descontinuada hoje.

Antes e depois

Checagens de prospecção feitas à mão, e chamadas pelo FirstSales

As mesmas checagens, de dois jeitos.

Feito à mão

Scripts que você precisa manter.

Um script por checagemSPF, DKIM, DMARC e MX programados separados.
Sem contrato comumOs campos mudam quando o script muda.
Agentes leem páginasLento, frágil e difícil de confiar.
Falhas silenciosasErros sem pista do que deu errado.
Limites no escuroServiços recusam sem avisar.
Trabalho de conta à mãoImportações e relatórios no navegador.

API do FirstSales

Uma spec, uma URL base.

Dezoito operaçõesEmail, DNS, domínio, textos e tutoriais.
Spec OpenAPI 3.1Gere um cliente tipado a partir dela.
Ferramentas MCPAgentes chamam as checagens direto.
Erros clarosError, message e hint em toda recusa.
Limites visíveisHeaders RateLimit em toda resposta.
Conta pelo códigoDeveloper API, CLI e servidor MCP do app.

Em resumo

Acesso para desenvolvedores: construir sozinho ou usar o FirstSales

O que é preciso para rodar checagens de prospecção e fluxos de conta pelo código, à mão e com o FirstSales.

Construir checagens de prospecção sozinho comparado à API do FirstSales
O que você recebe	Construir sozinho	FirstSales
Checagem de endereços	Suas próprias consultas MX	Chamadas de validação, descartável e catch-all
SPF, DKIM e DMARC	Um parser por tipo de registro	Uma chamada ou todas juntas, com nota
Avaliação de textos	Listas de palavras que você mantém	Spam, assunto, corpo e rascunho completo
Contrato legível por máquina	O que o código fizer	OpenAPI 3.1 em JSON e YAML
Acesso para agentes	Ler páginas	Servidor MCP público com doze ferramentas
Limites de uso	Descobertos do jeito difícil	Por IP, mostrados nos headers
Versões	Nenhuma	/api/v1 com 180 dias de aviso de descontinuação
Sua conta pelo código	O navegador	Developer API, CLI e servidor MCP do app
		Comece seu teste de $1

Antes de publicar

Dez checagens para uma integração com o FirstSales

Passe por elas antes de a sua integração entrar no ar.

Você escolheu a superfície pública ou a de conta de propósito
Cada chamada usa o caminho /api/v1
Seu cliente é gerado a partir da spec atual
Os resultados são lidos do corpo, não só do status
Os headers RateLimit são registrados e respeitados
Respostas 429 esperam o Retry-After
Os erros registram o campo hint
Headers Deprecation e Sunset disparam um alerta
Agentes usam o servidor MCP, não leem páginas
Chaves e tokens da conta ficam fora do seu código

O que as pessoas dizem

De pessoas que usam

Palavras reais de usuários reais, no idioma original. Sem avaliações pagas.

“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

Ler todas as avaliações

Perguntas,respondidas com clareza.

Não achou a sua? Escreva para nós.

01Preciso de uma chave para a API do FirstSales?

Não para a API pública nem para o servidor MCP público. Eles cobrem checagem de emails, consultas de DNS e domínio, avaliação de textos e tutoriais. Você só precisa da sua própria conta para a Developer API, o CLI firstsales e o servidor MCP do app.

02Onde fica a spec OpenAPI?

A spec pública é OpenAPI 3.1, em /openapi.json em JSON e em /api/openapi.yaml em YAML. A Developer API autenticada tem sua própria spec em developer.firstsales.io.

03Como conecto o servidor MCP ao Claude?

Adicione um servidor chamado firstsales com a URL https://firstsales.io/mcp/ na configuração do seu cliente MCP. Ele usa Streamable HTTP, e as ferramentas estão listadas no manifesto em /.well-known/mcp.json.

04Quais são os limites de uso?

Os limites são por IP em uma janela de 60 segundos: 20 chamadas por minuto para checar emails, 10 para consultas de DNS e domínio e 30 para avaliar textos. O limite exato de cada operação está na spec em x-rateLimit, e toda resposta traz headers RateLimit.

05O que acontece se eu passar do limite?

O endpoint responde 429 com um header Retry-After em segundos e um corpo JSON com os campos error, message e hint. Espere o tempo de Retry-After antes de chamar de novo.

06Como a API é versionada?

A versão fica no caminho. A versão atual é v1, então chame https://firstsales.io/api/v1/<operation>. Uma mudança incompatível sai com um prefixo novo, e uma versão tem suporte por pelo menos 180 dias depois do anúncio da sua substituta.

07Como instalo o CLI do FirstSales?

Instale o pacote npm @firstsales.io/cli. Ele adiciona um binário chamado firstsales. A referência do CLI em developer.firstsales.io lista cada comando.

08Posso testar o FirstSales antes de construir sobre ele?

Sim. A API pública funciona sem conta. Para testar o app e as superfícies da sua conta, comece um teste por $1 por 3 dias. Os planos começam em $29/mês com caixas e workspaces ilimitados.

Prospecção que continua quando você desconecta.Leads, emails, follow-ups e respostas, resolvidos.

Conecte caixas ilimitadas e deixe os agentes de IA encontrarem leads, escreverem cada email e fazerem follow-up. Ou envie seus próprios modelos no modo manual. A partir de $29/mês.

Comece seu teste de $1 Ver preços

$1 por 3 dias · Cancele quando quiser · Sem contrato

A API para desenvolvedores, o CLI e o servidor MCP do FirstSales, para pessoas e agentes que constroem.

Checagens de prospecção são fáceis de precisar e demoradas de construir bem.

Checagens de DNS têm muitos casos especiais

Agentes leem páginas quando não podem chamar

Os dados da conta ficam presos no app

Seis formas de entrar,separadas por precisar ou não de uma conta.

API REST pública

Servidor MCP público

Markdown para agentes

Developer API

CLI firstsales

Servidor MCP do app

Conecte o servidor MCP público

Comece com uma chamada pública, e conecte sua conta quando precisar.

Leia a spec

Faça uma chamada pública

Conecte sua conta

Contratos claros, para o seu código e seus agentes continuarem funcionando.

Uma spec para tudo

Ferramentas MCP para agentes

Caminhos com versão

Limites que você vê

Erros claros

Sua conta pelo código

Como um desenvolvedor usaa API e o servidor MCP do FirstSales

Importe a spec OpenAPI

Faça sua primeira chamada

Dê ao seu agente as mesmas checagens

Controle o ritmo pelos headers

Cada operação pública, com seu caminho e seu limite.

Versões, descontinuação e limites,por escrito para o seu código poder confiar.

Versões

Política de descontinuação

Limites de uso

Acima do limite

Como construir sobre a API do FirstSales sem surpresas depois.

Escolha primeiro a superfície certa

Chame sempre a forma /api/v1

Gere seu cliente a partir da spec

Leia o resultado, não só o status