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.

O que inclui

| Node | Tipo | Função | |------|------|--------| | Emkt | Action | Contatos, listas, tags, sequências, campanhas, supressões | | Emkt Trigger | Trigger | Webhooks de saída (HMAC) — open, click, bounce, etc. |

Credenciais

Crie uma credential Emkt API com:

| Campo | Exemplo | |-------|---------| | Base URL | https://emkt.cliente.com.br (sem / no final) | | API Key | valor de API_KEY do servidor |

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 · Enroll · Cancel Enrollment

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.