Bijlagen

Voeg bestanden toe aan een verzending door een attachments-array toe te voegen aan de POST /v1/email/messages-payload. Elke vermelding bevat de bytes van het bestand, base64-gecodeerd in content, plus een filename. Dezelfde array werkt op een batch-item. Volledige request- en responseschema's staan in de API-referentie.

Een verzending met één bijlage

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"
      }
    ]
  }'

De CLI leest het bestand en base64-codeert het voor je; via de API lever je de gecodeerde bytes zelf aan. De Go SDK neemt de ruwe bytes en codeert ze bij verzending.

content bevat de ruwe bestandsbytes, base64-gecodeerd. content_type is optioneel: als je het weglaat, leiden we het MIME-type af van de filename-extensie, met application/octet-stream als terugval voor een extensie die we niet herkennen. Al het andere aan de verzending werkt precies zoals bij e-mail verzenden: de 202, het asynchrone model, tags en metadata veranderen niet door de aanwezigheid van bijlagen.

De bijlagevelden

Veld	Type	Verplicht	Opmerkingen
filename	string	ja	1 tot 255 tekens; wordt getoond aan de ontvanger. Geen regeleinden of stuurtekens.
content	string	ja	Base64-gecodeerde bestandsbytes.
content_type	string	nee	MIME-type; wordt afgeleid van de bestandsnaamextensie als het ontbreekt.
content_id	string	nee	1 tot 128 tekens, [A-Za-z0-9._-]. Stel het in om het bestand inline weer te geven in plaats van als bijlage.

Een e-mail kan maximaal 20 bijlagen hebben (attachments is beperkt tot 20 items).

Inline afbeeldingen

Om een afbeelding in de HTML-body in te sluiten in plaats van bij te voegen, geef je de bijlage een content_id en verwijs je ernaar vanuit de markup met een cid:-URL:

Codevoorbeeld

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

De content_id is de koppeling tussen de cid:-verwijzing en de bijlage. Elke inline afbeelding heeft een unieke content_id nodig binnen de verzending; een duplicaat wordt geweigerd met een 422. Een bijlage zonder content_id wordt als gewone bestandsbijlage afgeleverd.

Groottebudget

We weigeren een verzending waarvan de geschatte gegenereerde berichtgrootte groter is dan 20 MB met een 413. De schatting is de HTML-body plus de tekstbody plus elke bijlage gemeten na base64-codering. Codering vergroot ruwe bytes met ongeveer 4/3, dus een bestand van 15 MB neemt op zichzelf al het volledige budget van 20 MB in beslag. Houd als vuistregel de totale ruwe bijlage-inhoud ruim onder 15 MB, zodat de body's en de MIME-verpakking er nog bij passen.

Ontvangende servers kunnen lagere groottelimieten hanteren. Een bericht dat Bird accepteert, kan alsnog bouncen als de server van de ontvanger de grootte weigert. Kies bijlagegroottes passend bij de mailboxproviders en organisaties waarnaar je verstuurt.

Zie Inkomende berichtgrootte voor ontvangen berichten.

Geblokkeerde bestandstypen

Uitvoerbare bestanden en scriptbijlagen worden bij validatie geweigerd met een 422, op basis van content_type of de bestandsnaamextensie. Geblokkeerde extensies zijn onder andere .exe, .dll, .msi, .bat, .cmd, .scr, .jar, .js, .vbs, .ps1, .sh, .hta en .lnk. Equivalente MIME-types zoals application/x-msdownload, application/java-archive en text/javascript worden ook geblokkeerd. Deze validatie is geen virusscanner. Om een geblokkeerd bestand te verspreiden, host je het achter een link.

In een batch

Elk item in een batchverzending kan een eigen attachments hebben, met hetzelfde veldcontract en hetzelfde budget van 20 MB per bericht. De geserialiseerde requestbody van de batch heeft daar bovenop een eigen limiet, die door base64-gecodeerde bijlagen snel wordt opgebruikt; zie batch verzenden voor de batchlimiet en hoe je daaromheen splitst.

Bijlagen lezen en downloaden

API-reads geven nooit bijlagebytes terug. GET /v1/email/messages/{message_id} retourneert alleen een attachments-array met metadata; elke vermelding bevat de bijlage-id, filename, content_type, size (gedecodeerde bytes) en inline:

Codevoorbeeld

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

Om de ruwe bytes terug te krijgen, roep je GET /v1/email/messages/{message_id}/attachments/{attachment_id} aan (referentie). Het streamt het bestand met het eigen contenttype en een Content-Disposition-header met de bestandsnaam. Twee voorwaarden gelden:

Contentopslag moet ingeschakeld zijn voor de werkruimte. Als opslag is uitgeschakeld, wordt er niets opgeslagen om te downloaden. Zie wat een 202 betekent.
Bijlagen worden 30 dagen bewaard na de verzending. Daarna retourneert de download 410 Gone.

Een 404 betekent dat het bericht geen opgeslagen content heeft of geen bijlage met dat ID; een 425 Too Early betekent dat de bijlage nog wordt opgeslagen en dat het verzoek even later opnieuw kan worden geprobeerd.

Volgende stappen

E-mail verzenden: de rest van de verzendpayload, inclusief ontvangers, content, tags en het asynchrone model
Batch verzenden: batches en waar bijlagen passen bij veel berichten
API-referentie: een bericht aanmaken: het volledige requestschema, inclusief attachments
API-referentie: een bijlage downloaden: het ophaalendpoint en de statuscodes

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Bekijk de gidsGetting started with email Ontdek de mogelijkheidEmail Volg het leerpadBuild your first integration ImplementatiegidsSend your first email

Probeer de oefening en ontvang een implementatieoverzicht