SendGridEmail

El componente SendGridEmail actúa como un puente seguro entre tu flujo de trabajo en nAppAI y el servicio de envío de correos electrónicos SendGrid. Su propósito principal es permitir que automatices la comunicación con tus usuarios o clientes, enviando notificaciones, confirmaciones o alertas basadas en eventos y datos de tus procesos.

Al usar este componente, puedes integrar la potencia de los asistentes de IA y las automatizaciones de nAppAI con la confiabilidad de SendGrid para asegurar que tus correos lleguen a destino.

¿Cómo funciona?

Internamente, este componente funciona como un “gestor de envíos” inteligente. Cuando ejecutas el flujo, el componente realiza los siguientes pasos:

1. Validación: Verifica que todos los datos sean correctos (formato de correo, validez de la clave de API, etc.).
2. Construcción: Prepara la información necesaria en el formato que SendGrid requiere para procesar el correo.
3. Envío: Comunica de forma segura con los servidores de SendGrid a través de su API para entregar el mensaje.
4. Resultado: Te devuelve una respuesta clara indicando si el correo fue enviado correctamente, junto con un identificador único para rastrearlo en caso de necesidad.

Piensa en este componente como el “cartero” de tu automatización: tú le das la dirección y el mensaje, y él se encarga de entregarlo de forma segura y confiable.

Conexión y Credenciales

Este componente requiere configurar previamente una credencial en el panel de Nappai para poder interactuar con el servicio SendGrid:

1. Dirígete a la sección de Credenciales en tu panel de Nappai.
2. Crea una nueva credencial del tipo sendgrid API y guarda la sendgrid Api Key que obtendrás en tu cuenta de SendGrid.
3. En tu flujo de trabajo, selecciona la credencial guardada en el campo de entrada Credential de este componente.

Nota importante: Nunca compartas tu clave de API manualmente. Siempre confígate en el gestor de credenciales seguro de nAppAI para proteger tu información.

Operaciones

Este componente ofrece varias operaciones que puedes seleccionar según lo que necesites hacer. Solo puedes usar una operación a la vez:

• Send Email: Permite enviar un correo electrónico estándar definiendo manualmente el cuerpo del mensaje y el asunto. Ideal para notificaciones simples o personalizados.
• Send Email with Template: Permite enviar correos utilizando una plantilla predefinida de SendGrid. Es útil cuando quieres mantener un diseño consistente y enviar datos dinámicos (como nombres, montos, etc.) dentro del diseño de la plantilla.

Para usar el componente, primero selecciona la operación que necesitas en el campo “Operation” (Operación).

Entradas

Modo de Mapeo (Mapping Mode)

Este componente cuenta con un modo especial llamado “Mapping Mode” (Modo de Mapeo). Cuando activas este modo mediante el interruptor, se habilita una entrada adicional llamada “Mapping Data” y cada campo de entrada te ofrece tres formas diferentes de proporcionar datos:

• Fixed (Fijo): Escribes el valor directamente en el campo.
• Mapped (Mapeado): Conectas la salida de otro componente para usar su resultado como valor.
• Javascript: Escribes código Javascript para calcular el valor dinámicamente.

Esta flexibilidad te permite crear flujos de trabajo más dinámicos y conectados, procesando múltiples registros o adaptando los datos según tus necesidades.

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente. Cada campo puede estar visible en diferentes operaciones:

• Operation: Selección para elegir la acción a realizar (Enviar correo estándar o con plantilla).
  • Visible en: Send Email, Send Email with Template
• Recipient Email: Dirección de correo electrónico del destinatario. Debe ser un formato válido.
  • Visible en: Send Email, Send Email with Template
• Sender Email: Dirección de correo verificada que actuará como el remitente. Debe estar registrada y verificada en tu cuenta de SendGrid para evitar rechazos por spam.
  • Visible en: Send Email, Send Email with Template
• Body: Contenido del mensaje en formato de texto plano. Se utiliza para redactar el cuerpo del correo en operaciones estándar.
  • Visible en: Send Email
• Subject: Línea de asunto del correo electrónico que verá el destinatario en su bandeja de entrada.
  • Visible en: Send Email
• Template ID: Identificador único de la plantilla configurada en SendGrid. Necesario para usar la operación de plantillas.
  • Visible en: Send Email with Template
• Template Data (JSON): Datos dinámicos en formato JSON que se inyectarán en la plantilla. Ejemplo: {"name": "Juan", "order": "12345"}. Dejar vacío si la plantilla no tiene variables.
  • Visible en: Send Email with Template
• Tool Name: Nombre de la herramienta que se mostrará al asistente de IA cuando seleccione este componente. Útil si el flujo es gestionado por un agente.
  • Visible en: Send Email, Send Email with Template
• Tool Description: Descripción detallada que ayuda al agente de IA a entender cuándo y cómo usar esta herramienta efectivamente.
  • Visible en: Send Email, Send Email with Template
• Tools arguments metadata: Metadata que define los argumentos para la integración de herramientas.
  • Visible en: Send Email, Send Email with Template

Salidas

El componente produce resultados estructurados que puedes utilizar para continuar tu flujo de trabajo, tomar decisiones condicionales o registrar información en otros sistemas.

• Data: Contiene el estado de la operación, un mensaje de identificación único para rastreo y posibles detalles de error en caso de fallo.
• Tool: Permite exponer el componente como una herramienta para que los asistentes de IA lo utilicen dentro de sus razonamientos.

Ejemplo de Respuesta JSON

Al ejecutarse con éxito, el componente devuelve una estructura similar a esta en su salida Data: json { “success”: true, “message_id”: “d1c3f4e5-a6b7-8c9d-0e1f-2a3b4c5d6e7f”, “error”: null }

• success: true indica que el correo fue aceptado por SendGrid y está en proceso de envío. false indica un fallo.
• message_id: Identificador único del mensaje. Útil para auditar envíos o consultar métricas de entrega en SendGrid.
• error: Mensaje descriptivo si hubo un error (ej. formato inválido, credenciales incorrectas). Será null si todo sale bien.

Conectividad

Este componente suele conectarse lógicamente después de componentes que procesan datos o activan flujos (como Triggers, Database Selectors o Webhooks).

• Conexión típica: Recibe datos de entrada (como una lista de correos o un nombre) y envía la salida a componentes de Notificación, Base de Datos (para registrar el envío) o a lógicos de Condicional para verificar si el correo se envió correctamente.
• Flujo recomendado: Trigger -> Extracción de Datos -> SendGridEmail -> Registro de Salida.

Ejemplo de Uso

Escenario: Confirmación de pedido en una tienda online.

1. Trigger: Se activa cuando llega un nuevo pedido.
2. Extractor de Datos: Obtiene el nombre del cliente y el correo electrónico.
3. SendGridEmail:
   • Operation: Send Email.
   • Recipient Email: Mapeado desde el extractor (cliente.email).
   • Sender Email: noreply@miempresa.com (Fijo).
   • Subject: “Confirmación de tu pedido #1234”.
   • Body: “Hola {nombre}, tu pedido ha sido recibido…”
4. Resultado: El componente devuelve success: true y el flujo continúa guardando la factura en la base de datos.

Consejo: Si usas el Mapping Mode, puedes enviar correos personalizados a múltiples destinatarios conectando una lista de datos a la entrada de mapeo.

Notas Importantes

🔒 Secure API Key Storage 🟴 high Never expose the API key in logs or code. Use encrypted secrets management to protect your credentials.

⚠️ Component in Development Mode 🟡 medium This component is marked as in development and may contain bugs or missing features. Use with caution and test thoroughly before production deployment.

📋 SendGrid API Key Required 🟴 high To send emails, you must provide a valid SendGrid API key. Store it securely in the platform’s credential store.

💡 Use Verified Sender Domains 🟢 low For better deliverability, verify your sender domain in SendGrid and use that email address as the ‘From’ address.

⚙️ Set Email Parameters Correctly 🟡 medium Ensure the component inputs include valid recipient, subject, and body fields. Incorrect or missing fields will result in email rejection.

ℹ️ Check Success Output 🟢 low The component returns a success flag and message in its output. Handle failures by inspecting the output and retrying or logging errors.

Consejos y Mejores Prácticas

• Utiliza el Mapping Mode cuando necesites procesar múltiples registros o cuando los datos de destino provengan de otros nodos del flujo.
• Verifica siempre que el correo del remitente (Sender Email) esté validado en SendGrid para evitar que tus correos caigan en spam.
• En operaciones con plantilla, asegúrate de que el formato JSON de Template Data coincida exactamente con las variables esperadas por tu plantilla.
• Revisa el campo success en la salida para manejar errores en tus flujos (por ejemplo, enviando una alerta si el envío falla).
• Si estás en fase de pruebas, ten en cuenta el modo de desarrollo y realiza validaciones exhaustivas antes de llevar el flujo a producción.

Consideraciones de Seguridad

• Protección de Credenciales: La seguridad es crítica. Nunca escribas tu API Key de SendGrid en textos o notas del componente. Únicamente utilízala a través del campo Credential vinculado a una credencial segura.
• Gestión de Errores: En flujos automatizados de alto volumen, considera agregar lógica de manejo de errores basada en la salida del componente para evitar cascadas de fallos si SendGrid reporta limitaciones de envío.
• Volumen de Envíos: Familiarízate con los límites de tu cuenta de SendGrid (sandbox vs. producción) para asegurar que tu automatización respete las políticas de uso del servicio.