Crear un custom node en n8n te permite extender la herramienta cuando los nodos existentes no cubren tu caso de uso. Aquí aprendes a construir uno desde cero en TypeScript para verificar la validez de un correo electrónico con una API externa.

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

Un custom node es un nodo que tú mismo programas para ampliar n8n a tu medida. Lo escribes en TypeScript y defines qué datos espera, qué devuelve, cómo se comporta y hasta cómo aparece en el editor visual.

¿Cuándo conviene crear uno? Cuando necesitas conectar un servicio que no existe en el catálogo, aplicar una lógica muy específica o resolver algo que los nodos estándar no contemplan. En este recorrido vas a construir un nodo llamado verificarEmail que consulta la API de emailable.com para validar correos.

¿Para qué sirve un custom node en n8n? Sirve para integrar servicios o lógica que no están disponibles en los nodos por defecto. Lo programas en TypeScript y queda disponible en tu editor como cualquier otro nodo nativo.

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

Todo arranca clonando el repositorio oficial n8n-nodes-starter, que ya trae la estructura base lista para trabajar [00:38].

Los pasos iniciales son directos:

• Abrir el repositorio en GitHub y copiar la URL desde el botón Code (HTTPS o SSH).
• Clonar el proyecto en tu IDE preferido, ya sea IntelliJ, Visual Studio Code u otro.
• Verificar que tienes n8n instalado globalmente con npm install -g.
• Instalar pnpm, el gestor de paquetes que reemplazó a npm en las versiones recientes de n8n por ser mucho más rápido [01:49].
• Confirmar la instalación ejecutando pnpm version y luego pnpm install para bajar las dependencias.

¿Qué carpetas trae el repositorio starter?

Dentro del proyecto encontrarás dos carpetas clave: credentials y nodes. La carpeta nodes es donde vive el código de tu nodo, y credentials guarda la configuración de autenticación que ese nodo necesita [02:42].

El starter incluye ejemplos como example-node y httpbin. Bórralos para empezar limpio y crea tus propios archivos.

¿Cómo estructurar los archivos de un custom node?

La nomenclatura es estricta: si los nombres no coinciden con la convención, el nodo no carga. Crea estos archivos respetando mayúsculas y extensiones [03:24]:

• verificarEmail.node.ts dentro de la carpeta nodes.
• verificarEmail.node.json como manifiesto del nodo.
• verificarEmailApi.credentials.ts dentro de credentials, con Credentials en mayúscula y plural.

También copia un icono SVG (en este caso email.svg) tanto en nodes como en credentials para que aparezca en el editor [04:04].

¿Cómo definir la descripción y propiedades del nodo en TypeScript?

La documentación oficial de n8n incluye un tutorial llamado Build a declarative-style node que sirve de plantilla. Desde ahí copias el esqueleto y lo adaptas [04:36].

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

Lo primero es importar la librería n8n-workflow, que trae los tipos necesarios. Luego defines la clase con el mismo nombre del archivo, sin el sufijo .node. En este caso, la clase se llama verificarEmail [05:14].

¿Qué campos lleva el bloque description?

El objeto description configura cómo se ve y se comporta el nodo. Estos son los campos que ajustas:

• displayName: el nombre visible, por ejemplo verificar email.
• name: el identificador interno en camelCase, empezando en minúscula.
• icon: el archivo SVG, en este caso email.svg.
• group: la categoría del nodo, que puede ser trigger, transformation o transform.
• description: una explicación breve, como verificar la validez de un correo electrónico usando emailable.com.
• inputs y outputs: aquí va un detalle importante. La documentación dice main, pero desde la migración a pnpm hay que usar la clase NodeConnectionType.Main [06:55].
• credentials: el nombre debe coincidir con el archivo de credenciales, por ejemplo verificarEmailApi.

¿Por qué falla si pongo main como string en inputs? Porque las versiones nuevas de n8n con pnpm exigen usar la enumeración NodeConnectionType.Main importada desde n8n-workflow. El string plano ya no es válido.

¿Cómo conectar la API de emailable al nodo?

Para probar el nodo necesitas una API key real. En emailable.com creas una cuenta, generas una key (puede llamarse N8N-PLAZI), la marcas como live para validar correos reales y copias la URL del endpoint que entrega la plataforma [08:13].

Esa URL se pega tal cual en la configuración de la petición dentro del nodo.

¿Cómo configurar la propiedad email con routing?

Las propiedades son los campos que el usuario llena en el editor visual. Para el correo a verificar, defines una propiedad con estas claves [09:36]:

• displayName: Dirección de email, con mayúsculas iniciales para evitar errores.
• name: email, el identificador del recurso.
• type: string, porque un correo es texto.
• placeholder: test@domain.com, el texto guía cuando el campo está vacío.
• default: una cadena vacía como valor inicial.
• routing: el atributo que indica cómo enviar el dato a la API.

El routing con tipo qs significa query string: el email viaja como parte de la URL de la petición, no en el body ni en headers [10:52]. Es la forma que exige emailable para recibir el correo a validar.

¿Qué es un query string en una API? Es la porción de la URL después del signo de interrogación que envía parámetros al servidor, como ?email=test@domain.com. n8n lo configura automáticamente con routing: { request: { qs: ... } }.

¿Qué sigue después de definir el nodo?

Con el archivo verificarEmail.node.ts listo, ya tienes la estructura base funcionando. Falta configurar dos piezas para que el nodo sea utilizable de punta a punta:

• El archivo de credenciales que guarda la API key del usuario.
• El manifiesto JSON que registra el nodo dentro de n8n.

¿Tú qué API conectarías primero con un custom node propio? Cuéntame en los comentarios qué integración te gustaría construir.