> ## 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.

# Pré-visualizar e-mail de decisão: API de verificação

> Veja o e-mail de aprovação ou recusa que o utilizador recebe, com destinatário, remetente e idioma, antes de alterar o estado da sessão. Didit.



Prompt para pré-visualizar o e-mail de decisão
        Copiar o prompt para a área de transferência



      
      

\<pre>

\`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": "<same new_status>",
"send_email": true,
"email_address": "<recipient>",
"email_language": "<language>",
"email_preview_token": "<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/<SESSION_ID>/decision-email-preview/ \
-H "x-api-key: <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.`

\</pre>



      
      

Colar em

A pré-visualização não altera nada e não envia nada.
A resposta mostra o e-mail exatamente como a pessoa o recebe quando define a sessão como `Approved` ou `Declined` com `send_email: true`.
Indica também quem o recebe, quem o envia e se a confirmação o envia de facto.## Quem recebe o e-mailO e-mail é enviado para o endereço da própria pessoa: o que foi verificado num passo de verificação de e-mail do fluxo, caso contrário o indicado em `contact_details` quando a sessão foi criada.
`recipient_source` indica qual deles se aplica (`email_verification` ou `contact_details`).
Quando a sessão não tem endereço para a pessoa, `recipient`, `recipient_source` e `preview_token` ficam com strings vazias e não é possível enviar nenhum e-mail.O e-mail é enviado a partir do domínio de remetente verificado da sua aplicação quando se aplica a sua [configuração de marca branca](https://docs.didit.me/pt/console/white-label.md) (`sender_kind: customer`), caso contrário a partir do remetente da Didit (`sender_kind: didit`).## Se o e-mail é enviado`will_be_sent` é `true` quando a confirmação da alteração com `send_email: true` faz com que o e-mail seja enviado.
Quando é `false`, `not_sent_reason` indica o motivo:| `not_sent_reason` | O que significa |
| - | - |
| `status_unchanged` | A sessão já tem este estado, pelo que a atualização não altera nada e não envia nada. |
| `notification_emails_disabled` | A sessão foi criada sem `contact_details.send_notification_emails: true`, pelo que nenhum e-mail de decisão é enviado para o endereço indicado em `contact_details`. |
| `no_recipient` | Não é conhecido nenhum endereço para a pessoa. |
| `sandbox` | A sessão é uma sessão de sandbox e o destinatário não optou por receber e-mails de sandbox, pelo que o e-mail é apenas simulado. Consulte a [adesão ao envio de e-mail](https://docs.didit.me/pt/integration/sandbox-testing.md#códigos-otp-e-adesão-ao-envio-de-e-mails). |## Confirmar a decisãoChame [Update Session Status](https://docs.didit.me/pt/sessions-api/update-status.md) com estes campos:| Campo de Update Session Status | Valor |
| - | - |
| `new_status` | O mesmo `new_status` que pré-visualizou |
| `send_email` | `true` |
| `email_address` | `recipient` da pré-visualização |
| `email_language` | `language` da pré-visualização |
| `email_preview_token` | `preview_token` da pré-visualização |O recibo expira após 15 minutos.
Se o destinatário, o idioma, o estado da sessão, o remetente ou o e-mail mudarem desde a pré-visualização, a atualização devolve `409` antes de qualquer alteração.
Volte a pré-visualizar e confirme com o novo recibo.## Relacionados- [Update Session Status](https://docs.didit.me/pt/sessions-api/update-status.md): aprove ou recuse a sessão e envie o e-mail.
- [Preview Resubmission Email](https://docs.didit.me/pt/sessions-api/preview-resubmission.md): em alternativa, pré-visualize o e-mail de reenvio.
- [Marca branca](https://docs.didit.me/pt/console/white-label.md): o remetente e a identidade visual que o e-mail utiliza.


## OpenAPI

````yaml pt/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 de Verificação de identidade. Autentique-se com o cabeçalho x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/session/{sessionId}/decision-email-preview/:
    post:
      tags:
        - Sessions
      summary: Pré-visualizar o e-mail de decisão de uma sessão
      description: >-
        Gere o e-mail que a pessoa recebe quando você define uma sessão como
        `Approved` ou `Declined` com `send_email: true`, sem alterar a sessão
        nem enviar nada. A resposta mostra o assunto e o HTML exatamente como
        são enviados, o destinatário, o remetente, o idioma e se a confirmação
        da alteração chega a enviar o e-mail (`will_be_sent`,
        `not_sent_reason`).


        O destinatário é o próprio endereço da pessoa: o endereço que a pessoa
        verificou num passo de verificação de e-mail do fluxo, ou então o
        fornecido em `contact_details` aquando da criação da sessão. O remetente
        é o domínio de remetente verificado da sua aplicação quando a marca
        branca se aplica (`sender_kind: customer`), caso contrário o remetente
        da Didit (`sender_kind: didit`).


        Para enviar exatamente o que pré-visualizou, chame [Update Session
        Status](/pt/sessions-api/update-status) com o mesmo `new_status`,
        `send_email: true`, `email_address` definido como `recipient`,
        `email_language` definido como `language` e `email_preview_token`
        definido como `preview_token`. O comprovativo expira após 15 minutos.
        Quando o destinatário, o idioma, o estado da sessão, o remetente ou o
        e-mail tiverem mudado desde a pré-visualização, a atualização devolve
        `409` antes de qualquer alteração; volte a pré-visualizar e confirme com
        o novo comprovativo.


        Funciona para sessões de Verificação de utilizadores (KYC) e Verificação
        de empresas (KYB) nos estados `Approved`, `Declined`, `In Review`, `Kyc
        Expired`, `Abandoned` ou `Resubmitted`. A verificação do estado é
        executada antes da validação do corpo. Requer o privilégio
        `write:sessions`; uma chave de API com âmbito precisa de acesso de
        escrita a decisões. As respostas utilizam `Cache-Control: no-store`:
        trate-as como conteúdo de verificação sensível.
      operationId: post_v3_session_decision_email_preview
      parameters:
        - in: path
          name: sessionId
          required: true
          description: >-
            UUID da sessão de verificação. Aceita IDs de sessão de utilizador
            (KYC) e de empresa (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: A decisão cujo e-mail pretende pré-visualizar.
                  example: Approved
                email_language:
                  type: string
                  default: en
                  description: >-
                    Idioma do e-mail, a mesma predefinição que Atualizar Estado
                    da Sessão. Um idioma que não esteja disponível reverte para
                    inglês; o campo `language` na resposta indica qual é
                    utilizado.
                  example: en
            examples:
              Approved:
                summary: Pré-visualizar o e-mail de aprovação em inglês
                value:
                  new_status: Approved
              Declined in Spanish:
                summary: Pré-visualizar o e-mail de recusa em espanhol
                value:
                  new_status: Declined
                  email_language: es
      responses:
        '200':
          description: >-
            Apenas pré-visualização. A sessão permanece inalterada e nenhum
            e-mail é enviado.
          headers:
            Cache-Control:
              description: >-
                Sempre `no-store`: a pré-visualização contém conteúdo de
                verificação e não deve ser guardada em 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: >-
                      O endereço para o qual o e-mail é enviado. Uma string
                      vazia quando não se conhece qualquer endereço para a
                      pessoa: nesse caso, nenhum e-mail pode ser enviado e
                      `preview_token` fica também vazio. Passe-o como
                      `email_address` quando confirmar.
                    example: person@example.com
                  recipient_source:
                    type: string
                    enum:
                      - email_verification
                      - contact_details
                      - ''
                    description: >-
                      De onde provém `recipient`. `email_verification`: o
                      endereço que a pessoa verificou num passo de verificação
                      de e-mail do fluxo. `contact_details`: o endereço
                      fornecido em `contact_details` aquando da criação da
                      sessão. Uma string vazia quando não existir endereço.
                    example: email_verification
                  sender:
                    type: string
                    description: O cabeçalho `From` com o qual o e-mail é enviado.
                    example: Example App <no-reply@mail.example.com>
                  sender_name:
                    type: string
                    description: A parte do nome de apresentação de `sender`.
                    example: Example App
                  sender_email:
                    type: string
                    format: email
                    description: A parte da morada de `sender`.
                    example: no-reply@mail.example.com
                  sender_kind:
                    type: string
                    enum:
                      - customer
                      - didit
                    description: >-
                      `customer`: o e-mail sai a partir do domínio de remetente
                      verificado da sua aplicação (marca branca). `didit`: sai a
                      partir do remetente próprio da Didit.
                    example: customer
                  subject:
                    type: string
                    description: A linha de assunto exatamente como é enviada.
                    example: Your verification has been approved in Example App
                  html:
                    type: string
                    description: >-
                      O HTML do e-mail exatamente como é enviado, com o
                      respetivo logótipo incorporado como data URL. Renderize-o
                      numa frame isolada (sandbox), nunca diretamente no DOM da
                      sua aplicação.
                    example: <!DOCTYPE html><html><body>...</body></html>
                  text:
                    type: string
                    description: >-
                      O texto simples do e-mail, tal como o histórico de
                      Mensagens da pessoa o guarda, para uma pré-visualização
                      compacta (o HTML continua a ser o e-mail que a pessoa
                      recebe).
                    example: >-
                      Verification Approved


                      Your identity has been successfully verified with Acme
                      Pay. No further action is needed on your part.
                  language:
                    type: string
                    description: >-
                      O idioma em que o e-mail está escrito. Inglês (`en`)
                      quando o `email_language` solicitado não estiver
                      disponível.
                    example: en
                  will_be_sent:
                    type: boolean
                    description: >-
                      Se confirmar a alteração com `send_email: true` envia este
                      e-mail. `false` quando `not_sent_reason` estiver definido.
                    example: true
                  not_sent_reason:
                    type: string
                    nullable: true
                    enum:
                      - status_unchanged
                      - notification_emails_disabled
                      - no_recipient
                      - sandbox
                      - null
                    description: >-
                      O motivo pelo qual a confirmação não enviaria nenhum
                      e-mail, ou `null` quando será enviado. `status_unchanged`:
                      a sessão já tem este estado, pelo que a atualização não
                      altera nada nem envia nada.
                      `notification_emails_disabled`: a sessão foi criada sem
                      `contact_details.send_notification_emails: true`, pelo que
                      nenhum e-mail de decisão é enviado para o endereço
                      fornecido em `contact_details`. `no_recipient`: nenhum
                      endereço é conhecido para a pessoa. `sandbox`: uma sessão
                      de sandbox cujo destinatário não aceitou a entrega de
                      e-mails em sandbox, pelo que o envio é apenas simulado.
                    example: null
                  preview_token:
                    type: string
                    description: >-
                      Recibo assinado para este e-mail exato, válido por 15
                      minutos. Passe-o como `email_preview_token` para
                      [Atualizar estado da
                      sessão](/pt/sessions-api/update-status). Uma string vazia
                      quando não há destinatário.
                    example: >-
                      eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000
              examples:
                Will Be Sent:
                  summary: >-
                    O e-mail de aprovação é enviado para o endereço verificado
                    no fluxo
                  value:
                    recipient: person@example.com
                    recipient_source: email_verification
                    sender: Example App <no-reply@mail.example.com>
                    sender_name: Example App
                    sender_email: no-reply@mail.example.com
                    sender_kind: customer
                    subject: Your verification has been approved in Example App
                    html: <!DOCTYPE html><html><body>...</body></html>
                    language: en
                    will_be_sent: true
                    not_sent_reason: null
                    preview_token: >-
                      eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000
                No Recipient:
                  summary: Não se conhece nenhuma morada da pessoa
                  value:
                    recipient: ''
                    recipient_source: ''
                    sender: Example App <no-reply@mail.example.com>
                    sender_name: Example App
                    sender_email: no-reply@mail.example.com
                    sender_kind: customer
                    subject: Your verification has been declined in Example App
                    html: <!DOCTYPE html><html><body>...</body></html>
                    language: en
                    will_be_sent: false
                    not_sent_reason: no_recipient
                    preview_token: ''
        '400':
          description: >-
            A sessão não está num estado aceite por este endpoint (`{"detail":
            ...}`), ou o corpo é inválido (`{"<field>": ["<message>"]}`).
          content:
            application/json:
              examples:
                Wrong Current Status:
                  summary: A sessão não está num estado aceite por este 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 não é Approved nem Declined
                  value:
                    new_status:
                      - '"Resubmitted" is not a valid choice.'
                Missing new_status:
                  summary: Campo obrigatório omitido
                  value:
                    new_status:
                      - This field is required.
        '401':
          description: A chave de API com âmbito expirou.
          content:
            application/json:
              examples:
                Expired API Key:
                  summary: Chave de API com âmbito cuja data de validade já passou
                  value:
                    detail: This API key has expired.
        '403':
          description: >-
            Credenciais em falta, um chamador sem o privilégio `write:sessions`,
            uma chave de API com âmbito sem o acesso de que este endpoint
            necessita, ou um `session_id` que pertence a outra aplicação.
          content:
            application/json:
              examples:
                Invalid Credentials:
                  summary: x-api-key em falta ou inválido
                  value:
                    detail: >-
                      Authentication credentials were not provided or are
                      invalid.
                Missing Privilege:
                  summary: O autor da chamada não tem write:sessions
                  value:
                    detail: You do not have permission to perform this action.
                Scoped Key Without Access:
                  summary: Chave de API com âmbito sem este acesso
                  value:
                    detail: This API key has no write access to decisions.
        '404':
          description: Não existe nenhuma sessão de KYC ou KYB com este `session_id`.
          content:
            application/json:
              examples:
                Not Found:
                  summary: session_id desconhecido
                  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: >-
            <?php


            require 'vendor/autoload.php';


            use Didit\DiditClient;


            // Reads DIDIT_API_KEY.

            $didit = new DiditClient();


            $result =
            $didit->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: >-
        A chave de API da sua aplicação, a partir de Programadores -> Chaves de
        API na Business Console. A chave principal tem acesso total. Uma chave
        nomeada pode ter o âmbito definido: nenhum, leitura ou escrita por
        recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de
        endereços IP e a uma data de validade. 401 significa que a chave está
        incorreta, revogada ou expirada; 403 significa que nenhuma chave foi
        enviada, que a chave não tem acesso a este recurso ou ação, ou que o
        pedido veio de um endereço fora da sua lista de IP; 404 numa rota de
        sessão significa que a sessão está fora dos fluxos ou estados da chave.
        Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs
        como nulos, e uma chave sem permissão de escrita em sessões recebe
        ligações de sessão e tokens como nulos. Consulte
        https://docs.didit.me/console/api-keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.