---
title: "Connettore SendGrid"
description: "Guida completa all'integrazione di SendGrid per sincronizzare contatti, email transazionali, campagne marketing ed eventi di engagement con Brevo tramite Tajo."
url: https://tajo.io/it/docs/connectors/marketing/sendgrid/
markdown: https://tajo.io/it/docs/connectors/marketing/sendgrid.md
lang: it-IT
robots: noindex
---

Richiedi l’accesso anticipato

Inserisci il tuo nome e indirizzo email aziendale. Ti invieremo un link per confermare la richiesta di accesso a Tajo.

# Connettore SendGrid

Stato del connettore: In corso In costruzione. Non ancora verificato.

| Campo di origine | Campo di destinazione | Valore di esempio |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Collega il tuo account SendGrid a Brevo tramite Tajo per la migrazione dell’infrastruttura email, sincronizzazione dei contatti, trasferimento dei dati delle campagne e analytics di engagement unificate tra entrambe le piattaforme.

## Panoramica

| Proprietà | Valore |
| --- | --- |
| **Piattaforma** | SendGrid (Twilio) |
| **Categoria** | Marketing |
| **Complessità di setup** | Facile |
| **Integrazione ufficiale** | Sì |
| **Dati sincronizzati** | Contatti, Campagne, Email transazionale, Eventi |
| **API Base URL** | `https://api.sendgrid.com/v3` |

## Funzionalità

- **Migrazione contatti** - Migra i contatti SendGrid Marketing a Brevo con campi personalizzati
- **Sync email transazionali** - Traccia gli eventi delle email transazionali per una reportistica unificata
- **Dati di campagna** - Sincronizza i dati di performance delle campagne Single Send e Automation
- **Webhook eventi** - Inoltra gli eventi email (delivered, opened, clicked, bounced) a Brevo
- **Sync delle suppression** - Migra le liste di bounce, block e disiscrizioni per la conformità
- **Migrazione template** - Esporta i Dynamic Transactional Template per l’uso in Brevo
- **Verifica mittente** - Sincronizza identità mittente verificate e autenticazione del dominio
- **Sync delle statistiche** - Importa statistiche di engagement storiche negli attributi Brevo

## Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un account SendGrid (Free, Essentials, Pro o Premier)
2. Una chiave API SendGrid con i permessi richiesti
3. Un account Brevo con accesso API
4. Un account Tajo

## Autenticazione

### Autenticazione con chiave API

SendGrid utilizza l’autenticazione bearer token.

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

Crea le chiavi API in SendGrid Settings > API Keys con livelli di permesso specifici:

- **Full Access** - Accesso API completo
- **Restricted Access** - Controllo dei permessi granulare
- **Billing Access** - Solo operazioni di billing

#### Permessi richiesti

```
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
```

Sicurezza della chiave API

Le chiavi API SendGrid vengono mostrate solo una volta alla creazione. Conservale in modo sicuro. Se vengono perse, devi crearne una nuova.

## Configurazione

### Setup di base

```yaml
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
```

### Mappatura dei campi

Mappa i campi di contatto SendGrid agli attributi di contatto Brevo:

#### Mappature predefinite

| Parameter | Type | Description |
| --- | --- | --- |
| `email` required | string | Indirizzo email del contatto (identificatore univoco) |
| `first_name` optional | string | Mappato all'attributo FIRSTNAME |
| `last_name` optional | string | Mappato all'attributo LASTNAME |
| `phone_number` optional | string | Mappato all'attributo SMS |
| `city` optional | string | Città del contatto |
| `country` optional | string | Paese del contatto |
| `custom_fields` optional | object | Coppie chiave-valore dei campi personalizzati |
| `list_ids` optional | array | Appartenenze alle liste SendGrid |

#### Mappatura dei campi personalizzati

```yaml
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
```

## Endpoint API

### Marketing Contacts

| Metodo | Endpoint | Descrizione |
| --- | --- | --- |
| `PUT` | `/v3/marketing/contacts` | Aggiungi o aggiorna contatti |
| `POST` | `/v3/marketing/contacts/search` | Cerca contatti |
| `GET` | `/v3/marketing/contacts/count` | Ottieni il conteggio dei contatti |
| `POST` | `/v3/marketing/contacts/exports` | Esporta contatti |
| `DELETE` | `/v3/marketing/contacts` | Elimina contatti |
| `GET` | `/v3/marketing/lists` | Elenca tutte le liste contatti |

### Email transazionale (Mail Send)

| Metodo | Endpoint | Descrizione |
| --- | --- | --- |
| `POST` | `/v3/mail/send` | Invia un’email |
| `GET` | `/v3/templates` | Elenca i Dynamic Template |
| `GET` | `/v3/templates/{id}` | Ottieni i dettagli di un template |

### Campagne (Single Send)

| Metodo | Endpoint | Descrizione |
| --- | --- | --- |
| `GET` | `/v3/marketing/singlesends` | Elenca i Single Send |
| `GET` | `/v3/marketing/singlesends/{id}` | Ottieni i dettagli di un Single Send |
| `GET` | `/v3/marketing/automations` | Elenca le Automation |

### Statistiche

| Metodo | Endpoint | Descrizione |
| --- | --- | --- |
| `GET` | `/v3/stats` | Ottieni statistiche email globali |
| `GET` | `/v3/categories/stats` | Ottieni statistiche per categoria |
| `GET` | `/v3/marketing/stats/singlesends` | Ottieni statistiche dei Single Send |

### Suppression

| Metodo | Endpoint | Descrizione |
| --- | --- | --- |
| `GET` | `/v3/suppression/bounces` | Elenca le email in bounce |
| `GET` | `/v3/suppression/blocks` | Elenca le email bloccate |
| `GET` | `/v3/suppression/spam_reports` | Elenca i report di spam |
| `GET` | `/v3/suppression/unsubscribes` | Elenca le disiscrizioni globali |

## Eventi

### Eventi email (tramite Event Webhook)

| Evento | Trigger | Caso d’uso |
| --- | --- | --- |
| `processed` | Email accettata da SendGrid | Conferma di invio |
| `delivered` | Email recapitata al destinatario | Tracciamento consegna |
| `open` | Email aperta | Engagement scoring |
| `click` | Link cliccato | Tracciamento interesse |
| `bounce` | Email respinta | Igiene della lista |
| `dropped` | Email soppressa | Revisione di compliance |
| `deferred` | Consegna posticipata | Monitoraggio retry |
| `spam_report` | Marcata come spam | Gestione reputazione |
| `unsubscribe` | Disiscritto via link | Sync delle preferenze |

## Esempi di codice

### Inizializza il connettore

```javascript
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
});
```

### Migra i contatti su Brevo

```javascript
// 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
// }
```

### Inoltra eventi email

```javascript
// 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');
});
```

## Limiti di velocità

Limiti di velocità API SendGrid:

| Endpoint | Limite | Dettagli |
| --- | --- | --- |
| Mail Send (`/v3/mail/send`) | Dipendente dal piano | Free: 100/giorno, Essentials: in base al piano |
| Marketing Contacts PUT | 3 richieste/secondo | Batch fino a 30.000 contatti |
| Marketing Contacts Search | 50 richieste/secondo | Per chiave API |
| API generale | 1.000 richieste/secondo | Per chiave API |
| Event Webhook | Consegna in batch | Fino a 1.000 eventi per POST |

Limiti Mail Send

I limiti di Mail Send dipendono dal tuo piano SendGrid. Gli account gratuiti sono limitati a 100 email/giorno. Controlla i dettagli del tuo piano per i limiti esatti di invio.

## Risoluzione dei problemi

### Problemi comuni

| Problema | Causa | Soluzione |
| --- | --- | --- |
| 401 Unauthorized | Chiave API non valida | Verifica la chiave API in SendGrid Settings |
| 403 Forbidden | Permessi della chiave API insufficienti | Crea una nuova chiave con gli scope richiesti |
| Esportazione contatti pendente | Elaborazione di dataset grande | Esegui polling dell’endpoint di stato dell’export fino al completamento |
| Sync delle suppression incompleta | Paginazione richiesta | Implementa la paginazione con il parametro offset |
| Event webhook non ricevuto | URL non verificato | Completa la verifica dell’URL del webhook in SendGrid |

### Modalità debug

Abilita il logging dettagliato:

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

### Testa la connessione

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

## Best practice

1. **Migra prima le suppression** - Assicurati che bounce, block e disiscrizioni siano in Brevo prima dell’invio
2. **Usa upload contatti in batch** - PUT fino a 30.000 contatti per richiesta per efficienza
3. **Verifica l’Event Webhook** - Abilita i webhook firmati con verifica ECDSA
4. **Mappa i campi personalizzati** - Crea attributi Brevo corrispondenti prima della migrazione contatti
5. **Sincronizza i dati di engagement** - Importa statistiche storiche per la segmentazione in Brevo
6. **Gestisci le esportazioni asincrone** - Le esportazioni di contatti sono asincrone; esegui polling per il completamento

## Sicurezza

- **Autenticazione con chiave API** - Bearer token con livelli di permesso granulari
- **Firma Event Webhook** - Verifica firma ECDSA per i payload webhook
- **Cifratura TLS** - Tutte le comunicazioni API cifrate via HTTPS
- **IP Access Management** - Limita l’accesso alla Dashboard e all’API per IP
- **Autenticazione a due fattori** - 2FA disponibile per l’accesso all’account

## Risorse correlate

- [Documentazione API SendGrid](https://docs.sendgrid.com/api-reference)
- [Guida Event Webhook SendGrid](https://docs.sendgrid.com/for-developers/tracking-events/event)
- [Connettore Brevo](https://tajo.io/it/docs/connectors/marketing/brevo)
- [Connettore Mailchimp](https://tajo.io/it/docs/connectors/marketing/mailchimp)
- [Skill Customer Sync](https://tajo.io/it/docs/skills/data-sync/customer-sync)