Allegati

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:

Allega un file in base64

Leggi il file, codificalo in base64 e invialo con il suo tipo MIME.

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"from\": \"Acme Billing <billing@acme.com>\",
    \"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\"
    }]
  }"

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 <billing@acme.com>',
  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',
    },
  ],
});

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 <billing@acme.com>",
    "to": "ada@example.com",
    "subject": "Invoice INV-1042",
    "text": "Your invoice is attached.",
    "attachments": [{
        "filename": "INV-1042.pdf",
        "content": pdf,
        "content_type": "application/pdf",
    }],
})

$emailit = Emailit::client(getenv('EMAILIT_API_KEY'));

$emailit->emails()->send([
    'from' => 'Acme Billing <billing@acme.com>',
    '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.

{
  "from": "Acme Billing <billing@acme.com>",
  "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.

{
  "from": "Acme <hello@acme.com>",
  "to": "ada@example.com",
  "subject": "Your weekly report",
  "html": "<p><img src=\"cid:chart-week-40\" alt=\"Weekly signups\" width=\"600\"></p>",
  "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

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.

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

Risoluzione dei problemi

Vedi anche

• Invia un’email
• Invia un’email nel riferimento API
• Conservazione dei dati