# Allegati > Allega file alle email inviate via API come contenuto base64 o da un URL, incorpora immagini inline con il Content-ID e rispetta i tipi di file consentiti e i limiti di dimensione. Questa pagina mostra come allegare file alle email che invii con `POST /emails`, come contenuto codificato in base64 oppure lasciando che Emailit li scarichi da un URL. Spiega anche le immagini inline, i tipi di file consentiti e i limiti di dimensione. ## Campi degli allegati Passa un array `attachments`. Ogni elemento è un oggetto con questi campi: - `filename` (string, obbligatorio): Il nome del file mostrato al destinatario. Deve terminare con un’[estensione consentita](#allowed-file-types). - `content` (string): Il file codificato in base64. Usa `content` oppure `url`, non entrambi. - `url` (string): Un URL `http://` o `https://` da cui Emailit scarica il file. Usa `content` oppure `url`, non entrambi. - `content_type` (string): Il tipo MIME, ad esempio `application/pdf`. Obbligatorio con `content`. Con `url`, il valore predefinito è il `Content-Type` restituito dal server. - `content_id` (string): Un Content-ID. Se lo imposti, l’allegato diventa inline e l’HTML può mostrarlo con `cid:`. - `encoding` (string): Come è codificato `content`. Lascialo su `base64`, a meno che tu non abbia un motivo per cambiarlo. ## Allega un file in base64 Leggi il file, codificalo in base64 e invialo con il suo tipo MIME. **cURL** ```bash curl https://api.emailit.com/v2/emails \ -H "Authorization: Bearer $EMAILIT_API_KEY" \ -H "Content-Type: application/json" \ -d "{ \"from\": \"Acme Billing \", \"to\": \"ada@example.com\", \"subject\": \"Invoice INV-1042\", \"text\": \"Your invoice is attached.\", \"attachments\": [{ \"filename\": \"INV-1042.pdf\", \"content\": \"$(base64 < INV-1042.pdf | tr -d '\n')\", \"content_type\": \"application/pdf\" }] }" ``` **Node.js** ```javascript import { readFile } from 'node:fs/promises'; import { Emailit } from '@emailit/node'; const emailit = new Emailit(process.env.EMAILIT_API_KEY); const pdf = await readFile('INV-1042.pdf'); await emailit.emails.send({ from: 'Acme Billing ', to: 'ada@example.com', subject: 'Invoice INV-1042', text: 'Your invoice is attached.', attachments: [ { filename: 'INV-1042.pdf', content: pdf.toString('base64'), content_type: 'application/pdf', }, ], }); ``` **Python** ```python import base64 import os from emailit import EmailitClient client = EmailitClient(os.environ["EMAILIT_API_KEY"]) with open("INV-1042.pdf", "rb") as f: pdf = base64.b64encode(f.read()).decode("ascii") client.emails.send({ "from": "Acme Billing ", "to": "ada@example.com", "subject": "Invoice INV-1042", "text": "Your invoice is attached.", "attachments": [{ "filename": "INV-1042.pdf", "content": pdf, "content_type": "application/pdf", }], }) ``` **PHP** ```php $emailit = Emailit::client(getenv('EMAILIT_API_KEY')); $emailit->emails()->send([ 'from' => 'Acme Billing ', 'to' => 'ada@example.com', 'subject' => 'Invoice INV-1042', 'text' => 'Your invoice is attached.', 'attachments' => [[ 'filename' => 'INV-1042.pdf', 'content' => base64_encode(file_get_contents('INV-1042.pdf')), 'content_type' => 'application/pdf', ]], ]); ``` ## Allega un file da un URL Invece di codificare tu il file, dai a Emailit un `url`. Emailit scarica il file mentre costruisce il messaggio, quindi la richiesta dura quanto il download. ```json { "from": "Acme Billing ", "to": "ada@example.com", "subject": "Invoice INV-1042", "text": "Your invoice is attached.", "attachments": [ { "filename": "INV-1042.pdf", "url": "https://files.acme.com/invoices/INV-1042.pdf" } ] } ``` L’URL deve rispettare queste regole, altrimenti la richiesta non riesce con `422` e `Attachment error`: - Usa `http` o `https` e punta a un host pubblico. Gli indirizzi privati e interni vengono rifiutati. - Restituisce direttamente il file con uno stato `2xx`. I reindirizzamenti non vengono seguiti. - Il download termina entro 30 secondi. - Il file non supera i 25 MB, secondo il suo header `Content-Length`. Emailit costruisce una copia separata del messaggio per ogni destinatario e scarica gli allegati da URL per ogni copia. Assicurati che gli URL firmati o con scadenza restino validi per tutta la richiesta, e che l’host del file regga un download per destinatario. ## Incorpora immagini inline Per mostrare un’immagine nel corpo HTML invece che come allegato separato, assegnale un `content_id` e fai riferimento a quell’ID con `cid:` in un tag `img`. ```json { "from": "Acme ", "to": "ada@example.com", "subject": "Your weekly report", "html": "

\"Weekly

", "attachments": [ { "filename": "chart.png", "content": "iVBORw0KGgoAAAANSUhEUgAA...", "content_type": "image/png", "content_id": "chart-week-40" } ] } ``` Il `content_id` dell’allegato e il valore dopo `cid:` devono corrispondere esattamente. Le immagini inline rendono il messaggio più pesante per ogni destinatario, quindi per i loghi e le altre immagini condivise di solito è meglio usare nell’HTML l’URL di un’immagine ospitata. ## Limiti di dimensione | Limite | Valore | | --- | --- | | Messaggio intero, dopo la codifica | 40 MB. I messaggi più grandi non riescono con `413 Message too large`. | | Un allegato scaricato da `url` | 25 MB | | Timeout del download per `url` | 30 secondi | | Corpo JSON della richiesta | 50 MB | La codifica base64 rende i file più grandi di circa un terzo, e il limite di 40 MB si applica al messaggio codificato. In pratica, mantieni la dimensione complessiva dei file sotto i 29 MB circa. Per file più grandi, caricali sul tuo storage e invia un link. ## Tipi di file consentiti `filename` deve terminare con una di queste estensioni. Qualsiasi altra estensione, o un nome senza estensione, non supera la convalida e restituisce `400`. | Categoria | Estensioni | | --- | --- | | Testo | `.txt`, `.csv`, `.log`, `.css`, `.ics`, `.xml` | | Immagini | `.jpg`, `.jpe`, `.jpeg`, `.gif`, `.png`, `.bmp`, `.psd`, `.tif`, `.tiff`, `.svg`, `.indd`, `.ai`, `.eps` | | Documenti | `.doc`, `.docx`, `.rtf`, `.odt`, `.ott`, `.pdf`, `.pub`, `.pages`, `.mobi`, `.epub` | | Audio | `.mp3`, `.m4a`, `.m4v`, `.wma`, `.ogg`, `.flac`, `.wav`, `.aif`, `.aifc`, `.aiff` | | Video | `.mp4`, `.mov`, `.avi`, `.mkv`, `.mpeg`, `.mpg`, `.wmv` | | Fogli di calcolo | `.xls`, `.xlsx`, `.ods`, `.numbers` | | Presentazioni | `.odp`, `.ppt`, `.pptx`, `.pps`, `.key` | | Archivi e contatti | `.zip`, `.vcf` | | Email | `.eml` | | Firme e crittografia | `.p7c`, `.p7m`, `.p7s`, `.pgp`, `.asc`, `.sig` | I file eseguibili e gli script non sono nell’elenco e non si possono allegare. ## Leggi gli allegati di un’email inviata [Elenca gli allegati](/it/docs/api-reference/emails/attachments/) (`GET /emails/{id}/attachments`) restituisce ogni allegato con `filename`, `content_type`, `size`, `content_id`, `content_disposition` (`attachment` o `inline`) e il `content` in base64. Richiede una chiave **Full Access**. Gli allegati vengono eliminati insieme al contenuto del messaggio quando termina il periodo di [conservazione dei dati](/it/docs/data-retention/). ## Risoluzione dei problemi | Errore | Cosa controllare | | --- | --- | | `Attachment at index 0 missing content_type (required when using 'content')` | Aggiungi `content_type` a ogni allegato in base64. | | `Attachment 'report.exe' has unsupported file type '.exe'` | Usa un’estensione consentita, oppure metti il file in un `.zip`. | | `Attachment at index 0 cannot have both 'content' and 'url'` | Invia solo uno dei due. | | `Attachment error` con `Failed to fetch attachment` | L’URL ha restituito uno stato di errore, un reindirizzamento o un timeout, oppure non è pubblico. Aprilo da un server esterno alla tua rete per controllare. | | `Attachment error` con `Attachment too large (max 25MB)` | Ospita il file e invia invece un link. | | `413 Message too large` | Riduci la dimensione totale degli allegati. | ## Vedi anche - [Invia un’email](/it/docs/email-api/send-email/) - [Invia un’email](/it/docs/api-reference/emails/send/) nel riferimento API - [Conservazione dei dati](/it/docs/data-retention/) --- Fonte: https://emailit.com/it/docs/email-api/attachments/