Aller au contenu
NouveauDécouvrir comment

Développeurs

L'API développeur, le CLI et le serveur MCP de FirstSales, pour les personnes et les agents qui construisent.

Vérifiez des adresses email, des enregistrements DNS et des textes de cold email depuis votre propre code, sans clé. Donnez les mêmes vérifications à votre agent IA sous forme d'outils MCP. Quand vous avez besoin de votre compte, utilisez la Developer API authentifiée, le CLI firstsales ou le serveur MCP de l'app.

$1 pour 3 jours · Annulez quand vous voulez · Sans engagement

  • 01

    Dix-huit opérations publiques, sans clé

  • 02

    Douze outils MCP pour tout client MCP

  • 03

    Spec OpenAPI 3.1 en JSON et YAML

  • 04

    Developer API et CLI pour votre propre compte

Pourquoi cela existe

On a vite besoin de vérifications de prospection et on met longtemps à bien les construire.

La plupart des équipes refont les mêmes petites vérifications : cette adresse est-elle réelle, ce domaine est-il configuré, cet email va-t-il ressembler à du spam. Chacune prend plus de temps qu'il n'y paraît.

Le DNS regorge de cas particuliers

SPF, DKIM et DMARC ont chacun leur format d'enregistrement, leurs sélecteurs et leurs règles de recherche. Un script rapide marche sur votre domaine et échoue sur le suivant.

Les agents lisent des pages faute de pouvoir appeler

Un agent IA sans outil adapté lit des pages web et devine. C'est lent, ça casse quand une page change et les réponses ne sont pas fiables.

Les données du compte restent dans l'app

Quand le seul moyen d'ajouter des contacts ou de lire une campagne est le navigateur, chaque import, rapport et synchronisation devient un travail manuel pour quelqu'un de l'équipe.

Six points d'entrée,selon que vous ayez besoin d'un compte ou non.

Les surfaces publiques répondent aux questions de délivrabilité et de rédaction pour tout le monde, sans clé. Les surfaces de compte agissent sur votre propre espace de travail FirstSales : contacts, campagnes, deals et plus.

  • Public, sans clé

    API REST publique

    Dix-huit opérations pour vérifier des emails, interroger le DNS et les domaines, noter des textes et lire des tutoriels, décrites par un seul document OpenAPI 3.1.

    Ouvrir /openapi.json
  • Public, sans clé

    Serveur MCP public

    Douze de ces vérifications sous forme d'outils MCP en Streamable HTTP, pour qu'un agent les appelle directement au lieu de lire des pages.

    Ouvrir le manifeste MCP
  • Public, sans clé

    Markdown pour les agents

    Une carte du contenu dans /llms.txt et une copie Markdown propre des pages du site pour les LLM et les crawlers qui préfèrent le texte au HTML.

    Ouvrir /llms.txt
  • Votre compte

    Developer API

    L'API authentifiée pour votre propre espace de travail. Elle couvre les flux du compte et reste distincte de l'API publique de diagnostic de ce site.

    Lire la documentation de la Developer API
  • Votre compte

    CLI firstsales

    Le paquet npm @firstsales.io/cli installe un binaire nommé firstsales, pour lancer les flux du compte depuis un terminal ou un script.

    Lire la référence du CLI
  • Votre compte

    Serveur MCP de l'app

    Un serveur MCP protégé par OAuth pour les actions dans l'app et les données du compte, pour qu'un agent travaille dans votre compte FirstSales avec votre accord.

    Lire le guide du MCP de l'app

Connectez le serveur MCP public

Ajoutez ceci à Claude Desktop, Claude Code ou tout client MCP compatible Streamable HTTP. Les outils apparaissent tout de suite dans votre agent.

{
  "mcpServers": {
    "firstsales": {
      "url": "https://firstsales.io/mcp/"
    }
  }
}
Du premier appel à votre propre compte

Commencez par un appel public, puis connectez votre compte quand il le faut.

Pas besoin de compte pour essayer l'API publique ou le serveur MCP. Connectez-vous seulement pour agir sur votre propre espace de travail.

  1. 01

    Lisez la spec

    Ouvrez /openapi.json ou /api/openapi.yaml et importez-la dans votre générateur de clients, votre explorateur d'API ou votre framework d'agents. Chaque opération, champ et limite y figure.

  2. 02

    Faites un appel public

    Envoyez une adresse email en POST à /api/v1/email/validate, ou ajoutez le serveur MCP à votre agent. Sans clé, sans inscription. Lisez les en-têtes RateLimit pour doser vos appels.

  3. 03

    Connectez votre compte

    Pour les contacts, campagnes et deals de votre espace de travail, utilisez la Developer API, le CLI firstsales ou le serveur MCP de l'app protégé par OAuth.

Ce que vous obtenez

Des contrats clairs, pour que votre code et vos agents continuent de fonctionner.

L'API publique est faite pour être lue d'abord par des machines : une spec, des chemins stables, des limites honnêtes et des erreurs claires.

  • Une spec pour tout

    Un seul document OpenAPI 3.1 décrit chaque opération publique, son corps de requête, sa réponse et sa limite. Générez un client dans le langage de votre choix.

  • Des outils MCP pour les agents

    Douze outils en Streamable HTTP, listés dans un manifeste à /.well-known/mcp.json, pour qu'un agent les trouve et les appelle sans code de liaison.

  • Des chemins versionnés

    Chaque endpoint vit sous /api/v1. Un changement incompatible sort sous un nouveau préfixe, et v1 garde son contrat.

  • Des limites visibles

    Chaque réponse porte des en-têtes RateLimit avec la limite, le reste et l'heure de remise à zéro, pour que votre client ralentisse avant d'être refusé.

  • Des erreurs claires

    Au-delà de la limite, vous recevez un 429 avec Retry-After en secondes et un corps JSON avec les champs error, message et hint qui disent quoi faire ensuite.

  • Votre compte depuis le code

    La Developer API, le CLI firstsales et le serveur MCP de l'app accèdent à votre espace de travail : imports, rapports et synchronisations sans navigateur.

Comment un développeur utilisel'API et le serveur MCP de FirstSales

Quatre étapes, de la lecture de la spec à la gestion d'une limite. Les exemples utilisent des données fictives.

  1. Spec

    Importez la spec OpenAPI

    Partez de la spec lisible par machine. Elle liste chaque opération publique sous /api/v1 avec sa méthode, ses champs de requête et la forme de sa réponse. Importez-la dans votre explorateur d'API ou votre générateur de clients et vous avez des appels typés en une minute.

    • OpenAPI 3.1. JSON à /openapi.json, YAML à /api/openapi.yaml.
    • Chaque schéma. Champs de requête et de réponse pour chaque appel.
    • Limites dans la spec. La limite de chaque opération sous x-rateLimit.
  2. Requête

    Faites votre premier appel

    Envoyez un corps JSON à l'opération voulue. La validation d'email renvoie 200 même quand l'adresse est mauvaise : lisez donc le champ valid plutôt que le code de statut. La réponse dit aussi si le domaine existe, a des serveurs de messagerie ou est jetable.

    • JSON en entrée et en sortie. Des corps POST simples avec un ou deux champs.
    • Sans clé. Les opérations publiques marchent sans inscription.
    • Des détails utiles. Enregistrements MX, indicateurs gratuit et jetable.
  3. MCP

    Donnez les mêmes vérifications à votre agent

    Ajoutez le serveur MCP public à votre agent avec une ligne de configuration. Votre agent peut alors valider une adresse, vérifier le DKIM d'un domaine ou noter un objet par un appel d'outil, et lire un tutoriel quand il doit expliquer une étape.

    • Streamable HTTP. Une URL : https://firstsales.io/mcp/.
    • Manifeste de découverte. Outils listés dans /.well-known/mcp.json.
    • Douze outils. Email, DNS, domaine, textes et tutoriels.
  4. Limites

    Dosez vos appels avec les en-têtes

    Chaque réponse vous dit où vous en êtes : RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset et RateLimit-Policy. Si vous dépassez, la réponse 429 contient un en-tête Retry-After, et votre client sait exactement combien de temps attendre.

    • Fenêtres par IP. Les limites se remettent à zéro toutes les 60 secondes.
    • En-têtes de l'IETF. Ralentissez avant d'être refusé.
    • Retry-After sur le 429. Le délai en secondes, plus une indication.
Référence des endpoints

Chaque opération publique, avec son chemin et sa limite.

Tous les chemins sont sous https://firstsales.io/api/v1. Les limites s'appliquent par IP sur une fenêtre de 60 secondes. La spec OpenAPI donne le schéma de requête et de réponse de chacune.

Vérification d'emails
OpérationCe qu'elle faitLimite
POST/api/v1/email/validateVérifie qu'une adresse a un vrai domaine, des serveurs de messagerie et un format valide.20/min
POST/api/v1/email/disposableNote le domaine d'une adresse selon le risque de boîte jetable ou temporaire.20/min
POST/api/v1/email/catchallIndique si un domaine accepte le courrier pour n'importe quelle boîte (catch-all).20/min
Vérifications DNS
OpérationCe qu'elle faitLimite
POST/api/v1/dns/checkLance une vérification DNS, d'authentification email ou de sécurité sur un domaine.10/min
POST/api/v1/dns/dkimRecherche et vérifie l'enregistrement DKIM d'un domaine pour un sélecteur.10/min
POST/api/v1/dns/validateLance SPF, DKIM, DMARC et MX ensemble, avec un score de confiance.10/min
POST/api/v1/dns/reverseRecherche DNS inverse (PTR) pour une adresse IPv4, avec vérification directe.10/min
Recherches de domaine
OpérationCe qu'elle faitLimite
POST/api/v1/domain/ageDonne l'âge d'enregistrement et la date d'expiration d'un domaine via RDAP.10/min
POST/api/v1/domain/dns-recordsRécupère tous les types d'enregistrements DNS d'un domaine en un appel.10/min
POST/api/v1/domain/subdomainsTrouve les sous-domaines via les journaux Certificate Transparency.5/min
Notation des textes
OpérationCe qu'elle faitLimite
POST/api/v1/analyze/spamNote le contenu d'un email selon le risque de mots déclencheurs de spam.30/min
POST/api/v1/analyze/subject-lineNote un objet de cold email et en propose un meilleur.30/min
POST/api/v1/analyze/cold-emailÉvalue un brouillon complet de cold email sur huit dimensions.Voir la spec
POST/api/v1/analyze/email-bodyNote le corps d'un cold email et propose des améliorations.30/min
POST/api/v1/analyze/personalizationRepère et note les éléments personnels d'un cold email.Voir la spec
Tutoriels et état
OpérationCe qu'elle faitLimite
GET/api/v1/public/tutorialsListe tous les tutoriels publics de FirstSales.Voir la spec
GET/api/v1/public/tutorials/{slug}Donne le contenu complet d'un tutoriel par son slug.Voir la spec
GET/api/v1/healthVérifie que le service fonctionne.Voir la spec

Versions, dépréciation et limites,écrites pour que votre code puisse s'y fier.

Ce sont les règles que la spec OpenAPI déclare dans x-apiVersioning, x-deprecationPolicy et x-rateLimit. La spec renvoie directement vers cette section.

Versions

La version de l'API figure dans le chemin de l'URL. La version actuelle est v1, donc chaque endpoint est accessible à https://firstsales.io/api/v1/<operation>.

Un changement incompatible sort sous un nouveau préfixe, et v1 garde son contrat. La forme sans préfixe /api/<operation> est un alias de la version actuelle et peut changer sans préavis, donc appelez la forme /api/v1/.

Politique de dépréciation

Une version reste prise en charge au moins 180 jours après l'annonce de son remplacement.

Une fois une version dépréciée, ses réponses portent Deprecation: true et un en-tête Sunset avec la date de retrait (RFC 8594), ainsi qu'un en-tête Link vers les notes de migration. Les retraits sont annoncés sur cette page. Aucune version n'est dépréciée aujourd'hui.

Limites d'usage

Chaque endpoint est limité par IP sur une fenêtre de 60 secondes : 20 par minute pour les vérifications d'emails, 10 pour les recherches DNS et de domaine et 30 pour la notation des textes. Chaque réponse porte les champs d'en-tête RateLimit de l'IETF, pour qu'un client se régule sans attendre un refus.

RateLimit-Limit
Requêtes autorisées dans la fenêtre en cours
RateLimit-Remaining
Requêtes encore disponibles
RateLimit-Reset
Secondes avant la remise à zéro de la fenêtre
RateLimit-Policy
La politique, sous la forme <limit>;w=60

Au-delà de la limite

L'endpoint répond 429 avec un en-tête Retry-After en secondes et un corps JSON contenant error, message et hint.

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

{ "error": "...", "message": "...", "hint": "..." }
“I've been using FirstSales.io for several months now, and I can confidently say it has revolutionized how I approach lead generation and customer acquisition.”
Paweł StelmachSmall business owner · Trustpilot
Guide simple

Comment construire sur l'API FirstSales sans mauvaises surprises.

Sept habitudes qui gardent vos intégrations en état de marche quand le trafic grandit et que les versions changent.

  1. 01

    Choisissez d'abord la bonne surface

    Si vous n'avez besoin que de vérifications sans compte, comme valider un email, vérifier le DNS ou noter un texte, utilisez l'API publique ou le serveur MCP public. Pour les contacts, campagnes ou deals de votre espace de travail, utilisez la Developer API, le CLI firstsales ou le serveur MCP de l'app. Les confondre est la première erreur la plus courante.

  2. 02

    Appelez toujours la forme /api/v1

    La forme sans préfixe /api/<operation> est un alias de la version actuelle et peut changer sans préavis. Appelez https://firstsales.io/api/v1/<operation> pour que votre code garde le contrat v1 quand une nouvelle version sort.

  3. 03

    Générez votre client depuis la spec

    Les clients écrits à la main dérivent. Générez-en un depuis /openapi.json et régénérez-le quand la spec change. Vous obtenez les bons noms de champs, les bons types et la limite de chaque opération en une étape.

  4. 04

    Lisez le résultat, pas seulement le statut

    Certaines vérifications répondent 200 à une mauvaise entrée parce que la vérification elle-même a fonctionné. La validation d'email en fait partie : une adresse invalide renvoie 200 avec valid à false. Décidez selon les champs du corps.

  5. 05

    Régulez-vous avec les en-têtes

    Lisez RateLimit-Remaining et RateLimit-Reset sur chaque réponse. Ralentissez quand il reste peu d'appels au lieu d'attendre un 429. Les vérifications d'emails permettent 20 appels par minute, les recherches DNS et de domaine 10 et la notation des textes 30.

  6. 06

    Gérez le 429 et patientez

    Quand vous atteignez la limite, attendez le nombre de secondes indiqué par Retry-After avant de réessayer. Le champ hint du corps JSON dit quoi changer. Ne réessayez pas en boucle serrée : cela garde la fenêtre pleine.

  7. 07

    Surveillez les en-têtes de dépréciation

    Une version reste prise en charge au moins 180 jours après l'annonce de son remplacement. Une fois une version dépréciée, les réponses portent Deprecation: true, un en-tête Sunset avec la date de retrait et un en-tête Link vers les notes de migration. Aucune version n'est dépréciée aujourd'hui.

Avant et après

Des vérifications de prospection faites à la main, et appelées depuis FirstSales

Les mêmes vérifications, de deux façons.

Fait à la main

Des scripts à maintenir.

  • Un script par vérificationSPF, DKIM, DMARC et MX codés séparément.
  • Aucun contrat partagéLes champs changent quand le script change.
  • Les agents lisent des pagesLent, fragile et peu fiable.
  • Échecs silencieuxDes erreurs sans indice sur la cause.
  • Limites à l'aveugleLes services refusent sans prévenir.
  • Le compte à la mainImports et rapports dans le navigateur.
API FirstSales

Une spec, une URL de base.

  • Dix-huit opérationsEmail, DNS, domaine, textes et tutoriels.
  • Spec OpenAPI 3.1Générez-en un client typé.
  • Outils MCPLes agents appellent les vérifications directement.
  • Erreurs clairesError, message et hint à chaque refus.
  • Limites visiblesEn-têtes RateLimit sur chaque réponse.
  • Le compte depuis le codeDeveloper API, CLI et serveur MCP de l'app.
En un coup d'œil

Accès développeur : tout construire soi-même ou FirstSales

Ce qu'il faut pour lancer des vérifications de prospection et des flux de compte depuis le code, à la main et avec FirstSales.

Construire ses vérifications de prospection comparé à l'API FirstSales
Ce que vous obtenezTout construire soi-mêmeFirstSales
Vérification d'adressesVos propres recherches MXAppels de validation, jetable et catch-all
SPF, DKIM et DMARCUn parseur par type d'enregistrementUn appel ou tous ensemble, avec un score
Notation des textesDes listes de mots à maintenirSpam, objet, corps et brouillon complet
Contrat lisible par machineCe que fait le codeOpenAPI 3.1 en JSON et YAML
Accès pour les agentsLecture de pagesServeur MCP public avec douze outils
Limites d'usageDécouvertes à vos dépensPar IP, affichées dans les en-têtes
VersionsAucune/api/v1 avec 180 jours de préavis de dépréciation
Votre compte depuis le codeLe navigateurDeveloper API, CLI et serveur MCP de l'app
Démarrez votre essai à $1
Avant la mise en ligne

Dix vérifications pour une intégration FirstSales

Passez-les en revue avant que votre intégration soit en ligne.

  • Vous avez choisi la surface publique ou de compte en connaissance de cause
  • Chaque appel utilise le chemin /api/v1
  • Votre client est généré depuis la spec actuelle
  • Les résultats se lisent dans le corps, pas seulement dans le statut
  • Les en-têtes RateLimit sont journalisés et respectés
  • Les réponses 429 attendent Retry-After
  • Les erreurs journalisent le champ hint
  • Les en-têtes Deprecation et Sunset déclenchent une alerte
  • Les agents utilisent le serveur MCP, pas la lecture de pages
  • Les clés et jetons du compte restent hors de votre code

Questions,réponses claires.

Vous ne trouvez pas la vôtre ? Écrivez-nous.

01Faut-il une clé pour l'API FirstSales ?

Pas pour l'API publique ni pour le serveur MCP public. Ils couvrent la vérification d'emails, les recherches DNS et de domaine, la notation des textes et les tutoriels. Vous n'avez besoin de votre compte que pour la Developer API, le CLI firstsales et le serveur MCP de l'app.

02Où se trouve la spec OpenAPI ?

La spec publique est en OpenAPI 3.1, à /openapi.json en JSON et à /api/openapi.yaml en YAML. La Developer API authentifiée a sa propre spec sur developer.firstsales.io.

03Comment connecter le serveur MCP à Claude ?

Ajoutez un serveur nommé firstsales avec l'URL https://firstsales.io/mcp/ dans la configuration de votre client MCP. Il utilise Streamable HTTP, et les outils sont listés dans le manifeste à /.well-known/mcp.json.

04Quelles sont les limites d'usage ?

Les limites s'appliquent par IP sur une fenêtre de 60 secondes : 20 appels par minute pour les vérifications d'emails, 10 pour les recherches DNS et de domaine et 30 pour la notation des textes. La limite exacte de chaque opération figure dans la spec sous x-rateLimit, et chaque réponse porte des en-têtes RateLimit.

05Que se passe-t-il au-delà de la limite ?

L'endpoint répond 429 avec un en-tête Retry-After en secondes et un corps JSON avec les champs error, message et hint. Attendez la durée de Retry-After avant de rappeler.

06Comment l'API est-elle versionnée ?

La version figure dans le chemin. La version actuelle est v1, donc appelez https://firstsales.io/api/v1/<operation>. Un changement incompatible sort sous un nouveau préfixe, et une version reste prise en charge au moins 180 jours après l'annonce de son remplacement.

07Comment installer le CLI FirstSales ?

Installez le paquet npm @firstsales.io/cli. Il ajoute un binaire nommé firstsales. La référence du CLI sur developer.firstsales.io liste chaque commande.

08Puis-je essayer FirstSales avant de construire dessus ?

Oui. L'API publique fonctionne sans compte. Pour essayer l'app et les surfaces de votre compte, lancez un essai pour $1 pour 3 jours. Les abonnements commencent à $29/mois avec des boîtes et des espaces de travail illimités.

Une prospection qui continue quand vous vous déconnectez.Leads, emails, relances et réponses, gérés.

Connectez des boîtes illimitées et laissez les agents IA trouver les leads, écrire chaque email et relancer. Ou envoyez vos propres modèles en mode manuel. À partir de $29/mois.

$1 pour 3 jours · Annulez quand vous voulez · Sans engagement

Installer avec l'IA

Votre agent de code installe la CLI et les skills FirstSales pour vous.

Prompt pour Claude Code

I'm setting up FirstSales (https://firstsales.io), an AI outbound sales platform: campaigns, contacts, a reply inbox, deliverability and lead signals. Help me get my workspace sending real, good emails end to end, from Claude Code.

Read these first so you know how FirstSales works:
- Developer docs and API: https://developer.firstsales.io
- CLI: https://www.npmjs.com/package/@firstsales.io/cli
- Skills for coding agents: https://github.com/firstsalesio/firstsales-skills (read README.md and GUIDE.md)

Setup
1. Install the CLI: npm install -g @firstsales.io/cli
2. Install the FirstSales skills:
   claude plugin marketplace add firstsalesio/firstsales-skills
   claude plugin install firstsales@firstsales
3. Ask me if I already have a FirstSales account. If not, send me to https://app.firstsales.io to sign up.
4. Ask me to create an API key under Settings → API → API Keys, with only the scopes we need.
   Never ask me to paste the key into this chat. Tell me to run this in my own terminal, so the key stays hidden:
   read -rs FS_KEY && firstsales auth login --api-key "$FS_KEY"; unset FS_KEY
5. Run `firstsales whoami` and tell me which workspace and organisation we are connected to.

Then ask me about my business: what I sell, who I sell to (roles, company size, countries), my best customers, and what I use today for outbound (tools, lists, mailboxes). Walk me through:
1. Teaching FirstSales my business: website, offer, proof points and case studies in the knowledge base, so the AI writes like someone who knows the product.
2. Connecting my sending mailboxes and checking my sending domain: SPF, DKIM, DMARC and warm-up. If anything is unhealthy, tell me the exact DNS record to add.
3. Bringing in contacts: import my CSV or CRM export into a clean list, remove duplicates and bad emails, and block domains I must never email (customers, competitors, my own).
4. Building my first campaign: the right list, senders, steps and timing. Write the sequence with me, show me the drafts, and do not launch until I say yes.
5. Setting up Signals if it fits: find people engaging with LinkedIn posts about topics my buyers care about, and turn them into leads.
6. Inviting my team and giving each person the right access.

Once campaigns run, show me how to work the reply inbox from here: which replies need an answer, draft responses in my voice, and move good conversations into deals. If I use Cal.com, connect it so follow-ups can offer my booking link (not the first email).

Throughout, as you learn about my business, proactively suggest and help create:
- Reply templates for the questions and objections my prospects are likely to raise, based on my product, site and codebase if you can see them.
- Campaign ideas and segments worth testing, with the reason for each.

Safety rules:
- Show every change as a dry run (--dry-run) first and wait for my yes. Never send emails, launch campaigns or delete anything without my yes.
- Tell me before anything that spends credits, and how many.

Be opinionated. If the docs give a sensible default, just use it. Don't make me choose between five options.