Giorgio Gnoli – Consulente CRM e Temporary Manager

Menu
Iscriviti

SFMC Tips #324: invio email immediato con Direct Email Send API

Di /

In questo articolo esploreremo come utilizzare la nuova Direct Email Send API in Marketing Cloud Next Growth & Advanced Editions per inviare email transazionali immediate da un’applicazione esterna.

La Direct Email Send API è progettata per inviare email immediatamente in risposta a eventi applicativi, come email di benvenuto, conferme d’ordine, reset password e notifiche account.

--- Method
POST

--- Endpoint
https://api.salesforce.com/automation/actions360/messaging/email/v1?sendDefinitionId=[Send Definition ID]

--- Headers
Content-Type: application/json
Authorization: Bearer [Access Token]

--- Body
{
  "to": "n.watanabe@nac-care.com",
  "individualId": "003A8000000Dmp1IAD",
  "attributes": {
    "$content": {
      "LastName": "Takahashi",
      "FirstName": "Miyu",
      "OrderNumber": "ORD-0001",
      "OrderDate": "2026-02-05",
      "ItemName": "Sample Item",
      "ItemQuantity": "1",
      "ItemPrice": "2000",
      "PaymentMethod": "Credit Card",
      "TotalAmount": "2200"
    }
  }
}

Attraverso una richiesta API si specifica una Send Definition creata in precedenza, senza passare per un On-Demand Flow, e l’email viene inviata tramite il servizio di messaggistica High Scale Flow (HSF).

In questo articolo percorreremo l’intero processo: creazione di un External Client App, autenticazione OAuth, preparazione del contenuto email e della Send Definition, preview dell’email e infine l’invio.

Panoramica della procedura

  1. Configurare un External Client App
  2. Installare Talend API Tester
  3. Ottenere un access token OAuth
  4. Creare un’email transazionale
  5. Configurare le Content Variables
  6. Creare una Send Definition
  7. Creare una richiesta Direct Email Send API
  8. Fare il preview dell’email tramite la Preview API
  9. Eseguire la Direct Email Send API per inviare l’email

Passaggi di configurazione

1. Configurare un External Client App

Per chiamare la Direct Email Send API è necessario un access token OAuth che includa lo scope sfap_api.

Secondo la documentazione ufficiale di Salesforce, sono supportati i seguenti due flussi OAuth:

  • Authorization Code Flow
  • Client Credentials Flow

L’Authorization Code Flow è indicato quando un utente accede a Salesforce tramite browser e l’API viene eseguita con i permessi di quell’utente.

Il Client Credentials Flow, invece, è pensato per integrazioni server-to-server che non richiedono l’interazione dell’utente. Lo scopo principale della Direct Email Send API è inviare automaticamente email in risposta a eventi generati da un’applicazione esterna, come il completamento di un ordine o una richiesta di reset password.

Per questo motivo, in questo articolo utilizziamo il Client Credentials Flow.

Creare un External Client App dedicato

Sebbene sia possibile aggiungere lo scope sfap_api a un External Client App esistente, in questo articolo creeremo un nuovo External Client App dedicato esclusivamente alla Direct Email Send API.

1. Da Setup, vai su External Client App Manager e clicca su New External Client App.

2. Compila i campi richiesti in Basic Information.

  • External Client App Name
    (Esempio: Direct Email Send API)
    Inserisci un nome descrittivo che identifichi chiaramente lo scopo dell’app. Dopo aver inserito il nome, l’API Name viene generato automaticamente. Poiché entrambi vengono utilizzati solo per la gestione interna, va bene qualsiasi nome significativo.
  • Contact Email
    Inserisci un indirizzo email valido. Questo indirizzo non viene utilizzato per le notifiche API standard: viene semplicemente registrato come contatto amministrativo dell’applicazione.
  • Distribution State
    Poiché questa applicazione verrà utilizzata solo all’interno dell’org Salesforce corrente, puoi lasciare l’impostazione su Local.

3. Successivamente, espandi API (Enable OAuth Settings) e attiva OAuth.

4. Sebbene la Callback URL sia obbligatoria, in questo scenario non viene effettivamente utilizzata. Inserisci un valore qualsiasi, ad esempio:

http://localhost:8082/api/sf/auth/callback

Tips: Con il Client Credentials Flow non c’è alcun redirect da browser, a differenza dell’Authorization Code Flow. Di conseguenza, la Callback URL non viene mai utilizzata durante l’esecuzione di questa API.

Seleziona i seguenti tre scope OAuth:

  1. Manage user data via APIs (api)
  2. Perform requests at any time (refresh_token, offline_access)
  3. Access the Salesforce API Platform (sfap_api)

Tips: Lo scope più importante per la Direct Email Send API è sfap_api. Il solo scope standard api, usato per le REST API Salesforce, non è sufficiente per chiamare la Direct Email Send API.

5. Scorri in basso e attiva le due opzioni seguenti, poi clicca su Create.

  • Enable Client Credentials Flow
  • Issue JSON Web Token (JWT)-based access tokens for named users

L’access token utilizzato dalla Direct Email Send API deve essere in formato JSON Web Token (JWT). Un JWT è composto da tre sezioni separate da punti.

xxxxxxxxxxxxxxxxx.yyyyyyyyyyyyyyy.zzzzzzzzzzzzzzz

6. Successivamente, apri la tab Policies e clicca su Edit.

7. Apri OAuth Policies, attiva Enable Client Credentials Flow e inserisci lo username del tuo Integration User nel campo Run As.

8. Modifica IP Relaxation con la seguente impostazione e salva le modifiche.

  • Relax IP restrictions

Con questa impostazione, l’API può essere eseguita anche da ambienti locali non compresi nei range IP fidati.

*Tuttavia, negli ambienti di produzione è consigliabile implementare un controllo degli accessi adeguato invece di rilassare incondizionatamente le restrizioni IP. Ad esempio, registrando gli indirizzi IP fissi del server API nei range IP fidati.

9. Infine, vai sulla tab Settings e apri OAuth Settings.

10. Clicca su Consumer Key and Secret.

11. Completa l’autenticazione tramite Mobile Authentication o Passcode Authentication. Questa autenticazione viene eseguita dall’amministratore di sistema attualmente collegato.

12. Vengono mostrati il Consumer Key e il Consumer Secret. Ti serviranno più avanti, quindi copiali e conservali oppure lascia questa pagina aperta.

Tips: Il Client Secret non viene ruotato automaticamente in modo periodico. A meno che un amministratore non lo rigeneri (ruoti) esplicitamente, lo stesso Client Secret può continuare a essere utilizzato.

2. Installare Talend API Tester

Per le richieste API descritte in questo articolo utilizzeremo Talend API Tester.

Installa l’estensione Chrome Talend API Tester dal Chrome Web Store.

  1. Cerca Talend API Tester nel Chrome Web Store.

2. Installa Talend API Tester — Free Edition.

3. Al termine dell’installazione, apri Talend API Tester.

3. Ottenere un access token OAuth

Ora otteniamo un access token. Prima di iniziare, assicurati di avere a disposizione i seguenti tre elementi:

  • My Domain
  • Consumer Key
  • Consumer Secret

1. Crea prima una nuova richiesta nella tab Request e imposta il metodo HTTP su POST.

2. Successivamente, inserisci l’URL dell’endpoint.

https://[Nome My Domain].my.salesforce.com/services/oauth2/token

3. Configura l’header della richiesta come segue.

  • Content-Type: application/x-www-form-urlencoded

4. Successivamente, cambia la tab Text sul lato destro della sezione Body in Form.

5. Clicca su Add form parameter tre volte, così da poter inserire tre parametri.

6. Inserisci i seguenti nomi di parametro.

  • grant_type
  • client_id
  • client_secret

7. Per grant_type, inserisci il valore fisso: client_credentials

8. Copia e incolla il client_id e il client_secret ottenuti in precedenza.

9. Dopo aver compilato tutti i campi, clicca su Send.

10. Se la richiesta ha successo (HTTP 200), viene restituito un access token.

Verifica che nella risposta siano presenti i seguenti valori.

  • token_format: jwt
  • scope: sfap_api, api

11. Infine, salva questa richiesta assegnandole un nome, così da poterla riutilizzare in seguito.

4. Creare un’email transazionale

Successivamente, vai alla tab Content e incolla il seguente template email in un componente Paragraph.

In questa implementazione, le Content Variables vengono passate direttamente dalla REST API. Il template seguente contiene già le Content Variables necessarie.

Dear {{$content.FirstName}} {{$content.LastName}},

Thank you for your order.
We have received your order with the following details.

----------------------------------
[Order Number]
{{$content.OrderNumber}}

[Order Date]
%%=FormatDate(($content.OrderDate), "MMMM d, yyyy h:mm a")=%%

[Product]
- Product Name: {{$content.ItemName}}
- Quantity: {{$content.ItemQuantity}}
- Price: %%=FormatNumber($content.ItemPrice,"N0")=%% Yen

[Payment Method]
{{$content.PaymentMethod}}

[Total Amount]
%%=FormatNumber($content.TotalAmount,"N0")=%% Yen
----------------------------------

We will notify you once your order is ready for shipment.

If you have any questions, please reply to this email or contact our support team.

Thank you for your continued support.

In questo esempio utilizziamo la nuova funzionalità Content Variable introdotta con Summer ’26. Aggiungi le seguenti variabili dalla Data Source.

I nomi delle variabili, incluse le maiuscole/minuscole, devono corrispondere esattamente ai valori che verranno forniti successivamente dall’API.

  • LastName (Text)
  • FirstName (Text)
  • OrderNumber (Text)
  • OrderDate (DateTime)
  • ItemName (Text)
  • ItemQuantity (Text)
  • ItemPrice (Number)
  • PaymentMethod (Text)
  • TotalAmount (Number)

Dopo aver configurato le Content Variables, salva e pubblica l’email.

Nota: Prima di pubblicare, cambia il tipo di email in Transactional Email.

Recupera il ManagedContentId (che inizia con 20Y) dell’email pubblicata.

  • Esempio: 20YTK0000170ASm2AM

5. Creare una Send Definition

Successivamente, crea una Send Definition.

Nota: problema temporaneo relativo al FromAddress non riconosciuto

Durante i miei test, ho riscontrato un problema per cui il campo FromAddress non veniva riconosciuto correttamente durante la creazione di un record ListEmail (Send Definition) tramite REST API.

L’indirizzo del mittente utilizzato nel test era già stato registrato in Authenticated Domains in Marketing Cloud Next con il seguente stato:

  • Domain Status: Active
  • From Address: Active
  • Capability: Outbound

Tuttavia, quando il FromAddress registrato veniva specificato nel body della richiesta REST API, veniva restituito il seguente errore.

[
  {
    "message": "There were custom validation error(s) encountered while saving the affected record(s). The first validation error encountered was \"invalid email address: FromAddress\".",
    "errorCode": "INVALID_INPUT",
    "fields": [
      "FromAddress"
    ]
  }
]

Poiché lo stesso indirizzo mittente poteva essere salvato correttamente in un record ListEmail creato dall’interfaccia utente di Salesforce, il problema non sembrava legato al formato dell’indirizzo email o all’autenticazione del domain. È possibile invece che si trattasse di un problema temporaneo nel processo di validazione API per il FromAddress.

Soluzione temporanea

Come soluzione alternativa, ho eseguito una volta un On-Demand Flow per forzare la creazione del record ListEmail. Ho poi utilizzato l’ID del record risultante come sendDefinitionId, riuscendo così a effettuare correttamente il preview e l’invio delle email.

Nota: Le email possono essere inviate anche quando lo stato del ListEmail è Draft.

Poiché si tratta apparentemente di un problema temporaneo, se non riscontri lo stesso errore puoi semplicemente creare la Send Definition tramite REST API come di consueto.

Normalmente, esegui la seguente richiesta da Talend API Tester.

--- Method
POST

--- Endpoint
https://[Nome My Domain].my.salesforce.com/services/data/v67.0/sobjects/ListEmail

--- Headers
Content-Type: application/json
Authorization: Bearer [Access Token]

--- Body
{
  "Name": "direct-email-send-api@1.0.0",
  "FromName": "NAC Co.,Ltd",
  "FromAddress": "info@mail.nac-care.com",
  "ManagedContentId": "20YTK0000170ASm2AM",
  "MessagePurpose": "Transactional",
  "IsOpenTrackingEnabled": true,
  "IsClickTrackingEnabled": true,
  "Status": "Draft"
}

Se la richiesta ha successo, viene restituita la seguente risposta. L’id è il tuo sendDefinitionId.

6. Creare una richiesta Direct Email Send API

Questo esempio utilizza la seguente richiesta.

--- Method
POST

--- Endpoint
https://api.salesforce.com/automation/actions360/messaging/email/v1?sendDefinitionId=[Send Definition ID]

--- Headers
Content-Type: application/json
Authorization: Bearer [Access Token]

--- Body
{
  "to": "n.watanabe@nac-care.com",
  "individualId": "003A8000000Dmp1IAD",
  "attributes": {
    "$content": {
      "LastName": "Takahashi",
      "FirstName": "Miyu",
      "OrderNumber": "ORD-0001",
      "OrderDate": "2026-02-05",
      "ItemName": "Sample Item",
      "ItemQuantity": "1",
      "ItemPrice": "2000",
      "PaymentMethod": "Credit Card",
      "TotalAmount": "2200"
    }
  }
}
  • Specifica in sendDefinitionId l’ID della Send Definition (il record ListEmail) creata precedentemente.
  • to (l’indirizzo email) è un campo obbligatorio. Non deve necessariamente essere un indirizzo email presente nel tuo CRM.
  • Specifica il destinatario tramite individualId (che inizia con una i minuscola). Questo valore viene utilizzato come identificatore in Email Engagement. Anche in questo caso non deve esistere nel tuo CRM: puoi usare qualsiasi valore.
  • Memorizza i tuoi dati di personalizzazione in attributes. I nomi degli attributi, incluse le maiuscole/minuscole, devono corrispondere esattamente a quelli definiti nella tua Content Variable.
  • Questa API viene fornita separatamente dalla REST API standard di Salesforce, come dimostrano l’host, il path, lo scope OAuth e la versione API differenti. Di conseguenza, viene gestita in modo indipendente rispetto alla REST API standard di Salesforce, inclusi i limiti d’uso come le quote di chiamate API.

7. Fare il preview dell’email tramite la Preview API

Prima di inviare l’email effettiva, utilizza la Preview API per verificare il risultato del rendering.

Modifica solo l’endpoint come mostrato di seguito. Utilizza gli stessi header e lo stesso body della richiesta precedente.

--- Endpoint
https://api.salesforce.com/automation/actions360/messaging/email/v1/preview?sendDefinitionId=[Send Definition ID]

Verifica quanto segue:

  • Nome e cognome del destinatario vengono visualizzati correttamente.
  • La data dell’ordine viene visualizzata come July 31, 2026 12:25 PM.
  • Il prezzo del prodotto viene visualizzato come 2.000.
  • L’importo totale viene visualizzato come 2.200.
  • Il corpo dell’email non è vuoto.
  • L’individualId specificato viene correttamente risolto come destinatario.
{
"response":{
"subject": "Direct Email Send API",
"body": "<!doctype html>...
                Dear Miyu Takahashi,<br><br>Thank you for your order.<br>We have received your order with the following details.<br><br>----------------------------------<br>[Order Number]<br>ORD-0001<br><br>[Order Date]<br>July 31, 2026 12:25 PM<br><br>[Product]<br>- Product Name: Sample Item<br>- Quantity: 1<br>- Price: $2,000<br><br>[Payment Method]<br>Credit Card<br><br>[Total Amount]<br>$2,200<br>----------------------------------<br><br>We will notify you once your order is ready for shipment.<br><br>If you have any questions, please reply to this email or contact our support team.<br><br>Thank you for your continued support.&nbsp;
...",
"preheader": "",
"text": " Dear Miyu Takahashi,

Thank you for your order.
We have received your order with the following details.

----------------------------------
[Order Number]
ORD-0001

[Order Date]
July 31, 2026 12:25 PM

[Product]
- Product Name: Sample Item
- Quantity: 1
- Price: $2,000

[Payment Method]
Credit Card

[Total Amount]
$2,200
----------------------------------

We will notify you once your order is ready for shipment.

If you have any questions, please reply to this email or contact our support team.

Thank you for your continued support. 

"
}
}

Se il preview risulta corretto, cambia nuovamente l’endpoint in /messaging/email/v1 ed esegui l’invio effettivo.

8. Eseguire la Direct Email Send API

Dopo aver inviato la richiesta descritta sopra, l’email è stata consegnata correttamente all’indirizzo specificato.

Controllando l’email, ho confermato che nome del destinatario, numero d’ordine, data dell’ordine, informazioni sul prodotto e importo specificati nell’oggetto $content della richiesta API sono stati resi correttamente nel corpo dell’email. Il test è andato a buon fine.

Conclusioni

In questo articolo abbiamo esplorato come inviare email transazionali direttamente da un sistema esterno utilizzando la Direct Email Send API.

Durante i test ho riscontrato anche alcuni comportamenti difficili da individuare partendo solo dalla documentazione ufficiale, oltre a qualche problema che sembrava essere temporaneo e specifico dell’ambiente.

Sebbene la struttura della richiesta della Direct Email Send API sia relativamente semplice, i prerequisiti necessari — inclusi autenticazione, contenuto dell’email, indirizzo mittente e Send Definition — devono essere tutti configurati correttamente.

Poiché i problemi di configurazione possono facilmente generare errori, consiglio di utilizzare prima la Preview API per verificare oggetto, corpo dell’email e valori delle Content Variable, prima di procedere con l’invio effettivo.

Spero che questo articolo ti sia utile per implementare la Direct Email Send API.

È tutto per questo articolo.

Resta aggiornato per altri tips su Salesforce Marketing Cloud! 😎

Nobuyuki Watanabe

Tradotto e adattato da SFMC Tips #324 : Marketing Cloud Next: Immediate Email Delivery with the Direct Email Send API di Nobuyuki Watanabe (@marketingcloudtips), pubblicato originariamente su Medium. Traduzione autorizzata dall’autore.

Related Posts:

Torna in alto