---
title: "Connettore Brevo"
description: "Guida completa all'integrazione di Brevo per sincronizzare contatti, email transazionali, SMS, campagne WhatsApp e marketing automation con Tajo."
url: https://tajo.io/it/docs/connectors/marketing/brevo/
markdown: https://tajo.io/it/docs/connectors/marketing/brevo.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 Brevo

Stato del connettore: Attivo Verificato. Tajo esegue oggi questo connettore.

| 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 Brevo a Tajo per una gestione unificata dei contatti, messaggistica transazionale su email, SMS e WhatsApp e marketing automation completa.

## Panoramica

| Proprietà | Valore |
| --- | --- |
| **Piattaforma** | Brevo |
| **Categoria** | Marketing |
| **Complessità di setup** | Facile |
| **Integrazione ufficiale** | Sì |
| **Dati sincronizzati** | Contatti, Campagne, Messaggi transazionali, Eventi, eCommerce |
| **API Base URL** | `https://api.brevo.com/v3` |

## Funzionalità

- **Messaggistica multi-canale** - Invia email transazionali, SMS e WhatsApp da un’API unificata
- **Gestione contatti** - Crea, aggiorna e segmenta i contatti con attributi personalizzati
- **Campagne marketing** - Crea e invia campagne email in modo programmatico
- **Tracciamento eventi** - Traccia eventi personalizzati e attività del sito tramite il Brevo Tracker
- **Sync eCommerce** - Sincronizza prodotti, ordini e dati del carrello per campagne personalizzate
- **Programmi di loyalty** - Gestisci iscrizioni alla loyalty, punti e dati dei membri
- **Supporto webhook** - Notifiche di eventi in tempo reale per eventi transazionali, marketing e CRM
- **Conversations** - Integrazione del widget di live chat e gestione programmatica dei messaggi

## Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un account Brevo (piano Free, Starter, Business o Enterprise)
2. Una chiave API generata da Brevo Settings > API Keys
3. Un account Tajo con accesso API
4. Dominio mittente verificato per l’invio email

## Autenticazione

Brevo supporta due metodi di autenticazione:

### Autenticazione con chiave API (consigliata)

Includi la tua chiave API nell’header `api-key` per ogni richiesta. Ideale per integrazioni dirette e comunicazione server-to-server.

```bash
curl -X GET "https://api.brevo.com/v3/account" \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### Autenticazione OAuth 2.0

Usa OAuth 2.0 per integrazioni private all’interno di un’organizzazione che richiedono accesso delegato e permessi specifici per utente. OAuth fornisce un sistema basato su token con periodi di validità definiti.

Disponibilità OAuth

OAuth è attualmente disponibile solo per integrazioni private all’interno di un’organizzazione. Le integrazioni OAuth non sono pensate per la distribuzione pubblica o la pubblicazione su marketplace.

## Configurazione

### Setup di base

```yaml
connectors:
  brevo:
    enabled: true
    api_key: "${BREVO_API_KEY}"
    api_version: "v3"

    # Data sync options
    sync:
      contacts: true
      campaigns: true
      transactional: true
      events: true
      ecommerce: true

    # List assignment
    lists:
      all_customers: 5
      newsletter: 6
      buyers: 7
```

### Mappatura dei campi

Mappa i tuoi campi dati agli attributi di contatto Brevo:

#### Mappature predefinite

| Parameter | Type | Description |
| --- | --- | --- |
| `email` required | string | Indirizzo email del contatto (identificatore univoco) |
| `FIRSTNAME` optional | string | Attributo nome del contatto |
| `LASTNAME` optional | string | Attributo cognome del contatto |
| `SMS` optional | string | Numero di telefono per messaggistica SMS e WhatsApp |
| `OPT_IN` optional | boolean | Stato del consenso opt-in marketing |
| `ORDER_COUNT` optional | integer | Numero totale di ordini effettuati |
| `TOTAL_REVENUE` optional | number | Ricavo lifetime dal contatto |
| `LOYALTY_POINTS` optional | integer | Saldo attuale dei punti del programma loyalty |

#### Mappatura attributi personalizzati

```yaml
field_mapping:
  # Standard fields
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  phone: SMS

  # Marketing fields
  opt_in: OPT_IN
  signup_source: SIGNUP_SOURCE
  preferred_language: LANGUAGE

  # eCommerce metrics
  orders_count: ORDER_COUNT
  total_spent: TOTAL_REVENUE
  last_order_date: LAST_ORDER_DATE

  # Loyalty fields
  loyalty_tier: VIP_TIER
  loyalty_points: LOYALTY_POINTS
```

## Endpoint API

### Endpoint principali

| Metodo | Endpoint | Descrizione |
| --- | --- | --- |
| `POST` | `/v3/smtp/email` | Invia email transazionale |
| `POST` | `/v3/transactionalSMS/send` | Invia SMS transazionale |
| `POST` | `/v3/whatsapp/sendMessage` | Invia WhatsApp transazionale |
| `POST` | `/v3/contacts` | Crea un contatto |
| `PUT` | `/v3/contacts/{email}` | Aggiorna un contatto |
| `GET` | `/v3/contacts/{identifier}` | Ottieni i dettagli di un contatto |
| `POST` | `/v3/contacts/import` | Importa contatti in blocco |

### Endpoint eCommerce

| Metodo | Endpoint | Descrizione |
| --- | --- | --- |
| `POST` | `/v3/orders/status` | Crea o aggiorna lo stato di un ordine |
| `POST` | `/v3/products` | Crea o aggiorna prodotti |
| `POST` | `/v3/categories` | Crea o aggiorna categorie di prodotti |
| `POST` | `/v3/events` | Traccia eventi personalizzati |

### Endpoint campagne

| Metodo | Endpoint | Descrizione |
| --- | --- | --- |
| `POST` | `/v3/emailCampaigns` | Crea una campagna email |
| `POST` | `/v3/emailCampaigns/{id}/sendNow` | Invia una campagna immediatamente |
| `GET` | `/v3/emailCampaigns` | Elenca tutte le campagne email |
| `GET` | `/v3/smtp/statistics/events` | Ottieni statistiche degli eventi email |

## Eventi

### Eventi transazionali

| Evento | Trigger | Caso d’uso |
| --- | --- | --- |
| `delivered` | Email recapitata in inbox | Conferma di consegna |
| `opened` | Email aperta dal destinatario | Tracciamento engagement |
| `clicked` | Link cliccato in email | Tracciamento click-through |
| `bounced` | Email respinta | Igiene della lista |
| `spam` | Marcata come spam | Monitoraggio compliance |
| `unsubscribed` | Contatto disiscritto | Gestione preferenze |

### Eventi eCommerce

| Evento | Trigger | Caso d’uso |
| --- | --- | --- |
| `order_completed` | Ordine effettuato con successo | Flussi post-acquisto |
| `cart_updated` | Contenuto del carrello modificato | Tracciamento carrello abbandonato |
| `cart_deleted` | Carrello svuotato o scaduto | Recupero del carrello |
| `product_viewed` | Pagina prodotto visitata | Browse abandonment |

## 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 Brevo account
await tajo.connectors.connect('brevo', {
  apiKey: process.env.BREVO_API_KEY
});
```

### Invia un’email transazionale

```javascript
// Send a transactional email via Brevo
await tajo.brevo.sendTransactionalEmail({
  to: [{ email: 'customer@example.com', name: 'John Doe' }],
  templateId: 12,
  params: {
    ORDER_ID: '12345',
    ORDER_TOTAL: '$59.99',
    DELIVERY_DATE: '2024-02-15'
  }
});
```

### Sincronizza i contatti

```javascript
// Bulk import contacts to Brevo
await tajo.connectors.sync('brevo', {
  type: 'full',
  resources: ['contacts'],
  options: {
    listIds: [5, 6],
    updateExisting: true,
    emptyContactsAttributes: false
  }
});

// Check sync status
const status = await tajo.connectors.status('brevo');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsSynced: 25400,
//   campaignsSent: 142,
//   eventsTracked: 89320
// }
```

### Traccia eventi personalizzati

```javascript
// Track a custom event for a contact
await tajo.brevo.trackEvent({
  email: 'customer@example.com',
  event: 'product_purchased',
  eventdata: {
    id: 'txn_98765',
    data: {
      product_name: 'Premium Widget',
      price: 49.99,
      currency: 'USD'
    }
  }
});
```

## Limiti di velocità

Brevo applica limiti di velocità su tre livelli in base al tuo piano:

| Endpoint | Free/Starter | Professional | Enterprise |
| --- | --- | --- | --- |
| `POST /v3/smtp/email` | 1.000 RPS | 2.000 RPS | 6.000 RPS |
| `POST /v3/transactionalSMS/send` | 150 RPS | 200 RPS | 250 RPS |
| `POST /v3/events` | 10 RPS | 20 RPS | 60 RPS |
| `/v3/contacts/*` | 10 RPS | 20 RPS | 60 RPS |
| Tutti gli altri endpoint | 100 RPH | 200 RPH | 600 RPH |

Risposta limite di velocità

Quando superi un limite di velocità, l’API restituisce uno status `429 Too Many Requests`. Monitora gli header dei limiti di velocità nelle risposte per tracciare il tuo utilizzo.

## Risoluzione dei problemi

### Problemi comuni

| Problema | Causa | Soluzione |
| --- | --- | --- |
| 401 Unauthorized | Chiave API non valida | Rigenera la chiave API in Brevo Settings |
| Contatto non creato | Campo email mancante | Assicurati che l’email sia fornita per tutti i contatti |
| Email non recapitata | Dominio mittente non verificato | Verifica il dominio nelle impostazioni Senders di Brevo |
| Webhook non ricevuto | URL errato o errore del server | Controlla l’accessibilità dell’URL del webhook e i log |
| SMS non inviato | Formato telefono non valido | Usa il formato internazionale con prefisso paese |

### Modalità debug

Abilita il logging dettagliato:

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

### Testa la connessione

```bash
tajo connectors test brevo
# ✓ API connection successful
# ✓ Contacts API accessible
# ✓ Transactional email ready
# ✓ SMS sending configured
# ✓ Webhooks registered
```

## Best practice

1. **Usa la rotazione delle chiavi API** - Ruota periodicamente le chiavi API per sicurezza
2. **Implementa la verifica dei webhook** - Convalida le firme dei webhook con autenticazione username/password
3. **Importazioni di contatti in batch** - Usa l’import in blocco per dataset di grandi dimensioni invece di chiamate API individuali
4. **Monitora i limiti di velocità** - Controlla gli header dei limiti di velocità per evitare errori 429
5. **Usa il tracciamento eventi** - Implementa il Brevo Tracker per dati comportamentali completi sui clienti
6. **Imposta correttamente l’autenticazione del mittente** - Configura SPF, DKIM e DMARC per una deliverability ottimale

## Sicurezza

- **Autenticazione con chiave API** - Accesso basato su token segreto tramite header `api-key`
- **OAuth 2.0** - Accesso delegato basato su token per integrazioni private
- **Verifica webhook** - Autenticazione username e password per chiamate webhook sicure
- **Cifratura TLS** - Tutte le comunicazioni API cifrate in transito
- **IP whitelisting** - Restrizioni IP opzionali disponibili sui piani Enterprise

## Risorse correlate

- [Documentazione API Brevo](https://developers.brevo.com/docs/getting-started)
- [Guida autenticazione Brevo](https://developers.brevo.com/docs/authentication-schemes)
- [Limiti di velocità Brevo](https://developers.brevo.com/docs/api-limits)
- [Connettore Shopify](https://tajo.io/it/docs/connectors/ecommerce/shopify)
- [Skill Customer Sync](https://tajo.io/it/docs/skills/data-sync/customer-sync)
- [API Contatti Brevo](https://tajo.io/it/docs/contact-management)