Załączniki

Dołącz pliki do wysyłki, dodając tablicę attachments do payloadu POST /v1/email/messages. Każdy wpis zawiera bajty pliku zakodowane w base64 w polu content oraz filename. Ta sama tablica działa w elemencie wysyłki zbiorczej. Pełne schematy żądania i odpowiedzi znajdziesz w dokumentacji API.

Wysyłka z jednym załącznikiem

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

CLI odczytuje plik i koduje go w base64 za Ciebie; przez API podajesz zakodowane bajty samodzielnie. SDK w Go przyjmuje surowe bajty i koduje je podczas transmisji.

content to surowe bajty pliku zakodowane w base64. content_type jest opcjonalne: jeśli je pominiesz, typ MIME zostanie wywnioskowany z rozszerzenia filename, a w przypadku nierozpoznanego rozszerzenia użyty zostanie application/octet-stream. Cała reszta wysyłki działa dokładnie tak jak w przypadku wysyłania e-maili: 202, model asynchroniczny, tagi i metadane nie zmieniają się po dodaniu załączników.

Pola załącznika

Pole	Typ	Wymagane	Uwagi
filename	string	tak	Od 1 do 255 znaków; wyświetlane odbiorcy. Bez znaków nowej linii ani znaków sterujących.
content	string	tak	Bajty pliku zakodowane w Base64.
content_type	string	nie	Typ MIME; wyznaczany z rozszerzenia nazwy pliku, jeśli pominięty.
content_id	string	nie	Od 1 do 128 znaków, [A-Za-z0-9._-]. Ustaw, aby plik był renderowany inline zamiast jako załącznik.

E-mail może mieć maksymalnie 20 załączników (tablica attachments jest ograniczona do 20 elementów).

Obrazy inline

Aby osadzić obraz w treści HTML zamiast dołączać go jako załącznik, nadaj załącznikowi content_id i odwołaj się do niego w znacznikach za pomocą URL-a cid::

Przykład kodu

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

content_id łączy odwołanie cid: z załącznikiem. Każdy obraz inline wymaga unikalnego content_id w ramach wysyłki; duplikat jest odrzucany z błędem 422. Załącznik bez content_id jest dostarczany jako zwykły załącznik plikowy.

Budżet rozmiaru

Odrzucamy wysyłkę, której szacowany rozmiar wygenerowanej wiadomości przekracza 20 MB, zwracając 413. Szacunek obejmuje treść HTML, treść tekstową oraz każdy załącznik mierzony po zakodowaniu w base64. Kodowanie zwiększa surowe bajty mniej więcej o 4/3, więc plik o rozmiarze 15 MB sam wypełnia cały budżet 20 MB. Orientacyjnie utrzymuj łączną surową zawartość załączników znacznie poniżej 15 MB, aby treści i opakowanie MIME nadal się zmieściły.

Serwery odbierające mogą stosować niższe limity rozmiaru. Wiadomość zaakceptowana przez Bird może nadal zostać odrzucona, jeśli serwer odbiorcy nie przyjmie jej rozmiaru. Dobieraj rozmiary załączników odpowiednio do dostawców poczty i organizacji, do których wysyłasz.

W przypadku wiadomości przychodzących zobacz Rozmiar wiadomości przychodzącej.

Zablokowane typy plików

Załączniki wykonywalne i skryptowe są odrzucane na etapie walidacji z błędem 422 na podstawie content_type lub rozszerzenia nazwy pliku. Zablokowane rozszerzenia to m.in. .exe, .dll, .msi, .bat, .cmd, .scr, .jar, .js, .vbs, .ps1, .sh, .hta i .lnk. Równoważne typy MIME, takie jak application/x-msdownload, application/java-archive i text/javascript, również są blokowane. Ta walidacja nie jest skanerem antywirusowym. Aby udostępnić zablokowany plik, umieść go za linkiem.

W wysyłce zbiorczej

Każdy element wysyłki zbiorczej może mieć własną tablicę attachments z takim samym kontraktem pól i takim samym budżetem 20 MB na wiadomość. Zserializowane ciało żądania wysyłki zbiorczej ma dodatkowo własny limit, który załączniki zakodowane w base64 szybko wyczerpują; zobacz wysyłkę zbiorczą, aby poznać limit na poziomie batcha i sposób podziału.

Odczytywanie i pobieranie załączników

Odczyty API nigdy nie zwracają bajtów załączników. GET /v1/email/messages/{message_id} zwraca tablicę attachments zawierającą wyłącznie metadane; każdy wpis zawiera id, filename, content_type, size (zdekodowane bajty) i inline załącznika:

Przykład kodu

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

Aby pobrać surowe bajty, wywołaj GET /v1/email/messages/{message_id}/attachments/{attachment_id} (dokumentacja). Strumieniuje plik z odpowiednim typem zawartości i nagłówkiem Content-Disposition zawierającym nazwę pliku. Dwa warunki muszą być spełnione:

Przechowywanie treści musi być włączone dla obszaru roboczego. Przy wyłączonym przechowywaniu nic nie jest zapisywane do pobrania. Zobacz co oznacza odpowiedź 202.
Załączniki są przechowywane przez 30 dni od wysyłki. Po tym czasie pobieranie zwraca 410 Gone.

404 oznacza, że wiadomość nie ma zapisanej treści lub nie ma załącznika o podanym ID; 425 Too Early oznacza, że załącznik jest jeszcze zapisywany i żądanie można ponowić za chwilę.

Następne kroki

Wysyłanie e-maili: reszta payloadu wysyłki, w tym odbiorcy, treść, tagi i model asynchroniczny
Wysyłka zbiorcza: batche i miejsce załączników w wielu wiadomościach
Dokumentacja API: tworzenie wiadomości: pełny schemat żądania, w tym attachments
Dokumentacja API: pobieranie załącznika: endpoint pobierania i jego kody statusu

Powiązane zasoby

Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.

Obejrzyj przewodnikGetting started with email Poznaj możliwościEmail Podążaj ścieżką naukiBuild your first integration Przewodnik wdrożeniowySend your first email

Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy