Pular para conteúdo

MAILCHIMP Members Add - Adicionar Assinante

O que é este Node?

O Mailchimp Members Add é o node responsável por adicionar um novo assinante (member) a uma lista do Mailchimp com email, status, merge fields e tags.

Por que este Node existe?

Capturar leads é a base do email marketing. Este node existe para:

  1. Captura de leads: Adicionar novos contatos à lista
  2. Sincronização: Integrar leads de WhatsApp/CRM com Mailchimp
  3. Segmentação: Adicionar tags para segmentar audiência
  4. Personalização: Incluir merge fields (nome, cidade, etc.)
  5. Automação: Inscrever automaticamente em flows

Como funciona internamente?

Quando o Members Add é executado, o sistema:

  1. Valida email e listId
  2. Monta objeto com email, status, merge fields e tags
  3. Faz requisição POST para /lists/{listId}/members
  4. Mailchimp adiciona assinante ou retorna erro se duplicado
  5. Salva resposta na variável
  6. Continua o flow

Código interno (mailchimp.executor.ts:136-164): 

case 'add':
  const email = this.replaceVariables(data.email || '', context.variables);
  const memberData: any = {
    email_address: email,
    status: data.status || 'subscribed', // subscribed, unsubscribed, cleaned, pending
  };

  if (data.mergeFields) {
    try {
      const mergeFields = typeof data.mergeFields === 'string'
        ? JSON.parse(this.replaceVariables(data.mergeFields, context.variables))
        : data.mergeFields;
      memberData.merge_fields = mergeFields;
    } catch (e) {
      this.logger.warn('Failed to parse merge fields:', e);
    }
  }

  if (data.tags) {
    memberData.tags = Array.isArray(data.tags) ? data.tags : data.tags.split(',').map((t: string) => t.trim());
  }

  const addResponse = await axios.post(`${baseUrl}/lists/${listId}/members`, memberData, {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
  });
  return addResponse.data;

Quando você DEVE usar este Node?

Use Members Add quando precisar adicionar assinantes:

Casos de uso:

  1. Captura via WhatsApp: Usuário fornece email no chat
  2. Formulário web: Sincronizar com Mailchimp
  3. Pós-compra: Adicionar cliente à lista
  4. Evento: Inscrever participantes
  5. Migração: Importar de outro sistema

Parâmetros Detalhados

listId (string, obrigatório)

O que é: ID da lista onde o assinante será adicionado.

Formato: String alfanumérica do Mailchimp

email (string, obrigatório)

O que é: Email do assinante a ser adicionado.

Formato: Email válido (validado pelo Mailchimp)

Flow completo para testar:

{
  "name": "Teste Mailchimp Members Add",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "email_1",
      "type": "email",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Capturar Email",
        "parameters": {
          "message": "Qual é o seu email?",
          "variable": "user_email"
        }
      }
    },
    {
      "id": "mailchimp_1",
      "type": "mailchimp",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Adicionar à Lista",
        "resource": "members",
        "operation": "add",
        "config": {
          "apiKey": "{{mailchimp_api_key}}",
          "server": "{{mailchimp_server}}"
        },
        "listId": "{{my_list_id}}",
        "email": "{{user_email}}",
        "status": "subscribed",
        "responseVariable": "newMember"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Confirmação",
        "parameters": {
          "message": "✅ Email {{user_email}} adicionado com sucesso!\n\nVocê receberá nossas novidades em breve."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "email_1" },
    { "source": "email_1", "target": "mailchimp_1" },
    { "source": "mailchimp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Digite um email válido e veja a confirmação!

status (string, opcional)

O que é: Status inicial do assinante.

Padrão: "subscribed"

Valores: - subscribed: Inscrito ativo (recebe emails) - unsubscribed: Descadastrado - pending: Aguardando confirmação (double opt-in) - cleaned: Email inválido (bounce)

Dica: Use "pending" para double opt-in (melhor prática)

mergeFields (string/object, opcional)

O que é: Campos personalizados do assinante (nome, cidade, telefone, etc.).

Formato: JSON string ou objeto

Exemplo: {"FNAME": "João", "LNAME": "Silva", "PHONE": "11999999999"}

Campos comuns: - FNAME: Primeiro nome - LNAME: Sobrenome - PHONE: Telefone - BIRTHDAY: Aniversário (MM/DD) - ADDRESS: Endereço

tags (string/array, opcional)

O que é: Tags para segmentação do assinante.

Formato: Array ou string separada por vírgulas

Exemplos: - Array: ["vip", "black-friday", "sp"] - String: "vip,black-friday,sp"

Parâmetros

Campo Tipo Obrigatório Descrição
listId string Sim ID da lista Mailchimp
email string Sim Email do assinante
status string Não subscribed, pending, unsubscribed, cleaned (padrão: subscribed)
mergeFields string/object Não Campos personalizados (FNAME, LNAME, etc.)
tags string/array Não Tags para segmentação

Exemplo 1: Captura Completa via WhatsApp

Objetivo: Capturar nome, email e telefone via WhatsApp e adicionar ao Mailchimp.

JSON para Importar

{
  "name": "Captura Completa WhatsApp → Mailchimp",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_nome",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Nome",
        "parameters": {
          "message": "Qual é o seu nome completo?",
          "variable": "nome"
        }
      }
    },
    {
      "id": "email_1",
      "type": "email",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Email",
        "parameters": {
          "message": "Qual é o seu email?",
          "variable": "email"
        }
      }
    },
    {
      "id": "phone_1",
      "type": "phone",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Telefone",
        "parameters": {
          "message": "Qual é o seu telefone?",
          "variable": "telefone"
        }
      }
    },
    {
      "id": "mailchimp_1",
      "type": "mailchimp",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Adicionar ao Mailchimp",
        "resource": "members",
        "operation": "add",
        "config": {
          "apiKey": "{{mailchimp_api_key}}",
          "server": "{{mailchimp_server}}"
        },
        "listId": "{{newsletter_list_id}}",
        "email": "{{email}}",
        "status": "subscribed",
        "mergeFields": "{\"FNAME\": \"{{nome}}\", \"PHONE\": \"{{telefone}}\"}",
        "tags": "whatsapp,lead-2025",
        "responseVariable": "subscriber"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Sucesso",
        "parameters": {
          "message": "🎉 Bem-vindo, {{nome}}!\n\n✅ Você foi inscrito com sucesso em nossa newsletter.\n📧 {{email}}\n\nEm breve você receberá nossos conteúdos exclusivos!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1300, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_nome" },
    { "source": "input_nome", "target": "email_1" },
    { "source": "email_1", "target": "phone_1" },
    { "source": "phone_1", "target": "mailchimp_1" },
    { "source": "mailchimp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Qual é o seu nome completo?
Usuário: João Silva
Sistema: Qual é o seu email?
Usuário: joao@exemplo.com
Sistema: Qual é o seu telefone?
Usuário: 11999999999
Sistema: 🎉 Bem-vindo, João Silva!

✅ Você foi inscrito com sucesso em nossa newsletter.
📧 joao@exemplo.com

Em breve você receberá nossos conteúdos exclusivos!

Exemplo 2: Double Opt-In (Melhor Prática)

Objetivo: Adicionar com status "pending" para Mailchimp enviar email de confirmação.

JSON para Importar

{
  "name": "Double Opt-In Mailchimp",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "email_1",
      "type": "email",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Capturar Email",
        "parameters": {
          "message": "Digite seu email para receber nossas novidades:",
          "variable": "email"
        }
      }
    },
    {
      "id": "mailchimp_1",
      "type": "mailchimp",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Adicionar (Pending)",
        "resource": "members",
        "operation": "add",
        "config": {
          "apiKey": "{{mailchimp_api_key}}",
          "server": "{{mailchimp_server}}"
        },
        "listId": "{{list_id}}",
        "email": "{{email}}",
        "status": "pending",
        "responseVariable": "result"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Instruções",
        "parameters": {
          "message": "📧 Email de confirmação enviado!\n\nVerifique sua caixa de entrada ({{email}}) e clique no link de confirmação para completar sua inscrição.\n\n✉️ Não esqueça de verificar o spam!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "email_1" },
    { "source": "email_1", "target": "mailchimp_1" },
    { "source": "mailchimp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Digite seu email para receber nossas novidades:
Usuário: maria@exemplo.com
Sistema: 📧 Email de confirmação enviado!

Verifique sua caixa de entrada (maria@exemplo.com) e clique no link de confirmação para completar sua inscrição.

✉️ Não esqueça de verificar o spam!

Resposta do Node

{
  "id": "abc123def456",
  "email_address": "joao@exemplo.com",
  "unique_email_id": "xyz789",
  "email_type": "html",
  "status": "subscribed",
  "merge_fields": {
    "FNAME": "João",
    "LNAME": "",
    "PHONE": "11999999999"
  },
  "stats": {
    "avg_open_rate": 0,
    "avg_click_rate": 0
  },
  "ip_signup": "192.168.1.1",
  "timestamp_signup": "2025-10-13T10:30:00+00:00",
  "timestamp_opt": "2025-10-13T10:30:00+00:00",
  "member_rating": 2,
  "last_changed": "2025-10-13T10:30:00+00:00",
  "list_id": "abc123list",
  "tags": [
    {
      "name": "whatsapp",
      "date_added": "2025-10-13T10:30:00+00:00"
    },
    {
      "name": "lead-2025",
      "date_added": "2025-10-13T10:30:00+00:00"
    }
  ]
}

Tratamento de Erros

Email já existe

Se o email já está na lista, a API retorna erro 400:

{
  "title": "Member Exists",
  "status": 400,
  "detail": "joao@exemplo.com is already a list member."
}

Solução: Use Members Update ao invés de Add.

Email inválido

{
  "title": "Invalid Resource",
  "status": 400,
  "detail": "Please provide a valid email address."
}

Solução: Valide email antes com EMAIL node.

Boas Práticas

✅ SIM: - Use status "pending" para double opt-in - Sempre valide email antes de adicionar - Use merge fields para personalização - Adicione tags para segmentação - Trate erro de email duplicado - Informe o usuário sobre confirmação

❌ NÃO: - Não adicione sem permissão (LGPD/GDPR) - Não use status "subscribed" sem consentimento - Não ignore validação de email - Não adicione emails comprados - Não force opt-in

Dicas

💡 Double Opt-In: Melhor prática para compliance e qualidade 💡 Merge Fields: Configure campos personalizados no Mailchimp primeiro 💡 Tags: Use para automações baseadas em comportamento 💡 Validação: Sempre valide email antes de enviar à API 💡 LGPD: Guarde evidência de consentimento do usuário

Próximos Passos

→ Members Update - Atualizar dados do assinante → Members Get - Buscar informações do assinante → Campaigns Create - Criar campanha para enviar