# Header e metadati > Aggiungi header email personalizzati e List-Unsubscribe agli invii via API, scopri quali header Emailit aggiunge o riscrive e allega metadati che tornano nei webhook. Questa pagina spiega due modi per aggiungere informazioni tue a un’email inviata con l’API email: `headers`, che entrano a far parte del messaggio ricevuto dal destinatario, e `meta`, che Emailit salva con l’email e restituisce nell’API e nei webhook. Elenca anche gli header che Emailit aggiunge, riscrive o rimuove. ## Aggiungi header personalizzati Passa `headers` come oggetto con i nomi degli header e valori di tipo stringa: ```json { "from": "Acme ", "to": "ada@example.com", "subject": "Receipt for order 1042", "text": "Thanks for your order.", "headers": { "X-Entity-Ref-ID": "order-1042", "X-Acme-Account": "881" } } ``` - Per From, To, Cc, Bcc, Reply-To e Subject usa i campi della richiesta, non `headers`. - Non impostare header il cui nome inizia con `X-Emailit-`. Emailit li usa internamente. Ad esempio, un messaggio che contiene già `X-Emailit-ID` viene considerato già elaborato e salta la riscrittura degli header e la firma DKIM di Emailit. - Gli header che imposta Emailit stesso, come `Message-ID` e `Date`, vengono sostituiti anche se li invii. Vedi la sezione successiva. ## Header che Emailit aggiunge o modifica | Header | Cosa fa Emailit | | --- | --- | | `Message-ID` | Lo imposta su ``, lo stesso valore di `message_id` nella risposta all’invio. Un `Message-ID` fornito da te viene sostituito. | | `Date` | Lo imposta quando Emailit elabora per la prima volta il messaggio per la consegna. | | `Subject` | Scrive l’oggetto finale e codifica i caratteri non ASCII. | | `Return-Path` | Imposta un indirizzo di bounce sul sottodominio del return path, `emailit.`, così i bounce tornano a Emailit e SPF è allineato. | | `DKIM-Signature` | Firma il messaggio con la chiave DKIM del tuo dominio. Può essere aggiunta una seconda firma per `emailitmail.com` per i feedback loop delle segnalazioni. | | `Received` | Aggiunge gli header di tracciamento del percorso per l’API e per il server di posta di Emailit. | | `X-Emailit-ID` | Aggiunge il token dell’email. | | `Feedback-ID` | Aggiunge un identificatore che i provider di posta usano nei report delle segnalazioni. | | `X-Emailit-Meta` | Aggiunge i tuoi valori `meta`, codificati in base64, quando invii `meta`. | | `X-Emailit-Tracking` | Aggiunge le impostazioni richieste quando attivi il tracciamento con `tracking`. | | `Bcc` | Lo rimuove, così i destinatari in Bcc restano nascosti. | | `Reply-To` | Lo rimuove quando indica lo stesso indirizzo di From. | | `Content-Disposition` | Lo rimuove dal livello principale del messaggio. Le parti degli allegati mantengono il proprio. | L’[SMTP relay](/it/docs/smtp/headers/) applica la stessa riscrittura ai messaggi che invii tramite SMTP. ## Aggiungi List-Unsubscribe alla posta di massa I provider di posta come Gmail e Yahoo si aspettano un’opzione di disiscrizione con un clic nella posta promozionale e nelle altre email di massa. Le [campagne](/it/docs/campaigns/) la aggiungono automaticamente. Per le newsletter o i riepiloghi che invii tramite l’API, aggiungi tu entrambi gli header: ```json { "from": "Acme ", "to": "ada@example.com", "subject": "Acme weekly digest", "html": "

This week at Acme…

", "headers": { "List-Unsubscribe": ", ", "List-Unsubscribe-Post": "List-Unsubscribe=One-Click" } } ``` - L’URL `https` deve accettare una richiesta `POST` con il corpo `List-Unsubscribe=One-Click` e disiscrivere la persona senza chiederle conferma (RFC 8058). - Rendi ogni URL specifico per il destinatario, così il tuo endpoint sa chi disiscrivere. - Emailit include `List-Unsubscribe` e `List-Unsubscribe-Post` nella firma DKIM, come richiesto dai provider per la disiscrizione con un clic. Vedi [Come soddisfo i requisiti di Gmail e Yahoo per i mittenti di grandi volumi?](/it/docs/kb/gmail-yahoo-bulk-sender-requirements/) per gli altri requisiti. Quando qualcuno si disiscrive, smetti di inviargli email. Puoi aggiungerlo alla [lista di soppressione](/it/docs/suppressions/), così Emailit blocca gli invii futuri. ## Allega metadati `meta` è un oggetto con chiavi e valori di tipo stringa che Emailit salva con ogni email. Usalo per collegare un’email ai record del tuo sistema. ```json { "from": "Acme ", "to": "ada@example.com", "subject": "Receipt for order 1042", "text": "Thanks for your order.", "meta": { "order_id": "1042", "customer_id": "cus_881", "kind": "receipt" } } ``` Converti numeri e booleani in stringhe prima di inviarli. Emailit restituisce `meta`: - In [Recupera un’email](/it/docs/api-reference/emails/get/), [Recupera i metadati](/it/docs/api-reference/emails/meta/) ed [Elenca le email](/it/docs/api-reference/emails/list/). - Negli eventi webhook dell’email: in `data.object.meta` per `email.accepted`, `email.scheduled`, `email.canceled` e gli eventi di consegna, e in `data.object.email.meta` per `email.loaded` ed `email.clicked`. Un evento di consegna con metadati ha questo aspetto (abbreviato): ```json [ { "type": "email.delivered", "data": { "object": { "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa", "object": "email", "to": "ada@example.com", "subject": "Receipt for order 1042", "status": "delivered", "meta": { "order_id": "1042", "customer_id": "cus_881", "kind": "receipt" } } } } ] ``` Un [nuovo tentativo](/it/docs/email-api/retry-and-forward/) mantiene i metadati dell’email. L’inoltro crea una nuova email senza metadati. > **I metadati viaggiano con il messaggio:** Emailit scrive `meta` anche nel messaggio, come header `X-Emailit-Meta` codificato in base64, quindi chiunque visualizzi il messaggio grezzo può decodificarlo. Non inserire in `meta` secret, token o dati personali sensibili. ## Ritrova le email in seguito Non puoi cercare o filtrare le email per `meta`. Per ritrovare un’email: - **Salva gli ID.** Salva l’`id`, o la mappa `ids` se i destinatari sono più di uno, accanto al tuo record, e recupera l’email con [Recupera un’email](/it/docs/api-reference/emails/get/). - **Filtra l’elenco.** [Elenca le email](/it/docs/api-reference/emails/list/) filtra per `to`, `from`, `subject`, `status`, `created_at`, `updated_at`, `spam_score`, `api_key_id` e `sending_domain_id`. Vedi [Filtri e ordinamento](/it/docs/api-reference/filtering/). - **Usa chiavi API separate.** Assegna a ogni applicazione o funzione la propria [chiave API](/it/docs/developers/api-keys/), poi filtra per `api_key_id`, o per **API key** in **Email API → Emails**. - **Associa gli eventi webhook.** Leggi `meta` da ogni evento per indirizzarlo al record giusto appena arriva. ## Vedi anche - [Invia un’email](/it/docs/email-api/send-email/) - [Header SMTP](/it/docs/smtp/headers/) - [Tipi di evento](/it/docs/webhooks/event-types/) - [Dizionario degli header email](/it/docs/dictionary/email-headers/) --- Fonte: https://emailit.com/it/docs/email-api/headers-and-metadata/