Creación de custom nodes en n8n con TypeScript para validar emails

Impulsa tus automatizaciones en n8n con un custom node hecho a tu medida: aprende a construirlo en TypeScript para validar correos con una API externa, configurar sus propiedades, manejar credenciales y definir el enrutamiento por query string. Todo, paso a paso y sin atajos.

¿Qué es un custom node en n8n y cuándo crearlo?

Un custom node es la forma de extender n8n cuando los nodos existentes no alcanzan. Permite conectar con un servicio concreto, aplicar lógica específica o cubrir casos no contemplados. Se escribe en TypeScript y defines todo: qué datos espera, qué devuelve, cómo se comporta y cómo aparece en el editor.

En este caso, se construye un nodo para verificar la validez de un correo usando la API de Emailable. Así, controlas entradas y salidas, asignas credenciales y determinas el formato de la petición.

• Se programa en TypeScript y se integra en el editor de n8n.
• Se configura con ícono propio en formato SVG.
• Usa credenciales para autenticar llamadas a la API externa.
• Envía el email como query string con QS.

¿Cómo preparar el entorno y clonar n8n-nodes-starter?

Primero, clona el repositorio base para nodos: n8n-nodes-starter. Desde el botón Code puedes elegir HTTPS o SSH y clonar con tu editor preferido, por ejemplo IntelliJ o Visual Studio Code usando la opción Get from VCS. Luego instala dependencias.

• Clonar el repositorio con HTTPS o SSH.
• Abrir el proyecto en IntelliJ y usar la terminal integrada.
• Verificar la herramienta de paquetes.

Comandos clave:

pnpm --version
pnpm install

Notas importantes:

• Las nuevas versiones de n8n usan pnpm: es como npm pero más rápido.
• La estructura principal del proyecto incluye las carpetas credentials y nodes. Ahí vivirán tus ficheros.
• Puedes eliminar ejemplos existentes para empezar desde cero.

¿Cómo construir el nodo, las credenciales y el ícono en TypeScript?

Dentro de la carpeta del proyecto, crea los archivos base:

• En nodes: verificar_email.node.ts y verificar_email.node.json.
• En credentials: el archivo de credenciales con sufijo Credentials en plural y en mayúscula.
• Copia tu icono, por ejemplo email.svg, en las carpetas credentials y nodes.

¿Qué importar y cómo nombrar la clase?

Desde la documentación oficial, importa la librería necesaria y crea la clase con el mismo nombre lógico del nodo. Asegúrate de coherencia entre nombres de archivo, clase y propiedades.

import { INodeType, INodeTypeDescription, NodeConnectionType } from 'n8n-workflow';

export class VerificarEmail implements INodeType {
  description: INodeTypeDescription = {
    displayName: 'Verificar email',
    name: 'verificarEmail', // primera letra en minúscula.
    icon: 'file:email.svg',
    group: ['transform'],
    version: 1,
    description: 'Verifica la validez de un correo electrónico usando emailable.com.',
    inputs: [NodeConnectionType.Main],
    outputs: [NodeConnectionType.Main],
    // credentials y requestDefaults se añaden más abajo.
    properties: [],
  };
}

Claves de configuración:

• displayName y name coherentes con el fichero. La propiedad name empieza en minúscula.
• icon apunta a tu SVG: email.svg.
• group como transformación: 'transform'.
• inputs/outputs con NodeConnectionType.Main para una entrada y salida.

¿Cómo declarar credenciales y la base de la API?

Genera tu API key en Emailable y añade el nombre de credencial que coincida con el archivo de credenciales. Define la URL base de la API en la descripción del nodo.

// dentro de description
credentials: [
  {
    name: 'verificarEmailApi',
    required: true,
  },
],

requestDefaults: {
  baseURL: '',
},

Puntos finos:

• El nombre de credencial debe coincidir con el fichero de credenciales.
• La URL base se pega desde el panel de Emailable.

¿Cómo definir la propiedad de entrada y el routing por query string?

El nodo recibe un único valor: la dirección de email. Se define como texto, con un placeholder útil y sin opciones.

// dentro de properties
{
  displayName: 'Dirección de email',
  name: 'email',
  type: 'string',
  placeholder: 'test@domain.com',
  default: '',
  routing: {
    request: {
      qs: {
        email: '={{$value}}',
      },
    },
  },
},

Detalles que marcan la diferencia:

• type: 'string' en lugar de options.
• placeholder para guiar el uso.
• default como cadena vacía.
• routing.request.qs envía el email como query string en la URL.

Conceptos clave y habilidades aplicadas:

• Uso de pnpm para instalar dependencias de forma eficiente.
• Estructura de nodos en n8n: carpetas credentials y nodes.
• Nomenclatura estricta de archivos y clases en TypeScript para evitar errores.
• Importación de n8n-workflow y empleo de NodeConnectionType.Main.
• Creación y referencia de API key en Emailable.
• Definición de propiedades del nodo: displayName, name, icon, group, version, description.
• Enrutamiento declarativo con routing y envío del parámetro por QS.

¿Te gustaría ver una variante que acepte el email por cuerpo en JSON o por header? Comenta qué necesitas automatizar y en qué servicio te gustaría integrarlo.