Documentazione
Sign inGet started
Inizia ora
Guide
Riferimento API
SDK
CLI
Knowledge Base
Changelog

Allegati

Allega file a un invio aggiungendo un array attachments al payload POST /v1/email/messages. Ogni voce contiene i byte del file codificati in base64 in content, più un filename. Lo stesso array funziona su un elemento batch. Gli schemi completi di richiesta e risposta si trovano nel reference API.

Un invio con un allegato

await bird.email.send({
  from: "hello@yourdomain.com",
  to: ["delivered@messagebird.dev"],
  subject: "Your invoice",
  html: "<p>Thanks for your order. Your invoice is attached.</p>",
  attachments: [
    {
      filename: "invoice.pdf",
      content: "JVBERi0xLjcKJ...",
      content_type: "application/pdf",
    },
  ],
});
L'CLI legge il file e lo codifica in base64 per te; tramite la API fornisci tu stesso i byte codificati. L'SDK Go accetta i byte grezzi e li codifica al momento dell'invio.
content contiene i byte grezzi del file, codificati in base64. content_type è opzionale: se lo ometti, il tipo MIME viene dedotto dall'estensione di filename, con fallback a application/octet-stream per le estensioni non riconosciute. Tutto il resto dell'invio funziona esattamente come descritto in invio email: 202, il modello asincrono, i tag e i metadati non cambiano in presenza di allegati.

I campi dell'allegato

CampoTipoObbligatorioNote
filenamestringsìDa 1 a 255 caratteri; visibile al destinatario. Nessun ritorno a capo o carattere di controllo.
contentstringsìByte del file codificati in Base64.
content_typestringnoTipo MIME; dedotto dall'estensione del nome file se omesso.
content_idstringnoDa 1 a 128 caratteri, [A-Za-z0-9._-]. Impostalo per visualizzare il file inline anziché come allegato.
Un'email può avere fino a 20 allegati (attachments accetta al massimo 20 elementi).

Immagini inline

Per incorporare un'immagine nel body HTML anziché allegarla, assegna all'allegato un content_id e fai riferimento ad esso nel markup con un URL cid::
Esempio di codice
{
  "html": "<p>Welcome aboard!</p><img src=\"cid:welcome-banner\"/>",
  "attachments": [
    {
      "filename": "banner.png",
      "content": "iVBORw0KGgoAAAANS...",
      "content_type": "image/png",
      "content_id": "welcome-banner"
    }
  ]
}
Il content_id è il collegamento tra il riferimento cid: e l'allegato. Ogni immagine inline richiede un content_id univoco all'interno dell'invio; un duplicato viene rifiutato con un 422. Un allegato senza content_id viene consegnato come normale file allegato.

Budget di dimensione

Rifiutiamo un invio la cui dimensione stimata del messaggio generato supera 20 MB con un 413. La stima comprende il body HTML più il body testuale più ogni allegato misurato dopo la codifica base64. La codifica aumenta i byte grezzi di circa 4/3, quindi un file da 15 MB da solo esaurisce già l'intero budget di 20 MB. Come regola pratica, mantieni il contenuto grezzo totale degli allegati ben al di sotto di 15 MB in modo che i body e il wrapping MIME rientrino ancora nel limite.
I server riceventi possono applicare limiti di dimensione inferiori. Un messaggio accettato da Bird può comunque generare un bounce se il server del destinatario ne rifiuta la dimensione. Scegli le dimensioni degli allegati in base ai provider di posta e alle organizzazioni a cui invii.
Per i messaggi ricevuti, consulta Dimensione dei messaggi in entrata.

Tipi di file bloccati

Gli allegati eseguibili e di script vengono rifiutati in fase di validazione con un 422, in base al content_type o all'estensione del nome file. Le estensioni bloccate includono .exe, .dll, .msi, .bat, .cmd, .scr, .jar, .js, .vbs, .ps1, .sh, .hta e .lnk. Anche i tipi MIME equivalenti come application/x-msdownload, application/java-archive e text/javascript sono bloccati. Questa validazione non è un antivirus. Per distribuire un file bloccato, pubblicalo dietro un link.

In un batch

Ogni elemento di un invio batch può avere il proprio attachments, con lo stesso contratto di campi e lo stesso budget di 20 MB per messaggio. Il body serializzato della richiesta batch ha un proprio limite superiore, che gli allegati codificati in base64 consumano rapidamente; consulta invio batch per il limite a livello di batch e come suddividere gli invii per rispettarlo.

Lettura e download degli allegati

Le letture API non restituiscono mai i byte degli allegati. GET /v1/email/messages/{message_id} restituisce un array attachments con solo i metadati; ogni voce contiene id, filename, content_type, size (byte decodificati) e inline dell'allegato:
Esempio di codice
{
  "attachments": [
    {
      "id": "ea_019c...",
      "filename": "invoice.pdf",
      "content_type": "application/pdf",
      "size": 215432,
      "inline": false
    }
  ]
}
Per ottenere i byte grezzi, chiama GET /v1/email/messages/{message_id}/attachments/{attachment_id} (reference). Restituisce il file in streaming con il proprio content type e un header Content-Disposition che indica il nome del file. Due condizioni lo regolano:
  • L'archiviazione dei contenuti deve essere abilitata per lo spazio di lavoro. Con l'archiviazione disabilitata, non viene archiviato nulla da scaricare. Consulta cosa significa un 202.
  • Gli allegati vengono conservati per 30 giorni dopo l'invio. Dopo tale periodo il download restituisce 410 Gone.
Un 404 indica che il messaggio non ha contenuto archiviato o nessun allegato con quell'ID; un 425 Too Early indica che l'allegato è ancora in fase di archiviazione e la richiesta può essere riprovata tra poco.

Passi successivi

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Guarda la guidaGetting started with emailEsplora la funzionalitàEmailSegui il percorso di apprendimentoBuild your first integrationGuida all'implementazioneSend your first email
Prova l'esercitazione e ottieni un brief di implementazione