Contatti: Crea, Importa e Status

I contatti sono i destinatari delle tue email. Creali individualmente, importali in massa da CSV, gestisci il loro status e traccia rimbalzi/reclami.

Crea un Contatto

Crea un singolo contatto.

cURL

curl -X POST https://api.tratto.email/v1/contacts \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email":"[email protected]",
    "firstName":"Alice",
    "lastName":"Smith",
    "status":"subscribed",
    "tags":["vip","newsletter"],
    "customFields":{"plan":"pro","signupDate":"2025-01-01"}
  }'

Risposta: la creazione restituisce solo l'id.

{
  "data": {
    "id": "cont_abc123"
  }
}

Elenca i Contatti

Recupera tutti i contatti con filtraggio opzionale.

cURL

curl "https://api.tratto.email/v1/contacts?status=subscribed&limit=50" \
  -H "Authorization: Bearer tratto_live_..."

Parametri di Query:

• q: Ricerca per prefisso dell'email, case-insensitive. Combinabile solo con status: con audienceId o tag restituisce 422
• status: Filtra per status (subscribed, unsubscribed, bounced, complained)
• audienceId: Solo i contatti di quell'audience
• tag: Solo i contatti con quel tag
• limit: Max risultati per pagina (default 50, max 100)
• after: Cursor per paginazione

Risposta:

{
  "data": [
    {
      "id": "cont_abc123",
      "email": "[email protected]",
      "firstName": "Alice",
      "lastName": "Smith",
      "status": "subscribed",
      "trackingOptOut": false,
      "tags": ["vip"],
      "customFields": { "plan": "pro" },
      "createdAt": "2025-06-30T12:00:00Z"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "Y3Vyc29yOnZhbHVl",
    "total": 1284
  }
}

pagination.total è il numero di contatti che soddisfano i filtri, non solo quelli della pagina. trackingOptOut indica se il destinatario ha chiesto di non essere tracciato — vedi Privacy.

Aggiorna un Contatto

Aggiorna i dettagli di un contatto (status, tag, campi personalizzati).

cURL

curl -X PATCH https://api.tratto.email/v1/contacts/cont_abc123 \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status":"unsubscribed",
    "tags":["unsubscribed"],
    "customFields":{"unsubscribedAt":"2025-06-30T12:00:00Z"}
  }'

customFields sostituisce l'intero oggetto: non viene fuso campo per campo.

Valori dello Status del Contatto

Auto-aggiornamenti:

• Quando un'email rimbalza → status diventa bounced
• Quando un contatto clicca annulla iscrizione → status diventa unsubscribed
• Quando un'email è segnalata → status diventa complained

Tag

Usa i tag per organizzare i contatti in gruppi logici:

• vip: Clienti di alto valore
• newsletter: Iscritti newsletter
• beta: Membri programma beta
• churned: Clienti a rischio

Casi d'uso dei tag:

• Segmenta campagne per tag
• Filtra contatti per flussi specifici
• Traccia coorti

Campi Personalizzati

customFields è un oggetto JSON a forma libera per le tue proprietà:

{
  "customFields": {
    "plan": "pro",
    "signupDate": "2025-01-01",
    "lastPurchase": "2025-06-15",
    "accountValue": 599.99
  }
}

Usa i campi personalizzati per:

• Archiviare proprietà tue sul contatto
• Filtrare le audience per condizioni sui campi personalizzati
• Personalizzare il contenuto delle email con le variabili

Disiscrivi un Contatto

Non esiste un endpoint di eliminazione. Un contatto si disattiva portandolo allo status unsubscribed, che ne conserva il record mantenendolo soppresso: un contatto eliminato potrebbe essere reimportato e ricevere email per errore.

cURL

curl -X PATCH https://api.tratto.email/v1/contacts/cont_abc123 \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{"status":"unsubscribed"}'

Risposta:

{
  "data": {
    "id": "cont_abc123"
  }
}

Prossimi Passi

• Usare contatti nelle campagne? Vedi Campagne
• Segmentare contatti in audience? Vai a Audience
• Usare i campi personalizzati del contatto nei template? Vedi Template