Aller au contenu
NouveauDécouvrir comment

Utiliser FirstSales avec Codex

Connectez Codex à FirstSales via l'API REST (ou la CLI dans un shell) — premier appel whoami, clés à portée limitée, écritures idempotentes et arrêt sur les opérations non prises en charge.

  1. Choisissez le bon chemin pour votre configuration Codex

    FirstSales propose deux voies d'intégration. Si votre environnement Codex dispose d'un shell avec npm, installez @firstsales.io/cli et pilotez-le comme n'importe quel agent shell : il gère l'authentification, le JSON et l'idempotence pour vous. Si Codex s'exécute sans accès shell (navigateur ou sandbox), appelez directement la Developer API en HTTPS. La documentation regroupe Codex avec les agents API-first précisément pour cette raison.

  2. Stockez la clé comme secret d'environnement

    Créez une clé Developer API dans Settings → API et placez-la dans le gestionnaire de secrets de votre environnement Codex sous FIRSTSALES_API_KEY. Ne collez jamais la clé brute dans un prompt et ne la committez jamais : référencez la variable d'environnement dans le code.

    # in your Codex task's environment
    FIRSTSALES_API_KEY=fs-key-...
    FIRSTSALES_BASE_URL=https://api.app.firstsales.io
  3. Vérifiez d'abord l'identité

    Quel que soit le chemin choisi, le premier appel confirme que la clé pointe vers l'org et le workspace attendus :

    curl https://api.app.firstsales.io/api/v1/whoami \
      -H "Authorization: Bearer $FIRSTSALES_API_KEY"
  4. Lisez l'état avant d'écrire

    Faites en sorte que Codex inspecte avant de muter. Les ressources sont rattachées à une org et un workspace :

    curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/campaigns \
      -H "Authorization: Bearer $FIRSTSALES_API_KEY"
    
    curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/contacts \
      -H "Authorization: Bearer $FIRSTSALES_API_KEY"
  5. Écrivez de façon idempotente

    Sur les créations, envoyez un en-tête Idempotency-Key afin qu'une requête retentée ne duplique jamais de données : important pour un agent autonome susceptible de réessayer après un timeout :

    curl -X POST \
      https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/contacts \
      -H "Authorization: Bearer $FIRSTSALES_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: codex-lead-2026-01" \
      -d '{"email":"[email protected]","first_name":"Sam"}'
  6. Gardez Codex sur la surface publique

    Demandez à Codex de n'utiliser que les endpoints publics /api/v1. Face à une réponse unsupported_operation, il doit s'arrêter et le signaler (jamais faire de scraping de l'app ni appeler des routes privées, des callbacks de fournisseur, des pixels de tracking, des gestionnaires de désabonnement ou des endpoints cron pour forcer un résultat. Gérez explicitement 401 (mauvaise clé), 422 (validation) le corps nomme le champ), et 429 (temporisez).

Astuces de pro

  • Shell disponible ? Privilégiez le CLI

    Si votre sandbox Codex peut exécuter npm, le CLI supprime beaucoup de code répétitif : authentification, JSON, idempotence et confirmation de suppression sont gérés pour vous. Ne repassez au HTTP brut que lorsqu'il n'y a pas de shell.

  • La clé vit dans l'environnement, pas dans le prompt

    Placez FIRSTSALES_API_KEY dans le gestionnaire de secrets de Codex et référencez-la. Une clé dans le prompt finit dans les logs et l'historique.

  • whoami est le contrôle de sécurité le moins coûteux

    Un seul appel confirme que Codex cible la bonne org et le bon workspace avant d'écrire quoi que ce soit. Le sauter, c'est comment des données finissent dans le mauvais workspace.

  • Idempotency-Key sur chaque création

    Les agents autonomes réessaient. Une clé d'idempotence stable transforme un POST retenté en no-op plutôt qu'en contact en double ou en double facturation.

Questions fréquentes

Codex doit-il utiliser le CLI ou l'API ?

Si Codex dispose d'un accès shell avec npm, utilisez le CLI. S'il s'exécute dans un navigateur ou une sandbox sans shell, appelez la Developer API en HTTPS. Le chemin API est celui par défaut pour les agents basés navigateur.

Comment donner la clé à Codex en toute sécurité ?

Stockez-la sous FIRSTSALES_API_KEY dans le gestionnaire de secrets/environnement de Codex et référencez la variable dans le code. Ne collez pas la clé brute dans des prompts et ne la committez pas.

Quels sont l'URL de base et le premier appel ?

Base https://api.app.firstsales.io, authentification Bearer. Premier appel GET /api/v1/whoami pour confirmer le contexte org et workspace avant toute écriture.

Comment éviter les écritures en double lors des relances ?

Envoyez un en-tête Idempotency-Key sur les requêtes de création. Une relecture avec la même clé renvoie le résultat d'origine plutôt que de créer un second enregistrement.

Que Codex ne doit-il jamais faire ?

Ne jamais appeler de routes privées de l'app, de callbacks de fournisseur, de pixels de tracking, de gestionnaires de désabonnement ou d'endpoints cron internes, et ne jamais faire de scraping de l'interface de l'app. Rester sur /api/v1 public ; s'arrêter et signaler sur unsupported_operation.

Développeur & CLI

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.