Anhänge

Hängen Sie Dateien an einen Versand an, indem Sie ein attachments-Array zum POST /v1/email/messages-Payload hinzufügen. Jeder Eintrag enthält die Bytes der Datei base64-kodiert in content sowie einen filename. Dasselbe Array funktioniert bei einem Batch-Element. Vollständige Request- und Response-Schemas finden Sie in der API-Referenz.

Ein Versand mit einem Anhang

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",
    },
  ],
});

client.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",
        }
    ],
)

_, err := client.Email.Send(context.Background(), bird.EmailSendParams{
	From:    "hello@yourdomain.com",
	To:      []string{"delivered@messagebird.dev"},
	Subject: "Your invoice",
	HTML:    "<p>Thanks for your order. Your invoice is attached.</p>",
	Attachments: []bird.EmailAttachment{{
		Filename:    "invoice.pdf",
		Content:     pdfBytes,
		ContentType: bird.String("application/pdf"),
	}},
})

$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: [
        (new EmailAttachment())
            ->setFilename('invoice.pdf')
            ->setContent('JVBERi0xLjcKJ...')
            ->setContentType('application/pdf'),
    ],
);

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>' \
  --attach ./invoice.pdf

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "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"
      }
    ]
  }'

Das CLI liest die Datei und base64-kodiert sie für Sie; über die API liefern Sie die kodierten Bytes selbst. Das Go-SDK nimmt die Roh-Bytes und kodiert sie beim Senden.

content sind die rohen Datei-Bytes, base64-kodiert. content_type ist optional: Wenn Sie es weglassen, leiten wir den MIME-Typ aus der filename-Erweiterung ab und verwenden application/octet-stream als Fallback für nicht erkannte Erweiterungen. Alles andere am Versand funktioniert genau wie beim E-Mail-Versand: 202, das asynchrone Modell, Tags und Metadaten bleiben durch Anhänge unverändert.

Die Anhang-Felder

Feld	Typ	Pflicht	Hinweise
filename	string	ja	1 bis 255 Zeichen; wird dem Empfänger angezeigt. Keine Zeilenumbrüche oder Steuerzeichen.
content	string	ja	Base64-kodierte Datei-Bytes.
content_type	string	nein	MIME-Typ; wird aus der Dateinamen-Erweiterung abgeleitet, wenn nicht angegeben.
content_id	string	nein	1 bis 128 Zeichen, [A-Za-z0-9._-]. Setzen Sie es, um die Datei inline statt als Anhang darzustellen.

Eine E-Mail kann bis zu 20 Anhänge haben (attachments ist auf 20 Einträge begrenzt).

Inline-Bilder

Um ein Bild in den HTML-Body einzubetten statt es anzuhängen, geben Sie dem Anhang eine content_id und referenzieren Sie es im Markup mit einer cid:-URL:

Codebeispiel

{
  "html": "<p>Welcome aboard!</p><img src=\"cid:welcome-banner\"/>",
  "attachments": [
    {
      "filename": "banner.png",
      "content": "iVBORw0KGgoAAAANS...",
      "content_type": "image/png",
      "content_id": "welcome-banner"
    }
  ]
}

Die content_id ist die Verknüpfung zwischen der cid:-Referenz und dem Anhang. Jedes Inline-Bild benötigt eine eindeutige content_id innerhalb des Versands; ein Duplikat wird mit einem 422 abgelehnt. Ein Anhang ohne content_id wird als regulärer Dateianhang zugestellt.

Größenbudget

Wir lehnen einen Versand ab, dessen geschätzte generierte Nachrichtengröße 20 MB überschreitet, mit einem 413. Die Schätzung umfasst den HTML-Body plus den Text-Body plus alle Anhänge gemessen nach der Base64-Kodierung. Die Kodierung bläht Roh-Bytes um etwa 4/3 auf, sodass eine 15-MB-Datei allein bereits das gesamte 20-MB-Budget verbraucht. Als Faustregel: Halten Sie den gesamten rohen Anhang-Inhalt deutlich unter 15 MB, damit die Bodys und das MIME-Wrapping noch Platz haben.

Empfangende Server können niedrigere Größenlimits anwenden. Eine Nachricht, die Bird akzeptiert, kann trotzdem bouncen, wenn der Server des Empfängers die Größe ablehnt. Wählen Sie Anhanggrößen passend zu den Mailbox-Anbietern und Organisationen, an die Sie senden.

Für empfangene Nachrichten siehe Eingehende Nachrichtengröße.

Blockierte Dateitypen

Ausführbare Dateien und Skript-Anhänge werden bei der Validierung mit einem 422 abgelehnt, basierend auf content_type oder der Dateinamen-Erweiterung. Blockierte Erweiterungen umfassen .exe, .dll, .msi, .bat, .cmd, .scr, .jar, .js, .vbs, .ps1, .sh, .hta und .lnk. Entsprechende MIME-Typen wie application/x-msdownload, application/java-archive und text/javascript werden ebenfalls blockiert. Diese Validierung ist kein Virenscanner. Um eine blockierte Datei weiterzugeben, hosten Sie sie hinter einem Link.

In einem Batch

Jedes Element in einem Batch-Versand kann eigene attachments haben, mit demselben Feldvertrag und demselben 20-MB-Budget pro Nachricht. Der serialisierte Request-Body des Batches hat zusätzlich ein eigenes Limit, das base64-kodierte Anhänge schnell aufbrauchen; siehe Batch-Versand für das Batch-Level-Limit und wie Sie darum herum aufteilen.

Anhänge lesen und herunterladen

API-Lesevorgänge geben niemals Anhang-Bytes zurück. GET /v1/email/messages/{message_id} liefert ein attachments-Array nur mit Metadaten; jeder Eintrag enthält id, filename, content_type, size (dekodierte Bytes) und inline des Anhangs:

Codebeispiel

{
  "attachments": [
    {
      "id": "ea_019c...",
      "filename": "invoice.pdf",
      "content_type": "application/pdf",
      "size": 215432,
      "inline": false
    }
  ]
}

Um die Roh-Bytes zurückzubekommen, rufen Sie GET /v1/email/messages/{message_id}/attachments/{attachment_id} auf (Referenz). Der Endpunkt streamt die Datei mit ihrem eigenen Content-Type und einem Content-Disposition-Header, der den Dateinamen enthält. Zwei Bedingungen gelten:

Inhaltsspeicherung muss aktiviert sein für den Workspace. Bei deaktivierter Speicherung wird nichts gespeichert, das heruntergeladen werden könnte. Siehe Was ein 202 bedeutet.
Anhänge werden 30 Tage nach dem Versand aufbewahrt. Danach gibt der Download 410 Gone zurück.

Ein 404 bedeutet, dass die Nachricht keinen gespeicherten Inhalt oder keinen Anhang mit dieser ID hat; ein 425 Too Early bedeutet, dass der Anhang noch gespeichert wird und die Anfrage in Kürze erneut versucht werden kann.

Nächste Schritte

E-Mail-Versand: der Rest des Versand-Payloads, einschließlich Empfänger, Inhalt, Tags und das asynchrone Modell
Batch-Versand: Batches und wo Anhänge bei vielen Nachrichten einzuordnen sind
API-Referenz: Nachricht erstellen: das vollständige Request-Schema, einschließlich attachments
API-Referenz: Anhang herunterladen: der Abruf-Endpunkt und seine Statuscodes

Verwandte Ressourcen