API para desarrolladores, CLI y servidor MCP

Por qué existe

Las revisiones de outreach se necesitan rápido y se construyen bien despacio.

La mayoría de los equipos termina rehaciendo las mismas revisiones pequeñas: si la dirección es real, si el dominio está configurado, si este email va a parecer spam. Cada una lleva más tiempo de lo que parece.

Las revisiones de DNS tienen muchos casos raros

SPF, DKIM y DMARC tienen cada uno su formato de registro, sus selectores y sus reglas de búsqueda. Un script rápido funciona con tu dominio y falla con el siguiente.

Los agentes leen páginas cuando no pueden llamar

Un agente de IA sin una herramienta adecuada lee páginas web y adivina. Es lento, se rompe cuando cambia una página y da respuestas en las que no puedes confiar.

Los datos de la cuenta se quedan en la app

Si la única forma de añadir contactos o leer una campaña es el navegador, cada importación, informe y sincronización se vuelve trabajo manual para alguien del equipo.

Seis formas de entrar,separadas según necesites una cuenta o no.

Las superficies públicas responden preguntas de entregabilidad y de copy para cualquiera, sin clave. Las superficies de cuenta actúan sobre tu propio espacio de trabajo en FirstSales: contactos, campañas, deals y más.

Público, sin clave
API REST pública
Dieciocho operaciones para revisar emails, consultar DNS y dominios, puntuar copy y leer tutoriales, descritas en un solo documento OpenAPI 3.1.
Abrir /openapi.json
Público, sin clave
Servidor MCP público
Doce de las mismas revisiones como herramientas MCP sobre Streamable HTTP, para que un agente las llame directamente en lugar de leer páginas.
Abrir el manifiesto MCP
Público, sin clave
Markdown para agentes
Un mapa de contenido en /llms.txt y una copia limpia en Markdown de las páginas del sitio para LLMs y crawlers que prefieren texto a HTML.
Abrir /llms.txt
Tu cuenta
Developer API
La API autenticada para tu propio espacio de trabajo. Cubre flujos de cuenta y es distinta de la API pública de diagnóstico de este sitio.
Leer la documentación de la Developer API
Tu cuenta
CLI firstsales
El paquete npm @firstsales.io/cli instala un binario llamado firstsales, para que ejecutes flujos de cuenta desde una terminal o un script.
Leer la referencia del CLI
Tu cuenta
Servidor MCP de la app
Un servidor MCP protegido con OAuth para acciones dentro de la app y datos de la cuenta, para que un agente trabaje en tu cuenta de FirstSales con tu permiso.
Leer la guía del MCP de la app

Conecta el servidor MCP público

Añade esto a Claude Desktop, Claude Code o cualquier cliente MCP que hable Streamable HTTP. Las herramientas aparecen en tu agente al momento.

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

De la primera llamada a tu propia cuenta

Empieza con una llamada pública, y conecta tu cuenta cuando la necesites.

No necesitas una cuenta para probar la API pública o el servidor MCP. Inicia sesión solo cuando quieras actuar sobre tu propio espacio de trabajo.

01
Lee la spec
Abre /openapi.json o /api/openapi.yaml e impórtala en tu generador de clientes, explorador de APIs o framework de agentes. Cada operación, campo y límite está ahí.
02
Haz una llamada pública
Envía una dirección de email por POST a /api/v1/email/validate, o añade el servidor MCP a tu agente. Sin clave, sin registro. Lee los headers RateLimit para medir tu ritmo.
03
Conecta tu cuenta
Para contactos, campañas y deals de tu propio espacio de trabajo, usa la Developer API, el CLI firstsales o el servidor MCP de la app protegido con OAuth.

Qué obtienes

Contratos claros, para que tu código y tus agentes sigan funcionando.

La API pública está hecha para que la lean primero las máquinas: una spec, rutas estables, límites honestos y errores claros.

Una spec para todo
Un solo documento OpenAPI 3.1 describe cada operación pública, su cuerpo de petición, su respuesta y su límite. Genera un cliente en el lenguaje que uses.
Herramientas MCP para agentes
Doce herramientas sobre Streamable HTTP, listadas en un manifiesto en /.well-known/mcp.json, para que un agente las encuentre y las llame sin código extra.
Rutas con versión
Cada endpoint vive bajo /api/v1. Un cambio incompatible sale con un prefijo nuevo, y v1 mantiene su contrato.
Límites que puedes ver
Cada respuesta lleva headers RateLimit con el límite, lo que queda y cuándo se reinicia la ventana, para que tu cliente frene antes de que lo rechacen.
Errores claros
Si pasas el límite, recibes un 429 con Retry-After en segundos y un cuerpo JSON con los campos error, message y hint que dicen qué hacer después.
Tu cuenta desde código
La Developer API, el CLI firstsales y el servidor MCP de la app llegan a tu propio espacio de trabajo, así importaciones, informes y sincronizaciones no necesitan navegador.

Cómo usa un desarrolladorla API y el servidor MCP de FirstSales

Cuatro pasos, desde leer la spec hasta manejar un límite. Los ejemplos usan datos de muestra.

Spec
Importa la spec OpenAPI
Empieza por la spec legible por máquinas. Lista cada operación pública bajo /api/v1 con su método, sus campos de petición y la forma de su respuesta. Impórtala en tu explorador de APIs o generador de clientes y tendrás llamadas tipadas en un minuto.
- OpenAPI 3.1. JSON en /openapi.json, YAML en /api/openapi.yaml.
- Cada esquema. Campos de petición y respuesta de cada llamada.
- Límites en la spec. El límite de cada operación en 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
Petición
Haz tu primera llamada
Envía un cuerpo JSON a la operación que necesitas. La validación de email devuelve 200 aunque la dirección sea mala, así que lee el campo valid y no el código de estado. La respuesta también dice si el dominio existe, si tiene servidores de correo o si es desechable.
- JSON de ida y vuelta. Cuerpos POST simples con uno o dos campos.
- Sin clave. Las operaciones públicas funcionan sin registro.
- Detalle útil. Registros MX e indicadores de proveedor gratis y desechable.
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
Dale a tu agente las mismas revisiones
Añade el servidor MCP público a tu agente con una línea de configuración. Así tu agente puede validar una dirección, revisar el DKIM de un dominio o puntuar un asunto como llamada de herramienta, y leer un tutorial cuando necesite explicar un paso.
- Streamable HTTP. Una URL: https://firstsales.io/mcp/.
- Manifiesto de descubrimiento. Herramientas listadas en /.well-known/mcp.json.
- Doce herramientas. Email, DNS, dominio, copy y tutoriales.
Límites
Mide tu ritmo con los headers
Cada respuesta te dice dónde estás: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset y RateLimit-Policy. Si te pasas, la respuesta 429 trae un header Retry-After, así tu cliente sabe exactamente cuánto esperar.
- Ventanas por IP. Los límites se reinician cada 60 segundos.
- Headers del IETF. Frena antes de que te rechacen.
- Retry-After en el 429. Tiempo de espera en segundos, más una pista.
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": "..." }

Referencia de endpoints

Cada operación pública, con su ruta y su límite.

Todas las rutas están bajo https://firstsales.io/api/v1. Los límites son por IP en una ventana de 60 segundos. La spec OpenAPI tiene el esquema de petición y respuesta de cada una.

Revisión de emails
Operación	Qué hace	Límite
POST/api/v1/email/validate	Revisa que una dirección tenga un dominio real, servidores de correo y un formato válido.	20/min
POST/api/v1/email/disposable	Puntúa el dominio de una dirección por riesgo de inbox desechable o temporal.	20/min
POST/api/v1/email/catchall	Averigua si un dominio acepta correo para cualquier buzón (catch-all).	20/min

Revisión de DNS
Operación	Qué hace	Límite
POST/api/v1/dns/check	Ejecuta una revisión de DNS, autenticación de email o seguridad sobre un dominio.	10/min
POST/api/v1/dns/dkim	Busca y revisa el registro DKIM de un dominio para un selector.	10/min
POST/api/v1/dns/validate	Ejecuta SPF, DKIM, DMARC y MX juntos, con una puntuación de confianza.	10/min
POST/api/v1/dns/reverse	Búsqueda de DNS inverso (PTR) para una dirección IPv4, con revisión directa.	10/min

Consultas de dominio
Operación	Qué hace	Límite
POST/api/v1/domain/age	Obtén la antigüedad de registro y la fecha de vencimiento de un dominio por RDAP.	10/min
POST/api/v1/domain/dns-records	Trae todos los tipos de registro DNS de un dominio en una sola llamada.	10/min
POST/api/v1/domain/subdomains	Encuentra subdominios a través de los registros de Certificate Transparency.	5/min

Puntuación de copy
Operación	Qué hace	Límite
POST/api/v1/analyze/spam	Puntúa el contenido de un email por riesgo de palabras de spam.	30/min
POST/api/v1/analyze/subject-line	Puntúa un asunto de cold email y sugiere uno mejor.	30/min
POST/api/v1/analyze/cold-email	Califica un borrador completo de cold email en ocho dimensiones.	Ver spec
POST/api/v1/analyze/email-body	Puntúa el cuerpo de un cold email y sugiere mejoras.	30/min
POST/api/v1/analyze/personalization	Encuentra y puntúa los detalles personales de un cold email.	Ver spec

Tutoriales y estado
Operación	Qué hace	Límite
GET/api/v1/public/tutorials	Lista todos los tutoriales públicos de FirstSales.	Ver spec
GET/api/v1/public/tutorials/{slug}	Obtén el contenido completo de un tutorial por su slug.	Ver spec
GET/api/v1/health	Revisa que el servicio esté funcionando.	Ver spec

Versiones, deprecación y límites,por escrito para que tu código pueda confiar en ellos.

Son las mismas reglas que la spec OpenAPI declara en x-apiVersioning, x-deprecationPolicy y x-rateLimit. La spec enlaza directamente a esta sección.

Versiones

La API lleva la versión en la ruta de la URL. La versión actual es v1, así que cada endpoint está en https://firstsales.io/api/v1/<operation>.

Un cambio incompatible sale con un prefijo nuevo, y v1 mantiene su contrato. La forma sin prefijo /api/<operation> es un alias de la versión actual y puede cambiar sin aviso, así que llama a la forma /api/v1/.

Política de deprecación

Una versión tiene soporte durante al menos 180 días después de anunciar su reemplazo.

Cuando una versión queda deprecada, sus respuestas llevan Deprecation: true y un header Sunset con la fecha de retiro (RFC 8594), además de un header Link que apunta a las notas de migración. Los retiros se anuncian en esta página. Hoy ninguna versión está deprecada.

Límites de uso

Cada endpoint tiene un límite por IP en una ventana de 60 segundos: 20 por minuto para revisar emails, 10 para consultas de DNS y dominio y 30 para puntuar copy. Cada respuesta lleva los campos de header RateLimit del IETF, para que un cliente se regule sin esperar un rechazo.

RateLimit-Limit: Peticiones permitidas en la ventana actual
RateLimit-Remaining: Peticiones que aún quedan
RateLimit-Reset: Segundos hasta que se reinicia la ventana
RateLimit-Policy: La política, como <limit>;w=60

Por encima del límite

El endpoint responde 429 con un header Retry-After en segundos y un cuerpo JSON con error, message y hint.

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

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

Guía sencilla

Cómo construir sobre la API de FirstSales sin sorpresas después.

Siete hábitos que mantienen las integraciones funcionando cuando crece el tráfico y cambian las versiones.

01
Elige primero la superficie correcta
Si solo necesitas revisiones que no tocan una cuenta, como validar emails, revisar DNS o puntuar copy, usa la API pública o el servidor MCP público. Si necesitas contactos, campañas o deals de tu propio espacio de trabajo, usa la Developer API, el CLI firstsales o el servidor MCP de la app. Confundirlas es el error inicial más común.
02
Llama siempre a la forma /api/v1
La forma sin prefijo /api/<operation> es un alias de la versión actual y puede cambiar sin aviso. Llama a https://firstsales.io/api/v1/<operation> para que tu código mantenga el contrato v1 cuando salga una versión nueva.
03
Genera tu cliente desde la spec
Los clientes escritos a mano se desfasan. Genera uno desde /openapi.json y vuelve a generarlo cuando cambie la spec. Obtienes los nombres de campo correctos, los tipos correctos y el límite de cada operación en un solo paso.
04
Lee el resultado, no solo el estado
Algunas revisiones responden 200 a una entrada mala porque la revisión en sí funcionó. La validación de email es una: una dirección inválida devuelve 200 con valid en false. Decide según los campos del cuerpo.
05
Regúlate con los headers
Lee RateLimit-Remaining y RateLimit-Reset en cada respuesta. Frena cuando quede poco en lugar de esperar un 429. La revisión de emails permite 20 llamadas por minuto, las consultas de DNS y dominio 10 y la puntuación de copy 30.
06
Maneja el 429 y espera
Cuando llegues al límite, espera los segundos de Retry-After antes de volver a intentar. El campo hint del cuerpo JSON dice qué cambiar. No reintentes en un bucle cerrado; solo mantiene la ventana llena.
07
Atento a los headers de deprecación
Una versión tiene soporte durante al menos 180 días después de anunciar su reemplazo. Cuando una versión queda deprecada, las respuestas llevan Deprecation: true, un header Sunset con la fecha de retiro y un header Link a las notas de migración. Hoy ninguna versión está deprecada.

Antes y después

Revisiones de outreach hechas a mano, y llamadas desde FirstSales

Las mismas revisiones, de dos maneras.

Hecho a mano

Scripts que tienes que mantener.

Un script por revisiónSPF, DKIM, DMARC y MX programados por separado.
Sin contrato compartidoLos campos cambian cuando cambia el script.
Los agentes leen páginasLento, frágil y difícil de confiar.
Fallos silenciososErrores sin pista de qué salió mal.
Límites a ciegasLos servicios rechazan sin avisar.
Trabajo de cuenta a manoImportaciones e informes en el navegador.

API de FirstSales

Una spec, una URL base.

Dieciocho operacionesEmail, DNS, dominio, copy y tutoriales.
Spec OpenAPI 3.1Genera un cliente tipado desde ella.
Herramientas MCPLos agentes llaman las revisiones directamente.
Errores clarosError, message y hint en cada rechazo.
Límites visiblesHeaders RateLimit en cada respuesta.
Acceso a la cuenta desde códigoDeveloper API, CLI y servidor MCP de la app.

De un vistazo

Acceso para desarrolladores: construirlo tú frente a FirstSales

Lo que cuesta ejecutar revisiones de outreach y flujos de cuenta desde código, a mano y con FirstSales.

Construir revisiones de outreach tú mismo comparado con la API de FirstSales
Qué incluye	Construirlo tú	FirstSales
Revisión de direcciones	Tus propias búsquedas MX	Llamadas de validación, desechable y catch-all
SPF, DKIM y DMARC	Un parser por tipo de registro	Una llamada o todas juntas, con puntuación
Puntuación de copy	Listas de palabras que mantienes	Spam, asunto, cuerpo y borrador completo
Contrato legible por máquinas	Lo que haga el código	OpenAPI 3.1 en JSON y YAML
Acceso para agentes	Leer páginas	Servidor MCP público con doce herramientas
Límites de uso	Los descubres por las malas	Por IP, mostrados en headers
Versiones	Ninguna	/api/v1 con 180 días de aviso de deprecación
Tu cuenta desde código	El navegador	Developer API, CLI y servidor MCP de la app
		Empieza tu prueba de $1

Antes de publicar

Diez revisiones para una integración con FirstSales

Repásalas antes de que tu integración salga en vivo.

Elegiste la superficie pública o la de cuenta a propósito
Cada llamada usa la ruta /api/v1
Tu cliente se genera desde la spec actual
Los resultados se leen del cuerpo, no solo del estado
Los headers RateLimit se registran y se respetan
Las respuestas 429 esperan Retry-After
Los errores registran el campo hint
Los headers Deprecation y Sunset lanzan una alerta
Los agentes usan el servidor MCP, no leen páginas
Las claves y tokens de cuenta quedan fuera de tu código

Lo que dice la gente

De personas que lo usan

Palabras reales de usuarios reales, en su idioma original. Sin reseñas pagadas.

“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

Leer todas las reseñas

Preguntas,respondidas con claridad.

¿No encuentras la tuya? Escríbenos.

01¿Necesito una clave para la API de FirstSales?

No para la API pública ni para el servidor MCP público. Cubren revisión de emails, consultas de DNS y dominio, puntuación de copy y tutoriales. Solo necesitas tu propia cuenta para la Developer API, el CLI firstsales y el servidor MCP de la app.

02¿Dónde está la spec OpenAPI?

La spec pública es OpenAPI 3.1, en /openapi.json en JSON y en /api/openapi.yaml en YAML. La Developer API autenticada tiene su propia spec en developer.firstsales.io.

03¿Cómo conecto el servidor MCP a Claude?

Añade un servidor llamado firstsales con la URL https://firstsales.io/mcp/ a la configuración de tu cliente MCP. Usa Streamable HTTP, y las herramientas están listadas en el manifiesto en /.well-known/mcp.json.

04¿Cuáles son los límites de uso?

Los límites son por IP en una ventana de 60 segundos: 20 llamadas por minuto para revisar emails, 10 para consultas de DNS y dominio y 30 para puntuar copy. El límite exacto de cada operación está en la spec en x-rateLimit, y cada respuesta lleva headers RateLimit.

05¿Qué pasa si paso el límite?

El endpoint responde 429 con un header Retry-After en segundos y un cuerpo JSON con los campos error, message y hint. Espera lo que indique Retry-After antes de volver a llamar.

06¿Cómo se versiona la API?

La versión va en la ruta. La versión actual es v1, así que llama a https://firstsales.io/api/v1/<operation>. Un cambio incompatible sale con un prefijo nuevo, y una versión tiene soporte durante al menos 180 días después de anunciar su reemplazo.

07¿Cómo instalo el CLI de FirstSales?

Instala el paquete npm @firstsales.io/cli. Añade un binario llamado firstsales. La referencia del CLI en developer.firstsales.io lista cada comando.

08¿Puedo probar FirstSales antes de construir sobre él?

Sí. La API pública funciona sin cuenta. Para probar la app y las superficies de tu cuenta, empieza una prueba por $1 por 3 días. Los planes empiezan en $29/mes con buzones y espacios de trabajo ilimitados.

Prospección que sigue cuando te desconectas.Leads, emails, seguimientos y respuestas, resueltos.

Conecta buzones ilimitados y deja que los agentes de IA busquen leads, escriban cada email y hagan seguimiento. O envía tus propias plantillas en modo manual. Desde $29/mes.

Empieza tu prueba de $1 Ver precios

$1 por 3 días · Cancela cuando quieras · Sin contrato

La API para desarrolladores, el CLI y el servidor MCP de FirstSales, para personas y agentes que construyen.

Las revisiones de outreach se necesitan rápido y se construyen bien despacio.

Las revisiones de DNS tienen muchos casos raros

Los agentes leen páginas cuando no pueden llamar

Los datos de la cuenta se quedan en la app

Seis formas de entrar,separadas según necesites una cuenta o no.

API REST pública

Servidor MCP público

Markdown para agentes

Developer API

CLI firstsales

Servidor MCP de la app

Conecta el servidor MCP público

Empieza con una llamada pública, y conecta tu cuenta cuando la necesites.

Lee la spec

Haz una llamada pública

Conecta tu cuenta

Contratos claros, para que tu código y tus agentes sigan funcionando.

Una spec para todo

Herramientas MCP para agentes

Rutas con versión

Límites que puedes ver

Errores claros

Tu cuenta desde código

Cómo usa un desarrolladorla API y el servidor MCP de FirstSales

Importa la spec OpenAPI

Haz tu primera llamada

Dale a tu agente las mismas revisiones

Mide tu ritmo con los headers

Cada operación pública, con su ruta y su límite.

Versiones, deprecación y límites,por escrito para que tu código pueda confiar en ellos.

Versiones

Política de deprecación

Límites de uso

Por encima del límite

Cómo construir sobre la API de FirstSales sin sorpresas después.

Elige primero la superficie correcta

Llama siempre a la forma /api/v1

Genera tu cliente desde la spec

Lee el resultado, no solo el estado

Regúlate con los headers

Maneja el 429 y espera

Atento a los headers de deprecación