Pular para o conteúdo
NovoVeja como

Gerencie Contatos com a CLI do FirstSales

Faça CRUD de contatos, listas e tags pela linha de comando — criações idempotentes, importações em massa, exportações e exclusões deliberadas com escopo de org e workspace.

Tutoriais
Desenvolvedor e CLI
min de leitura
8 min
etapas
7 · Avançado

  1. Liste e leia contatos

    Tudo é limitado a uma organização e a um workspace. Comece apenas lendo — liste contatos, depois busque um pelo ID:

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

  2. Crie e atualize um contato

    Crie com uma chave de idempotência para que novas tentativas não dupliquem; a atualização aplica patch apenas nos campos que você enviar:

    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. Organize com listas

    Listas de contatos são como você segmenta para quem uma campanha envia. Crie, renomeie e exclua listas pela 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. Gerencie tags em massa

    Tags são rótulos livres entre contatos. Você pode renomear (o que faz uma fusão) ou excluir uma tag em todos os lugares onde ela aparece — a exclusão é destrutiva, então exige --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. Importação em massa

    Envie um lote de contatos com um job de importação. Aponte para uma lista; a plataforma remove duplicatas por e-mail no servidor, então reimportar as mesmas pessoas não vai criar cópias:

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

  6. Exporte o que você filtrou

    Liste seus jobs de exportação / recupere contatos como CSV para relatórios ou backup:

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

  7. Exclua com cuidado

    Remover um contato é destrutivo e exige --confirm. Prefira deixar a limpeza suprimir automaticamente endereços ruins em vez de excluir permanentemente — a exclusão é definitiva:

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

Dicas de especialista

  • Segmente com listas, rotule com tags

    Listas decidem para quem uma campanha envia; tags são rótulos transversais para filtragem. Use os dois — um contato pode estar em uma lista e carregar várias tags.

  • A importação é idempotente e sem duplicação

    A remoção de duplicatas por e-mail no servidor significa que rodar uma importação de novo não vai dobrar sua lista. Ainda assim, passe --idempotency-key para que o próprio job não seja criado duas vezes.

  • Não exclua permanentemente para suprimir

    Para parar de enviar e-mail a alguém, deixe a limpeza marcá-lo como sujo ou confie no status de bounce/descadastrado — ambos excluem automaticamente. Reserve contacts delete --confirm para uma remoção genuína.

  • renomear funde tags

    Renomear uma tag para um nome já existente as funde. Útil para arrumar 'founder' vs 'founders' — mas não é reversível, então confira o nome de destino antes.

Perguntas frequentes

Como os contatos são delimitados?

A uma organização e um workspace. Todo comando de contato leva --org e --workspace; os mesmos IDs de contato não vão resolver em um workspace diferente.

Como evito contatos duplicados na importação?

As importações removem duplicatas por e-mail no servidor, então reimportar as mesmas pessoas as adiciona à lista sem criar cópias. Passe --idempotency-key para que o próprio job de importação também seja seguro para repetir.

Qual é a diferença entre listas e tags?

Listas definem o público para quem uma campanha envia; tags são rótulos livres para filtragem e segmentação. Um contato pertence a listas e pode carregar várias tags.

Como eu removo uma tag de todos os lugares?

contact-tags delete --confirm a remove de todos os contatos, e contact-tags rename funde uma tag em outra. Ambas são destrutivas, então a exclusão exige --confirm.

Posso exportar meus contatos?

Sim — use contact-exports para recuperar contatos como CSV. No app, a exportação reflete seu filtro/seleção atual; via API você trabalha com jobs de exportação.

Devo excluir contatos que sofrem bounce?

Geralmente não. Contatos com bounce, descadastrados e sinalizados pela limpeza (sujos) são automaticamente excluídos dos envios, então a exclusão raramente é necessária. Exclua permanentemente só quando você realmente quiser que o registro desapareça, e isso exige --confirm.

Desenvolvedor e CLI

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

Instalar com IA

Seu agente de código configura a CLI e as skills do FirstSales para você.

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 ↗