Questo articolo spiega come aggiornare un template esistente dell'Email Builder di HITLEAD e le relative impostazioni email tramite l'endpoint API PATCH /emails/builder/:templateId. Copre i campi supportati, il payload semplificato dell'editor, i passi di configurazione, le best practice e le domande frequenti per gli sviluppatori che gestiscono i template tramite integrazioni API.

IMPORTANTE: Per i dettagli completi sull'endpoint, i parametri della richiesta e le informazioni sulla risposta, consulta la documentazione ufficiale API: Update a template with settings

INDICE

Cos'è l'aggiornamento dei template Email Builder e delle impostazioni email tramite API?

Aggiornare i template Email Builder e le impostazioni email tramite API consente agli sviluppatori di apportare modifiche a un template Email Builder esistente senza dover intervenire manualmente all'interno di HITLEAD. Con l'endpoint PATCH /emails/builder/:templateId puoi aggiornare il contenuto del template e le impostazioni email supportate in una singola chiamata API.

Questa funzionalità è utile per agenzie, sviluppatori e partner di integrazione che gestiscono i template email in modo programmatico. Invece di effettuare aggiornamenti separati per il contenuto del template e le impostazioni email, questo endpoint semplifica il processo di aggiornamento mantenendo il comportamento di aggiornamento esistente.

Cos'è l'endpoint di aggiornamento del template Email Builder?

L'endpoint di aggiornamento del template Email Builder consente di aggiornare un template Email Builder esistente utilizzando il suo templateId. Questo endpoint è pensato per chi ha bisogno di controllo API sul contenuto del template e sulle impostazioni email supportate, come la riga dell'oggetto, i dettagli del mittente e il testo di anteprima.

Endpoint:

PATCH /emails/builder/:templateId

Questo endpoint supporta gli aggiornamenti ai template Email Builder esistenti. Può essere utilizzato per aggiornare il contenuto del template, le impostazioni email, o entrambi in una sola richiesta.

Importante: Questo endpoint aggiorna un template Email Builder esistente. Non deve essere considerato come strumento per aggiornare Campaign inviate, Campaign pianificate o copie email nei Workflow, a meno che quel comportamento non sia confermato per il tuo caso d'uso specifico.

Vantaggi principali dell'aggiornamento dei template Email Builder tramite API

Gli aggiornamenti dei template tramite API aiutano i team a gestire i contenuti email in modo più efficiente, specialmente quando si lavora su più template, sedi o integrazioni. Questo può ridurre le modifiche manuali e rendere più semplice mantenere coerenti i contenuti e le impostazioni dei template.

  • Singola chiamata API: Aggiorna il contenuto del template e le impostazioni email supportate insieme, invece di fare modifiche separate.

  • Controllo completo del template: Gestisci il contenuto dei template Email Builder esistenti tramite API.

  • Supporto alle impostazioni email: Aggiorna subject, fromName, fromEmail e previewText.

  • Struttura del payload più pulita: Usa editorType e editorContent invece della struttura precedente che utilizzava type, html/dnd e isPlainText.

  • Gestione automatica del testo normale: isPlainText viene ora derivato automaticamente, riducendo la necessità di inviare quel valore manualmente.

  • Compatibilità con le versioni precedenti: Il comportamento di aggiornamento esistente viene mantenuto, supportando al contempo il payload semplificato.

  • Preparazione delle Campaign più rapida: Aggiorna rapidamente i template riutilizzabili prima di utilizzarli nelle Campaign o in altri Workflow email.

Impostazioni email supportate

Le impostazioni email definiscono come l'email appare ai destinatari prima e dopo che l'abbiano aperta. Aggiornare questi campi tramite API aiuta a garantire che il template abbia le informazioni corrette sul mittente, la riga dell'oggetto e il testo di anteprima prima che venga utilizzato.

L'endpoint ora supporta l'aggiornamento delle seguenti impostazioni email:

CampoDescrizioneObbligatorio
subjectLa riga dell'oggetto dell'email visualizzata nella casella di posta del destinatario.No
fromNameIl nome del mittente visualizzato ai destinatari.No
fromEmailL'indirizzo email del mittente visualizzato ai destinatari.No
previewTextIl breve testo di anteprima mostrato da molti provider di posta vicino alla riga dell'oggetto.No

Tutti i campi delle impostazioni del template sono facoltativi. Puoi inviare solo i campi che vuoi aggiornare.

Nota sulla validazione: fromEmail viene validato per il corretto formato email. Se viene fornito un formato email non valido, la richiesta potrebbe fallire la validazione.

Segnaposto screenshot: Aggiungi uno screenshot che mostra il pannello delle impostazioni dell'Email Builder dove vengono configurati oggetto, nome mittente, email mittente e testo di anteprima nell'interfaccia di HITLEAD.

Payload semplificato dell'editor

Il payload semplificato dell'editor riduce il numero di campi necessari per aggiornare il contenuto del template. Invece di passare manualmente valori separati per il tipo di editor, il contenuto HTML o drag-and-drop, e lo stato del testo normale, la struttura aggiornata utilizza editorType e editorContent.

In precedenza, le integrazioni potevano utilizzare campi come:

  • type
  • html
  • dnd
  • isPlainText

La struttura semplificata utilizza:

  • editorType
  • editorContent

Con questo aggiornamento, isPlainText viene derivato automaticamente. Questo significa che non è più necessario inviare manualmente isPlainText quando si utilizza il payload semplificato dell'editor.

Esempio di struttura semplificata:

{
  "editorType": "html",
  "editorContent": "<html><body><p>Il tuo contenuto email aggiornato</p></body></html>"
}

Il valore esatto di editorType deve corrispondere al tipo di editor supportato per il template che stai aggiornando.

Segnaposto screenshot: Aggiungi uno screenshot o diagramma che mostra la struttura del payload semplificato con editorType e editorContent in evidenza.

Aggiornare contenuto e impostazioni del template insieme

Aggiornare contenuto e impostazioni insieme è utile quando un template necessita sia di modifiche al design o al testo che di aggiornamenti visibili nella casella di posta. Ad esempio, potresti voler aggiornare il contenuto del corpo, la riga dell'oggetto, il nome del mittente e il testo di anteprima allo stesso tempo.

Esempio di corpo della richiesta:

{
  "editorType": "html",
  "editorContent": "<html><body><p>Contenuto del template email aggiornato.</p></body></html>",
  "subject": "Oggetto email aggiornato",
  "fromName": "Nome della tua azienda",
  "fromEmail": "mittente@esempio.com",
  "previewText": "Una breve anteprima della tua email aggiornata."
}

Poiché tutti i campi delle impostazioni del template sono facoltativi, puoi includere solo i campi che devono essere modificati.

Esempio di corpo della richiesta per aggiornare solo le impostazioni email:

{
  "subject": "Nuova riga dell'oggetto",
  "fromName": "Nome della tua azienda",
  "fromEmail": "mittente@esempio.com",
  "previewText": "Testo di anteprima della casella di posta aggiornato."
}

Esempio di corpo della richiesta per aggiornare solo il contenuto del template:

{
  "editorType": "html",
  "editorContent": "<html><body><p>Viene aggiornato solo il contenuto del template.</p></body></html>"
}

Considerazioni sui template nei Workflow

I template email utilizzati all'interno dei passi di un Workflow possono comportarsi diversamente a seconda di come il template è stato aggiunto e se le modifiche vengono sincronizzate. Un template salvato aggiunto a un Workflow può diventare una copia all'interno del passo del Workflow, quindi gli aggiornamenti al template originale potrebbero non applicarsi sempre a quell'email nel Workflow.

Prima di fare affidamento sugli aggiornamenti API per le email nei Workflow:

  • Verifica se l'email del Workflow è sincronizzata con il template originale.

  • Controlla il passo email del Workflow dopo aver aggiornato il template.

  • Testa l'email del Workflow prima di attivare o fare affidamento sull'automazione.

Per il comportamento specifico dei Workflow, consulta Gestione dei template email nei passi del Workflow.

Domande frequenti

D: Posso aggiornare solo la riga dell'oggetto senza modificare il contenuto del template?

Sì. Tutti i campi delle impostazioni del template sono facoltativi, quindi puoi inviare solo il campo subject se è l'unico valore che vuoi aggiornare.

D: Posso aggiornare i dettagli del mittente tramite questo endpoint?

Sì. L'endpoint supporta l'aggiornamento di fromName e fromEmail.

D: fromEmail viene validato?

Sì. fromEmail viene validato per il corretto formato email.

D: Devo ancora inviare isPlainText?

No. Con la struttura del payload semplificata, isPlainText viene derivato automaticamente.

D: Quali campi hanno sostituito la struttura precedente del payload dell'editor?

Il payload semplificato utilizza editorType e editorContent invece della struttura precedente che usava type, html/dnd e isPlainText.

D: Questo endpoint può aggiornare sia il contenuto che le impostazioni in una sola richiesta?

Sì. Puoi aggiornare il contenuto del template e le impostazioni email supportate in una singola chiamata API.

D: Questo endpoint aggiorna solo i template esistenti?

Sì. L'endpoint viene utilizzato per aggiornare un template Email Builder esistente identificato dal templateId.

D: Questo aggiornerà automaticamente i template già copiati nei Workflow?

Non sempre. Il comportamento delle email nei Workflow può dipendere dal fatto che l'email del Workflow sia copiata o sincronizzata con il template originale. Controlla il passo email del Workflow dopo aver aggiornato un template.

D: Cosa devo fare dopo aver aggiornato un template tramite API?

Apri il template in HITLEAD, controlla il contenuto e le impostazioni aggiornati, quindi visualizza l'anteprima e testa l'email prima di utilizzarla.