> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.
# API anteprima email di decisione: approvata e rifiutata
> Visualizza l'email di approvazione o rifiuto che riceve la persona, con destinatario, mittente e lingua, prima di modificare lo stato della sessione con Didit.
Prompt per l'anteprima dell'email di decisione
Copia il prompt negli appunti
\
\`Preview the Approved or Declined email a Didit session sends the person, then confirm the decision so exactly that email goes out.
Endpoint:
POST https://verification.didit.me/v3/session/{session_id}/decision-email-preview/
Authentication:
x-api-key (client API key) or a user-auth token. Privilege: write:sessions. A scoped API key needs write access to decisions.
Path parameter:
\- session_id (UUID): KYC or KYB; Didit resolves it against both session types.
Request body:
\- new_status (string, required): "Approved" or "Declined".
\- email_language (string, optional, default "en"): language of the email. A language that is not offered falls back to English.
The session's current status must be one of: Approved, Declined, In Review, Kyc Expired, Abandoned, Resubmitted.
Previewing changes nothing and sends nothing.
Response (200, Cache-Control: no-store):
\- recipient: the person's own address (the one they verified in the flow, else the one in contact_details). Empty string when none is known.
\- recipient_source: "email_verification", "contact_details", or "" when there is no address.
\- sender, sender_name, sender_email: the From header and its parts.
\- sender_kind: "customer" (your verified sender domain) or "didit" (Didit's sender).
\- subject, html: the email exactly as sent. Render html in a sandboxed frame.
\- language: the language actually used.
\- will_be_sent (boolean) and not_sent_reason: null, "status_unchanged", "notification_emails_disabled", "no_recipient" or "sandbox".
\- preview_token: receipt for this exact email, valid 15 minutes. Empty when there is no recipient.
Confirm with PATCH https://verification.didit.me/v3/session/{session_id}/update-status/:
\{
"new_status": "",
"send_email": true,
"email_address": "",
"email_language": "",
"email_preview_token": ""
}
If the recipient, language, session status, sender or email changed since the preview, or the receipt is older than 15 minutes, update-status returns 409 { "detail": "This email preview changed or expired. Preview the message again before confirming." } and changes nothing. Preview again and confirm with the new receipt.
curl example:
curl -X POST https://verification.didit.me/v3/session//decision-email-preview/ \
-H "x-api-key: " \
-H "Content-Type: application/json" \
-d '{ "new_status": "Approved", "email_language": "en" }'
Failure modes:
\- 400: the session is not in an accepted status ({ "detail": "Only sessions with status ... can be updated. Current status: ..." }), or new_status is missing or invalid.
\- 401: the scoped API key has expired.
\- 403: missing credentials (a wrong, revoked or expired key gets 401), the caller lacks write:sessions, a scoped key lacks decisions write, or the session belongs to another application ({ "detail": "You do not have permission to perform this action." }).
\- 404: { "detail": "Not found." } when no session with this session_id exists.
For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`
\
Incolla in
L'anteprima non modifica nulla e non invia nulla.
La risposta mostra l'email esattamente come la riceve la persona quando imposti la sessione su `Approved` o `Declined` con `send_email: true`.
Indica anche chi la riceve, da chi proviene e se la conferma la invia davvero.## Chi riceve l'emailL'email va all'indirizzo della persona: quello verificato in un passaggio di verifica email del flusso, altrimenti quello indicato in `contact_details` al momento della creazione della sessione.
`recipient_source` indica quale dei due si applica (`email_verification` o `contact_details`).
Se la sessione non contiene un indirizzo per la persona, `recipient`, `recipient_source` e `preview_token` sono stringhe vuote e non è possibile inviare alcuna email.L'email viene inviata dal dominio mittente verificato della tua applicazione quando si applica la tua [configurazione white label](https://docs.didit.me/it/console/white-label.md) (`sender_kind: customer`), altrimenti dal mittente di Didit (`sender_kind: didit`).## Se l'email viene inviata`will_be_sent` è `true` quando la conferma della modifica con `send_email: true` invia l'email.
Quando è `false`, `not_sent_reason` indica il motivo:| `not_sent_reason` | Significato |
| - | - |
| `status_unchanged` | La sessione ha già questo stato, quindi l'aggiornamento non modifica nulla e non invia nulla. |
| `notification_emails_disabled` | La sessione è stata creata senza `contact_details.send_notification_emails: true`, quindi nessuna email di decisione viene inviata all'indirizzo indicato in `contact_details`. |
| `no_recipient` | Non è noto alcun indirizzo per la persona. |
| `sandbox` | La sessione è una sessione sandbox e il destinatario non ha aderito all'invio di email in sandbox, quindi l'email viene solo simulata. Vedi [adesione alle email](https://docs.didit.me/it/integration/sandbox-testing.md#codici-otp-e-opt-in-per-le-email). |## Conferma la decisioneChiama [Update Session Status](https://docs.didit.me/it/sessions-api/update-status.md) con questi campi:| Campo di Update Session Status | Valore |
| - | - |
| `new_status` | Lo stesso `new_status` che hai visualizzato in anteprima |
| `send_email` | `true` |
| `email_address` | `recipient` dell'anteprima |
| `email_language` | `language` dell'anteprima |
| `email_preview_token` | `preview_token` dell'anteprima |La ricevuta scade dopo 15 minuti.
Se il destinatario, la lingua, lo stato della sessione, il mittente o l'email sono cambiati dopo l'anteprima, l'aggiornamento restituisce `409` prima che venga modificato qualsiasi dato.
Ripeti l'anteprima e conferma con la nuova ricevuta.## Correlati- [Update Session Status](https://docs.didit.me/it/sessions-api/update-status.md): approva o rifiuta la sessione e invia l'email.
- [Preview Resubmission Email](https://docs.didit.me/it/sessions-api/preview-resubmission.md): visualizza in anteprima l'email per una nuova presentazione.
- [White label](https://docs.didit.me/it/console/white-label.md): il mittente e il branding utilizzati nell'email.
## OpenAPI
````yaml it/openapi-25.json POST /v3/session/{sessionId}/decision-email-preview/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: API di verifica dell'identità. Autenticati con l'intestazione x-api-key.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/session/{sessionId}/decision-email-preview/:
post:
tags:
- Sessions
summary: Visualizza l'anteprima dell'email con la decisione di una sessione
description: >-
Genera l'anteprima dell'email che la persona riceve quando imposti una
sessione su `Approved` o `Declined` con `send_email: true`, senza
modificare la sessione né inviare alcunché. La risposta mostra l'oggetto
e l'HTML esattamente come vengono inviati, il destinatario, il mittente,
la lingua e se la conferma della modifica comporterà effettivamente
l'invio dell'email (`will_be_sent`, `not_sent_reason`).
Il destinatario è l'indirizzo della persona stessa: quello verificato in
un passaggio di verifica email del workflow, altrimenti quello fornito
in `contact_details` alla creazione della sessione. Il mittente è il
dominio mittente verificato della tua applicazione quando si applica il
White label (`sender_kind: customer`), altrimenti il mittente di Didit
(`sender_kind: didit`).
Per inviare esattamente ciò di cui hai visualizzato l'anteprima, chiama
[Update Session Status](/it/sessions-api/update-status) con gli stessi
`new_status`, `send_email: true`, `email_address` impostato su
`recipient`, `email_language` impostato su `language` ed
`email_preview_token` impostato su `preview_token`. La ricevuta scade
dopo 15 minuti. Se il destinatario, la lingua, lo stato della sessione,
il mittente o l'email sono cambiati rispetto all'anteprima,
l'aggiornamento restituisce `409` prima che venga modificato qualcosa;
genera nuovamente l'anteprima e conferma con la nuova ricevuta.
Funziona per le sessioni di Verifica degli utenti (KYC) e Verifica
aziendale (KYB) con stato `Approved`, `Declined`, `In Review`, `Kyc
Expired`, `Abandoned` o `Resubmitted`. Il controllo dello stato viene
eseguito prima della validazione del corpo. Richiede il privilegio
`write:sessions`; una chiave API con ambito limitato necessita
dell'accesso in scrittura alle decisioni. Le risposte utilizzano
`Cache-Control: no-store`: trattale come contenuto sensibile di
verifica.
operationId: post_v3_session_decision_email_preview
parameters:
- in: path
name: sessionId
required: true
description: >-
UUID della sessione di verifica. Accetta sia ID di sessione utente
(KYC) sia ID di sessione aziendale (KYB).
schema:
type: string
format: uuid
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- new_status
properties:
new_status:
type: string
enum:
- Approved
- Declined
description: >-
La decisione di cui desideri visualizzare l'anteprima
dell'email.
example: Approved
email_language:
type: string
default: en
description: >-
Lingua dell'email, con lo stesso valore predefinito di
Aggiorna stato della sessione. Una lingua non offerta
ripiega sull'inglese; `language` nella risposta indica quale
viene utilizzata.
example: en
examples:
Approved:
summary: Visualizza l'anteprima dell'email di approvazione in inglese
value:
new_status: Approved
Declined in Spanish:
summary: Visualizza l'anteprima dell'email di rifiuto in spagnolo
value:
new_status: Declined
email_language: es
responses:
'200':
description: >-
Solo anteprima. La sessione non viene modificata e non viene inviata
alcuna email.
headers:
Cache-Control:
description: >-
Sempre `no-store`: l'anteprima contiene contenuti di verifica e
non deve essere memorizzata nella cache.
schema:
type: string
example: no-store
content:
application/json:
schema:
type: object
required:
- recipient
- recipient_source
- sender
- sender_name
- sender_email
- sender_kind
- subject
- html
- text
- language
- will_be_sent
- not_sent_reason
- preview_token
properties:
recipient:
type: string
description: >-
L'indirizzo a cui viene inviata l'email. Stringa vuota se
non si conosce alcun indirizzo per la persona: in tal caso
non è possibile inviare alcuna email e anche
`preview_token` è vuoto. Passalo come `email_address`
quando confermi.
example: person@example.com
recipient_source:
type: string
enum:
- email_verification
- contact_details
- ''
description: >-
Da dove proviene `recipient`. `email_verification`:
l'indirizzo verificato dalla persona in un passaggio di
verifica email del flusso. `contact_details`: l'indirizzo
fornito in `contact_details` alla creazione della
sessione. Una stringa vuota quando non è presente alcun
indirizzo.
example: email_verification
sender:
type: string
description: L'intestazione `From` con cui viene inviata l'email.
example: Example App
sender_name:
type: string
description: La parte del nome visualizzato di `sender`.
example: Example App
sender_email:
type: string
format: email
description: La parte relativa all'indirizzo di `sender`.
example: no-reply@mail.example.com
sender_kind:
type: string
enum:
- customer
- didit
description: >-
`customer`: l'email viene inviata dal dominio mittente
verificato della tua applicazione (white label). `didit`:
viene inviata dal mittente di Didit.
example: customer
subject:
type: string
description: La riga dell'oggetto esattamente come viene inviata.
example: Your verification has been approved in Example App
html:
type: string
description: >-
L'HTML dell'email esattamente come inviato, con il logo
incorporato come data URL. Effettuane il rendering in un
frame in sandbox, mai direttamente nel DOM della tua
applicazione.
example: ...
text:
type: string
description: >-
Il testo dell'email in testo normale, così come viene
mantenuto nel thread Messaggi della persona, per
un'anteprima compatta (l'HTML rimane l'email ricevuta
dalla persona).
example: >-
Verification Approved
Your identity has been successfully verified with Acme
Pay. No further action is needed on your part.
language:
type: string
description: >-
La lingua in cui è scritta l'email. Inglese (`en`) se
l'`email_language` richiesta non è disponibile.
example: en
will_be_sent:
type: boolean
description: >-
Indica se la conferma della modifica con `send_email:
true` comporta l'invio di questa email. `false` quando
`not_sent_reason` è impostato.
example: true
not_sent_reason:
type: string
nullable: true
enum:
- status_unchanged
- notification_emails_disabled
- no_recipient
- sandbox
- null
description: >-
Il motivo per cui la conferma non invierebbe alcuna email,
oppure `null` se verrà inviata. `status_unchanged`: la
sessione ha già questo stato, quindi l'aggiornamento non
modifica nulla e non invia nulla.
`notification_emails_disabled`: la sessione è stata creata
senza `contact_details.send_notification_emails: true`,
quindi non viene inviata alcuna email di decisione
all'indirizzo indicato in `contact_details`.
`no_recipient`: non è noto alcun indirizzo per la persona.
`sandbox`: una sessione sandbox il cui destinatario non ha
acconsentito alla consegna delle email in sandbox, quindi
l'invio viene solo simulato.
example: null
preview_token:
type: string
description: >-
Ricevuta firmata per questa specifica email, valida per 15
minuti. Inviala come `email_preview_token` a [Update
Session Status](/it/sessions-api/update-status). Una
stringa vuota quando non è presente alcun destinatario.
example: >-
eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000
examples:
Will Be Sent:
summary: >-
L'email di approvazione viene inviata all'indirizzo
verificato nel flusso
value:
recipient: person@example.com
recipient_source: email_verification
sender: Example App
sender_name: Example App
sender_email: no-reply@mail.example.com
sender_kind: customer
subject: Your verification has been approved in Example App
html: ...
language: en
will_be_sent: true
not_sent_reason: null
preview_token: >-
eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000
No Recipient:
summary: Nessun indirizzo noto per la persona
value:
recipient: ''
recipient_source: ''
sender: Example App
sender_name: Example App
sender_email: no-reply@mail.example.com
sender_kind: customer
subject: Your verification has been declined in Example App
html: ...
language: en
will_be_sent: false
not_sent_reason: no_recipient
preview_token: ''
'400':
description: >-
La sessione non è in uno stato accettato da questo endpoint
(`{"detail": ...}`), oppure il corpo non è valido (`{"":
[""]}`).
content:
application/json:
examples:
Wrong Current Status:
summary: >-
La sessione non si trova in uno stato accettato da questo
endpoint
value:
detail: >-
Only sessions with status Approved, Declined, In Review,
Kyc Expired, Abandoned, Resubmitted can be updated.
Current status: In Progress
Invalid new_status:
summary: new_status non è Approved o Declined
value:
new_status:
- '"Resubmitted" is not a valid choice.'
Missing new_status:
summary: Campo obbligatorio omesso
value:
new_status:
- This field is required.
'401':
description: La chiave API con ambito è scaduta.
content:
application/json:
examples:
Expired API Key:
summary: Chiave API con ambito oltre la sua data di scadenza
value:
detail: This API key has expired.
'403':
description: >-
Credenziali mancanti, chiamante senza il privilegio
`write:sessions`, chiave API con ambito limitato priva dell'accesso
richiesto da questo endpoint, oppure un `session_id` che appartiene
a un'altra applicazione.
content:
application/json:
examples:
Invalid Credentials:
summary: x-api-key mancante o non valida
value:
detail: >-
Authentication credentials were not provided or are
invalid.
Missing Privilege:
summary: Il chiamante non dispone dell'autorizzazione write:sessions
value:
detail: You do not have permission to perform this action.
Scoped Key Without Access:
summary: Chiave API con ambito priva di questo accesso
value:
detail: This API key has no write access to decisions.
'404':
description: Non esiste alcuna sessione KYC o KYB con questo `session_id`.
content:
application/json:
examples:
Not Found:
summary: session_id sconosciuto
value:
detail: Not found.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: |-
curl -X POST \
https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/decision-email-preview/ \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"new_status": "Approved", "email_language": "en"}'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.sessions.preview_decision_email(
"3fa85f64-5717-4562-b3fc-2c963f66afa6",
new_status="Approved",
)
print(result)
- lang: javascript
label: Node.js
source: >-
import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await
didit.sessions.previewDecisionEmail("3fa85f64-5717-4562-b3fc-2c963f66afa6",
{
new_status: "Approved",
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.PreviewDecisionEmail(ctx, \"3fa85f64-5717-4562-b3fc-2c963f66afa6\", didit.SessionsPreviewDecisionEmailParams{\n\tNewStatus: \"Approved\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: >-
import me.didit.Didit;
import me.didit.types.SessionsPreviewDecisionEmailParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result =
client.sessions().previewDecisionEmail("3fa85f64-5717-4562-b3fc-2c963f66afa6",
SessionsPreviewDecisionEmailParams.builder()
.newStatus(SessionsPreviewDecisionEmailParams.NewStatus.of("Approved"))
.build());
System.out.println(result);
- lang: php
label: PHP
source: >-
sessions->previewDecisionEmail('3fa85f64-5717-4562-b3fc-2c963f66afa6',
[
'new_status' => 'Approved',
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.sessions.preview_decision_email(
"3fa85f64-5717-4562-b3fc-2c963f66afa6",
new_status: "Approved"
)
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await
client.Sessions.PreviewDecisionEmailAsync("3fa85f64-5717-4562-b3fc-2c963f66afa6",
new SessionsPreviewDecisionEmailParams
{
NewStatus = "Approved",
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
La chiave API della tua applicazione, da Developers -> API keys nella
Business Console. La chiave primaria ha accesso completo. Una chiave con
nome può avere un ambito definito: nessuno, lettura o scrittura per
risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco
di indirizzi IP e a una data di scadenza. 401 indica che la chiave è
errata, revocata o scaduta; 403 indica che non è stata inviata alcuna
chiave, che la chiave non ha accesso a questa risorsa o azione, oppure
che la richiesta proviene da un indirizzo non incluso nel suo elenco IP;
404 su una route di sessione indica che la sessione non rientra nei
workflow o negli stati previsti dalla chiave. Una chiave senza accesso
ai media riceve gli URL di immagini, video e PDF come null, e una chiave
senza permessi di scrittura sulle sessioni riceve link e token di
sessione come null. Consulta https://docs.didit.me/console/api-keys.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.