n8n-nodes-emkt

Community nodes privados para a API Emkt (email marketing). Uso interno e nas instalações dos clientes — não é pacote verificado do marketplace n8n.

Versões

• 0.3.0 (16/09/2026) — o node cria e edita sequências com vários
  gatilhos (Create/Update em Sequence); testes do que vai para a API (o
  corpo de cada operação, inclusive o = que a URL com expressão exige). No
  npm o pacote não leva dependência de runtime — npm audit --omit=dev está
  limpo; os avisos do npm audit são do n8n-workflow/vitest de
  desenvolvimento.
• 0.2.2 — origem (UTM) e landing URL no node; custom fields do n8n.

O que inclui

Credenciais

Crie uma credential Emkt API com:

O node envia X-Api-Key em todas as chamadas. Use Test na credential para validar (GET /api/contacts?per_page=1).

Referência completa da API: /help na instalação, ou API.md no monorepo.

Operações (v1)

Contact

Create/Upsert · Get · Get Many · Update · Delete · Add/Remove Tag · Add/Remove from List

Custom fields no Create/Update: coleção Add Custom Field (dropdown com slugs de /api/contact-fields + valor).

Origem no Create/Upsert: coleção Origin (UTM) (source, medium, campaign, term, content) + Landing URL. Vai para o histórico em contact_utms, não para custom fields — por isso não aparece no Update, que não grava origem.

List / Tag

Get Many · Create · Delete

Sequence

Get Many · Get · Create · Update · Enroll · Cancel Enrollment

Multigatilho. Uma sequência pode ter vários gatilhos, e qualquer um deles
inscreve ("OU" entre eles; o contato entra uma vez só). Há dois caminhos, e o
antigo continua valendo:

• um gatilho (no Create): Trigger Type + Trigger List ID / Trigger Tag
  ID, como sempre foi. É o corpo que a API já aceitava, e continua criando a
  sequência de um gatilho só;
• vários (Create e Update): a coleção Triggers, um item por gatilho.
  Quando preenchida, ela substitui a lista inteira e o primeiro item vira o
  primário. Deixada vazia, não vai no corpo — no Create o caminho de cima é o
  que vale, e no Update nenhum gatilho é tocado.

No Update o node edita a lista inteira, não um gatilho só. A API também aceita
um PATCH com os campos trigger_* soltos, que edita o primário
preservando os extras; isso não está exposto aqui para a operação não ter dois
jeitos de mexer na mesma coisa — quem precisa disso monta a lista inteira, que é
o que a tela também faz.

Get e Get Many trazem triggers — a lista completa, ordenada, com o
position 0 sendo o primário. Antes só o Get trazia: na listagem via-se o
primário (pelas colunas trigger_*) e um trigger_count dizendo que havia
outros, sem dizer quais.

Campaign

Get Many · Get · Send Test · Send

Suppression

Add · Delete (Force para hard_bounce/complaint)

Emkt Trigger

Ao ativar o workflow, registra POST /api/webhooks/endpoints com a URL do n8n. Em cada entrega valida X-Emkt-Signature (HMAC-SHA256). Ao desativar, remove o endpoint.

A URL do webhook do n8n precisa ser pública (a API recusa loopback/rede privada por anti-SSRF).

Instalação no n8n (self-hosted)

1. Build do pacote:

cd packages/n8n-nodes-emkt
npm install
npm run build
npm pack

2. No servidor do n8n, habilite community packages (N8N_COMMUNITY_PACKAGES_ENABLED=true).

3. Instale o tarball (ou o diretório do pacote):

# opção A — tarball
cd ~/.n8n
mkdir -p custom
cd custom
npm init -y
npm install /caminho/para/n8n-nodes-emkt-0.1.0.tgz

# opção B — apontar N8N_CUSTOM_EXTENSIONS para o pacote buildado
# N8N_CUSTOM_EXTENSIONS=/caminho/para/packages/n8n-nodes-emkt

4. Reinicie o n8n. Os nodes Emkt e Emkt Trigger aparecem no painel.

Por cliente

Cada instalação Emkt tem a própria Base URL + API Key. Crie uma credential por cliente no n8n.

Exemplo rápido

1. Credential Emkt apontando para a API do cliente
2. Node Emkt → Contact → Create/Upsert (email, lists: Newsletter)
   • Custom Fields: botão Add Custom Field — escolhe o campo na lista e o valor (fixo ou expressão)
3. Node Emkt → Sequence → Enroll (mesmo email + Sequence ID)

Ou use Emkt Trigger (eventos click, unsubscribe) → Slack/CRM.

Desenvolvimento

npm install
npm run build        # gera dist/
npm run typecheck
npm run build:watch  # enquanto edita

O pacote fica fora do workspace pnpm do monorepo (deps próprias via npm) para não puxar a árvore do n8n para o resto do projeto.