Email API: Guida completa per sviluppatori (2026)

Integrazione API Email: Da OAuth alla Sincronizzazione in Tempo Reale

Un'integrazione reale di API email segue quattro fasi indipendentemente dal provider scelto. Leggi questa sezione come una checklist prima di iniziare la tua implementazione: saltare uno qualsiasi di questi passaggi è il motivo più comune per cui le integrazioni funzionano in fase di sviluppo e si interrompono in produzione.

Autenticazione OAuth 2.0

Sia Gmail che Microsoft Graph utilizzano lo standard Flusso di autorizzazione con codice di autorizzazione OAuth 2.0. I meccanismi sono identici: reindirizza l'utente al provider, ricevi un codice monouso sul tuo URL di callback, scambialo con un token di aggiornamento a lunga durata sul lato server, quindi usa quel token di aggiornamento per generare token di accesso a breve durata per ogni chiamata API successiva.

• Reindirizza l'utente al punto di accesso di autorizzazione del provider con il tuo ID cliente, uri_di_reindirizzamento, e il richiesto ambito.
• L'utente concede i permessi, il provider reindirizza al tuo URL di callback con un token una tantum codice parametro.
• Il tuo server scambia quello codice per un token_accesso (durata di vita di 1 ora) e un token_di_aggiornamento tramite un POST di canale secondario.
• Memorizzare il token_di_aggiornamento server-side, criptata a riposo. Questa è la credenziale a lunga durata che utilizzi per generare automaticamente nuovi token di accesso.

Invia e ricevi e-mail

Una volta autenticate, le due operazioni successive coprono l'80%% dell'utilizzo tipico delle API di posta elettronica: recupero la posta in arrivo e invio un messaggio. Con l'API unificata di Unipile, entrambi funzionano in modo identico su Gmail, Outlook e IMAP attraverso un unico set di endpoint.

# Recupera le ultime 50 email da una casella di posta connessa
curl --request GET \
  --url 'https://api.unipile.com/api/v1/emails?limit=50&folder=inbox' \
  --header 'X-API-KEY: YOUR_API_KEY'

# Invia un'email di testo normale
curl --request POST \
  --url 'https://api.unipile.com/api/v1/emails' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "account_id": "YOUR_ACCOUNT_ID",
    "subject": "Ciao da Unipile",
    "body": "Ciao, questa è un'email di testo normale",
    "to": [{"display_name":"John Doe","identifier":"john@example.com"}]
  }'

Unipile supporta anche le tipiche funzionalità avanzate di invio che gli sviluppatori si aspettano: allegati (multipart form-data con più file), intestazioni personalizzate (passaggio di array di X- header predefiniti), rispondi nella conversazione (usando il messaggio originale provider_id), sovrascrivi nome visualizzato, alias del mittente consentiti, e apertura / tracciamento collegamenti con eventi webhook in tempo reale. Ognuno di questi corrisponde a un singolo campo nel corpo della richiesta, senza negoziazione del protocollo richiesta.

# Invia con allegati + intestazioni personalizzate + tracciamento
curl --request POST \
  --url 'https://api.unipile.com/api/v1/emails' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --form 'account_id=YOUR_ACCOUNT_ID' \
  --form 'subject=Bozza contratto' \
  --form 'body=Trovi qui sotto l'allegato v3.' \
  --form 'to=[{"identifier":"sarah@acme.com"}]' \
  --form 'attachments=@/path/to/contract.pdf' \
  --form 'attachments=@/path/to/appendix.png' \
  --form 'custom_headers=[{"name":"X-Campaign-ID","value":"q1-outreach"}]' \
  --form 'tracking_options={"opens":true,"links":true,"label":"q1-outreach"}'

Per un riferimento completo per sviluppatori che copre tutte le opzioni di invio e il comportamento specifico del provider, consulta il nostro Guida API per l'invio di e-mail.

Sincronizzazione e-mail in tempo reale

La sincronizzazione della casella di posta è la parte più complessa di qualsiasi integrazione di posta elettronica, ed è quella che viene più spesso fraintesa. Un sistema robusto sincronizzazione e-mail l'implementazione ha tre fasi distinte: sincronizzazione iniziale, sincronizzazione incrementale e notifiche webhook in tempo reale. Saltare uno qualsiasi di essi produce un'integrazione che funziona dal primo giorno e si rompe su larga scala.

Pianifica i rinnovi dal primo giorno: le sottoscrizioni di Pub/Sub per la posta di Gmail scadono dopo 7 giorni e devono essere rinnovate. Le sottoscrizioni di Microsoft Graph per le risorse di posta scadono dopo un massimo di circa 3 giorni. Integra il rinnovo delle sottoscrizioni nell'infrastruttura dei tuoi processi in background. prima andare in produzione, altrimenti la tua integrazione smetterà silenziosamente di ricevere eventi.

Webhook ed Eventi

I webhook sono il modo in cui un'API di posta elettronica moderna comunica al tuo backend che è successo qualcosa, in tempo reale, senza che tu debba chiederlo. Invece di interrogare /messaggi ogni 30 secondi (costoso e lento), ti iscrivi una volta e il provider invia un payload JSON al tuo endpoint ogni volta che arriva una nuova email, viene letta, a cui viene risposto o viene eliminata.

Gli eventi a cui ti iscrivi di solito sono posta_ricevuta (un nuovo messaggio è arrivato nella casella di posta in arrivo), posta_inviata (un messaggio in uscita è stato consegnato correttamente), posta_aperta (il destinatario l'ha aperto, se il tracciamento è abilitato), mail_link_clicked (il destinatario ha fatto clic su un link tracciato), e stato_account (La casella di posta connessa necessita di riautenticazione, ad esempio dopo una modifica della password). Ogni evento fornisce contesto sufficiente affinché i tuoi sistemi a valle possano reagire senza effettuare chiamate API aggiuntive.