Conector de SendGrid

Conecta tu cuenta de SendGrid con Brevo a través de Tajo para migrar tu infraestructura de email, sincronizar contactos, transferir datos de campaña y unificar la analítica de engagement entre ambas plataformas.

Resumen

Funcionalidades

• Migración de contactos - Migra los contactos de SendGrid Marketing a Brevo con campos personalizados
• Sincronización de email transaccional - Registra los eventos de email transaccional para un reporting unificado
• Datos de campaña - Sincroniza los datos de rendimiento de Single Send y Automation
• Webhooks de eventos - Reenvía los eventos de email (entregado, abierto, clicado, rebotado) a Brevo
• Sincronización de suppressions - Migra las listas de rebotes, bloqueos y bajas para cumplimiento
• Migración de plantillas - Exporta Dynamic Transactional Templates para usarlas en Brevo
• Verificación de remitente - Sincroniza identidades de remitente verificadas y autenticación de dominio
• Sincronización de estadísticas - Importa estadísticas históricas de engagement como atributos de Brevo

Requisitos previos

Antes de empezar, asegúrate de tener:

1. Una cuenta de SendGrid (Free, Essentials, Pro o Premier)
2. Una clave API de SendGrid con los permisos necesarios
3. Una cuenta de Brevo con acceso a la API
4. Una cuenta de Tajo

Autenticación

Autenticación con clave API

SendGrid usa autenticación con bearer token.

curl https://api.sendgrid.com/v3/marketing/contacts \
  -H "Authorization: Bearer SG.YOUR_API_KEY" \
  -H "Content-Type: application/json"

Crea claves API en SendGrid Settings > API Keys con niveles de permisos específicos:

• Full Access - Acceso completo a la API
• Restricted Access - Control granular de permisos
• Billing Access - Solo operaciones de facturación

Permisos necesarios

Marketing: Full Access
  - Contacts (read)
  - Single Sends (read)
  - Automations (read)
Mail Send: Full Access
  - Mail Send (read)
Stats: Read Access
Suppressions: Read Access
Tracking: Read Access

Configuración

Configuración básica

connectors:
  sendgrid:
    enabled: true
    api_key: "${SENDGRID_API_KEY}"

    # Data sync options
    sync:
      contacts: true
      campaigns: true
      transactional: true
      suppressions: true
      statistics: true

    # List mapping to Brevo
    list_mapping:
      "All Contacts": 60
      "Newsletter": 61
      "Transactional": 62

Asignación de campos

Asocia los campos de contacto de SendGrid con los atributos de contacto de Brevo:

Asignación de campos personalizados

field_mapping:
  # Standard fields
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  phone_number: SMS

  # Location fields
  city: CITY
  state_province_region: STATE
  country: COUNTRY
  postal_code: POSTAL_CODE

  # Engagement metrics
  avg_open_rate: AVG_OPEN_RATE
  avg_click_rate: AVG_CLICK_RATE

  # Custom fields
  custom_fields.company: COMPANY_NAME
  custom_fields.plan: PLAN_TYPE

Endpoints de la API

Marketing Contacts

Email transaccional (Mail Send)

Campañas (Single Sends)

Estadísticas

Suppressions

Eventos

Eventos de email (a través del Event Webhook)

Ejemplos de código

Inicializar el conector

import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Connect SendGrid
await tajo.connectors.connect('sendgrid', {
  apiKey: process.env.SENDGRID_API_KEY
});

Migrar contactos a Brevo

// Full contact migration from SendGrid to Brevo
await tajo.connectors.sync('sendgrid', {
  type: 'full',
  resources: ['contacts', 'suppressions'],
  options: {
    includeCustomFields: true,
    migrateListMemberships: true,
    migrateSuppressions: true
  }
});

// Check migration status
const status = await tajo.connectors.status('sendgrid');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsMigrated: 45000,
//   suppressionsSynced: 3200,
//   listsMapped: 8
// }

Reenviar eventos de email

// Handle SendGrid Event Webhook
app.post('/webhooks/sendgrid', async (req, res) => {
  const signature = req.get('X-Twilio-Email-Event-Webhook-Signature');

  // Verify webhook signature (ECDSA)
  if (!verifySendGridSignature(req.body, signature)) {
    return res.status(401).send('Unauthorized');
  }

  // Process batch of events
  for (const event of req.body) {
    await tajo.connectors.handleWebhook('sendgrid', {
      type: event.event,
      email: event.email,
      timestamp: event.timestamp,
      payload: event
    });
  }

  res.status(200).send('OK');
});

Límites de velocidad

Límites de velocidad de la API de SendGrid:

Resolución de problemas

Problemas habituales

Modo depuración

Activa el registro detallado:

connectors:
  sendgrid:
    debug: true
    log_level: verbose
    log_webhooks: true

Probar la conexión

tajo connectors test sendgrid
# ✓ API connection successful
# ✓ Contacts readable
# ✓ Lists accessible
# ✓ Statistics readable
# ✓ Suppressions accessible

Buenas prácticas

1. Migra primero las suppressions - Asegúrate de que los rebotes, bloqueos y bajas están en Brevo antes de enviar
2. Usa subidas de contactos por lote - Haz PUT de hasta 30.000 contactos por petición para mayor eficiencia
3. Verifica el Event Webhook - Activa los webhooks firmados con verificación ECDSA
4. Asocia los campos personalizados - Crea los atributos correspondientes en Brevo antes de la migración de contactos
5. Sincroniza datos de engagement - Importa estadísticas históricas para la segmentación en Brevo
6. Gestiona las exportaciones asíncronas - Las exportaciones de contactos son asíncronas; haz polling hasta que finalicen

Seguridad

• Autenticación con clave API - Bearer token con niveles de permisos granulares
• Firma del Event Webhook - Verificación de firma ECDSA para los payloads de webhook
• Cifrado TLS - Toda la comunicación con la API se cifra vía HTTPS
• IP Access Management - Restringe el acceso al Dashboard y a la API por IP
• Autenticación de dos factores - 2FA disponible para el acceso a la cuenta

Recursos relacionados

• Documentación de la API de SendGrid
• Guía del Event Webhook de SendGrid
• Conector de Brevo
• Conector de Mailchimp
• Skill de sincronización de clientes