Saltar al contenido
NuevoVer cómo

Gestionar contactos con la CLI de FirstSales

Crea, lee, actualiza y elimina contactos, listas y etiquetas desde la línea de comandos — creaciones idempotentes, importaciones masivas, exportaciones y borrados deliberados con alcance a un org y workspace.

Tutoriales
Desarrollador y CLI
min de lectura
8 min
pasos
7 · Avanzado

  1. Lista y lee contactos

    Todo está delimitado por una organización y un workspace. Comienza en modo de solo lectura: lista contactos, luego obtén uno por ID:

    firstsales contacts list --org ORG_ID --workspace WS_ID --json
firstsales contacts get --org ORG_ID --workspace WS_ID --contact CONTACT_ID

  2. Crea y actualiza un contacto

    Crea con una clave de idempotencia para que los reintentos no dupliquen; actualizar aplica un parche solo a los campos que envíes:

    firstsales contacts create --org ORG_ID --workspace WS_ID \
  --data '{"email":"[email protected]","first_name":"Jane","company_name":"Acme"}' \
  --idempotency-key jane-acme-2026-01

firstsales contacts update --org ORG_ID --workspace WS_ID \
  --contact CONTACT_ID --data '{"job_title":"VP Sales"}'

  3. Organiza con listas

    Las listas de contactos son cómo segmentas a quién le envía una campaña. Crea, renombra y elimina listas desde la CLI:

    firstsales contact-lists list --org ORG_ID --workspace WS_ID
firstsales contact-lists create --org ORG_ID --workspace WS_ID \
  --data '{"name":"Q1 SaaS founders"}'
firstsales contact-lists update --org ORG_ID --workspace WS_ID \
  --list LIST_ID --data '{"name":"Q1 SaaS founders (US)"}'

  4. Gestiona etiquetas en masa

    Las etiquetas son rótulos libres a través de los contactos. Puedes renombrar (lo que fusiona) o eliminar una etiqueta en todos los lugares donde aparece: eliminarla es destructivo, así que requiere --confirm:

    firstsales contact-tags list --org ORG_ID --workspace WS_ID
firstsales contact-tags rename --org ORG_ID --workspace WS_ID \
  --data '{"from":"founder","to":"founders"}'
firstsales contact-tags delete --org ORG_ID --workspace WS_ID \
  --data '{"tag":"stale"}' --confirm

  5. Importación masiva

    Envía un lote de contactos con un trabajo de importación. Apúntalo a una lista; la plataforma deduplica por correo en el servidor, así que reimportar a las mismas personas no crea copias:

    firstsales contact-imports create --org ORG_ID --workspace WS_ID \
  --data-file ./leads.json \
  --idempotency-key import-2026-01

  6. Exporta lo que filtraste

    Lista tus trabajos de exportación / recupera contactos como CSV para reportes o respaldo:

    firstsales contact-exports list --org ORG_ID --workspace WS_ID

  7. Elimina con cuidado

    Eliminar un contacto es destructivo y requiere --confirm. Prefiere dejar que la limpieza suprima automáticamente las direcciones malas en lugar de eliminarlas permanentemente: la eliminación es definitiva:

    firstsales contacts delete --org ORG_ID --workspace WS_ID \
  --contact CONTACT_ID --confirm

Consejos de experto

  • Segmenta con listas, etiqueta con tags

    Las listas deciden a quién le envía una campaña; las etiquetas son rótulos transversales para filtrar. Usa ambas: un contacto puede estar en una lista y llevar muchas etiquetas.

  • La importación es idempotente y deduplicada

    La deduplicación en el servidor por correo significa que volver a ejecutar una importación no duplicará tu lista. Aun así pasa --idempotency-key para que el propio trabajo no se cree dos veces.

  • No elimines permanentemente para suprimir

    Para dejar de enviarle a alguien, deja que la limpieza lo marque como sucio o confía en el estado rebotado/desuscrito: esos se excluyen automáticamente. Reserva contacts delete --confirm para una eliminación genuina.

  • rename fusiona etiquetas

    Renombrar una etiqueta a un nombre existente las fusiona. Útil para limpiar 'founder' vs 'founders': pero no es reversible, así que revisa el nombre destino primero.

Preguntas frecuentes

¿Cómo están delimitados los contactos?

Por una organización y un workspace. Cada comando de contacto lleva --org y --workspace; los mismos IDs de contacto no se resuelven en otro workspace.

¿Cómo evito contactos duplicados al importar?

Las importaciones deduplican por correo en el servidor, así que reimportar a las mismas personas las agrega a la lista sin crear copias. Pasa --idempotency-key para que el propio trabajo de importación también sea seguro de reintentar.

¿Cuál es la diferencia entre listas y etiquetas?

Las listas definen la audiencia a la que le envía una campaña; las etiquetas son rótulos libres para filtrar y segmentar. Un contacto pertenece a listas y puede llevar muchas etiquetas.

¿Cómo elimino una etiqueta en todos lados?

contact-tags delete --confirm la elimina de todos los contactos, y contact-tags rename fusiona una etiqueta en otra. Ambas son destructivas, así que eliminar requiere --confirm.

¿Puedo exportar mis contactos?

Sí: usa contact-exports para recuperar contactos como CSV. En la app, la exportación refleja tu filtro/selección actual; vía la API trabajas con trabajos de exportación.

¿Debería eliminar los contactos que rebotan?

Generalmente no. Los contactos rebotados, desuscritos y marcados por la limpieza (sucios) se excluyen automáticamente de los envíos, así que rara vez hace falta eliminarlos. Elimina permanentemente solo cuando realmente quieras que el registro desaparezca, y requiere --confirm.

Desarrollador y CLI

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

Instalar con IA

Tu agente de código configura la CLI y las skills de FirstSales por ti.

Prompt para 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.
Developer docs ↗npm: @firstsales.io/cli ↗GitHub: firstsales-skills ↗