Allegati e immagini inline

Frontmail offre quattro modi per aggiungere file a un’email. Gli allegati sono disponibili sui piani a pagamento; la dimensione totale massima per richiesta dipende dal piano (vedi Piani).

Metodo	Dove si configura	Uso
Allegati statici	Impostazioni del modello	Lo stesso file in ogni email (listino prezzi, PDF delle condizioni)
Base64 dinamico	attachments nella richiesta di invio	Piccoli file generati (≤ qualche centinaio di kB)
Upload	POST /v1/uploads, poi attachments: [{ upload_id }]	File più grandi, file scelti dagli utenti
File da modulo	Campi file di sendForm() / /v1/send-form	File allegati a un modulo HTML

Allegati statici

Gli allegati statici sono file allegati a ogni email inviata con il modello (fino a 10 per modello). Sono conservati in S3 e contano nel limite di dimensione per richiesta. L’editor dei modelli li elenca in Impostazioni → Protezione → Allegati statici; caricarli dalla dashboard non è ancora possibile: se te ne serve uno, scrivi a support@frontmail.dev.

Allegati dinamici

Attiva prima Consenti allegati dal modulo in Impostazioni → Protezione del modello; altrimenti le richieste con allegati falliscono con attachments_not_allowed.

Base64 nella richiesta

await send('svc_01J9…', 'tpl_invoice', { name: 'Giulia' }, {
  attachments: [
    { filename: 'fattura.pdf', contentType: 'application/pdf', contentBase64: pdfBase64 },
  ],
});

"attachments": [
  { "filename": "fattura.pdf", "content_type": "application/pdf", "content_base64": "JVBERi0xLjcK…" }
]

Il base64 aumenta la richiesta di un terzo: per tutto ciò che supera qualche centinaio di kilobyte, usa gli upload.

Upload

1. Richiedi un URL di upload (con chiave pubblica o privata):

   curl https://api.frontmail.dev/v1/uploads \
     -H 'Content-Type: application/json' \
     -H 'X-Frontmail-Public-Key: pk_4f2a…' \
     -d '{ "filename": "cv.pdf", "content_type": "application/pdf", "size": 482113 }'

   {
     "upload_id": "upl_01J9Z3",
     "url": "https://uploads.frontmail.dev/…",
     "method": "PUT",
     "headers": { "Content-Type": "application/pdf" },
     "expires_at": "2026-09-24T11:00:00Z"
   }

2. Invia il file con PUT a url con gli headers restituiti prima di expires_at.

3. Fai riferimento al file nell’invio: "attachments": [{ "upload_id": "upl_01J9Z3" }].

La size dichiarata viene confrontata subito con il limite del tuo piano (attachment_too_large) e l’oggetto salvato viene controllato di nuovo al momento dell’invio del messaggio.

File da modulo

Con sendForm(), ogni <input type="file"> del modulo diventa un allegato:

<input type="file" name="cv" accept="application/pdf">

Tipi e nomi di file bloccati

Gli allegati dinamici arrivano da chiunque possa usare il tuo modulo, quindi Frontmail rifiuta i tipi di file che eseguono codice o che sono tipici veicoli di phishing, con attachments_not_allowed: eseguibili e programmi di installazione (.exe, .msi, .msix, .appx, .scr, .com, .bat, .cmd, .cpl, .dll, .jar, .app, .pkg, …), script (.js, .jse, .vbs, .wsf, .ps1, .hta, …), collegamenti (.lnk, .url, .library-ms, …), immagini disco (.iso, .img, .vhd, .vhdx, .dmg), pagine web e immagini vettoriali (.html, .htm, .xhtml, .mht, .svg), OneNote (.one) e file Office con macro (.docm, .xlsm, .pptm, …). I nomi dei file vengono prima ripuliti: i caratteri invisibili e da destra a sinistra (usati per camuffare invoice<U+202E>fdp.exe come invoiceexe.pdf) e i punti o gli spazi finali vengono rimossi, quindi report.exe. conta come .exe.

Con la chiave pubblica, anche POST /v1/uploads richiede almeno un modello che consenta gli allegati dal modulo, e gli upload condividono un budget giornaliero per organizzazione pari a 200 × il limite di allegati del tuo piano.

Immagini inline

Hai due possibilità:

• Immagini ospitate – usa un URL https:// assoluto in <img src>. Ideale per loghi e decorazioni: email leggere, e i client caricano le immagini quando servono.
• Immagini CID – un allegato statico con un content ID, ad es. logo, a cui fai riferimento con <img src="cid:logo" alt="Esempio S.r.l.">. L’immagine è incorporata nell’email, quindi viene mostrata anche quando le immagini remote sono bloccate, ma rende ogni email più pesante.

Imposta sempre alt sulle immagini: i controlli del modello ti avvisano se manca.

Nota

Alcuni provider limitano i tipi di allegato o la dimensione totale del messaggio (ad es. 10 MB per l’API SES v1, 25 MB per Gmail). Se il tuo piano consente più del tuo provider, vale il limite del provider. Vedi le guide ai provider.

Nella dashboard

Consulta Editor dei modelli per le impostazioni del modello.