Lampiran

Lampirkan file ke pengiriman dengan menambahkan array attachments ke payload POST /v1/email/messages. Setiap entri berisi byte file yang di-base64-encode di content, beserta filename. Array yang sama berlaku pada item batch. Skema request dan response lengkap ada di referensi API.

Pengiriman dengan satu lampiran

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 membaca file dan melakukan base64-encode untuk Anda; melalui API Anda menyediakan byte yang sudah di-encode sendiri. SDK Go menerima byte mentah dan melakukan encode saat pengiriman.

content adalah byte file mentah yang di-base64-encode. content_type bersifat opsional: jika Anda mengosongkannya, kami menyimpulkan MIME type dari ekstensi filename, dan menggunakan application/octet-stream jika ekstensinya tidak dikenali. Semua hal lain tentang pengiriman bekerja persis seperti pada mengirim email: 202, model async, tag, dan metadata tidak berubah dengan adanya lampiran.

Field lampiran

Field	Tipe	Wajib	Catatan
filename	string	ya	1 sampai 255 karakter; ditampilkan kepada penerima. Tidak boleh ada line break atau karakter kontrol.
content	string	ya	Byte file yang di-encode Base64.
content_type	string	tidak	MIME type; disimpulkan dari ekstensi nama file jika tidak diisi.
content_id	string	tidak	1 sampai 128 karakter, [A-Za-z0-9._-]. Isi untuk merender file secara inline, bukan sebagai lampiran.

Sebuah email dapat memiliki maksimal 20 lampiran (attachments dibatasi 20 item).

Gambar inline

Untuk menyematkan gambar di body HTML alih-alih melampirkannya, berikan lampiran tersebut content_id dan referensikan dari markup dengan URL cid::

Contoh kode

{
  "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 adalah penghubung antara referensi cid: dan lampiran. Setiap gambar inline memerlukan content_id yang unik dalam satu pengiriman; duplikat akan ditolak dengan 422. Lampiran tanpa content_id dikirim sebagai lampiran file biasa.

Batas ukuran

Kami menolak pengiriman yang estimasi ukuran pesan yang dihasilkan melebihi 20 MB dengan 413. Estimasi dihitung dari body HTML ditambah body teks ditambah setiap lampiran yang diukur setelah base64 encoding. Encoding memperbesar byte mentah sekitar 4/3, sehingga file 15 MB saja sudah menghabiskan seluruh batas 20 MB. Sebagai panduan, jaga total konten lampiran mentah jauh di bawah 15 MB agar body dan pembungkus MIME masih muat.

Server penerima dapat menerapkan batas ukuran yang lebih rendah. Pesan yang diterima Bird tetap bisa bounce jika server penerima menolak ukurannya. Sesuaikan ukuran lampiran dengan penyedia kotak masuk dan organisasi tujuan pengiriman Anda.

Untuk pesan yang diterima, lihat Ukuran pesan masuk.

Tipe file yang diblokir

Lampiran executable dan script ditolak saat validasi dengan 422, berdasarkan content_type atau ekstensi nama file. Ekstensi yang diblokir meliputi .exe, .dll, .msi, .bat, .cmd, .scr, .jar, .js, .vbs, .ps1, .sh, .hta, dan .lnk. MIME type yang setara seperti application/x-msdownload, application/java-archive, dan text/javascript juga diblokir. Validasi ini bukan pemindai virus. Untuk mendistribusikan file yang diblokir, hosting file tersebut di balik sebuah tautan.

Dalam batch

Setiap item dalam pengiriman batch dapat memiliki attachments sendiri, dengan kontrak field yang sama dan batas 20 MB per pesan yang sama. Body request batch yang diserialisasi memiliki batas tersendiri di atasnya, yang cepat terpakai oleh lampiran base64-encoded; lihat pengiriman batch untuk batas level batch dan cara membaginya.

Membaca dan mengunduh lampiran

Pembacaan API tidak pernah mengembalikan byte lampiran. GET /v1/email/messages/{message_id} mengembalikan array attachments berisi metadata saja; setiap entri memiliki id, filename, content_type, size (byte yang di-decode), dan inline lampiran:

Contoh kode

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

Untuk mendapatkan byte mentah kembali, panggil GET /v1/email/messages/{message_id}/attachments/{attachment_id} (referensi). Endpoint ini men-stream file dengan content type-nya sendiri dan header Content-Disposition yang berisi nama file. Dua syarat yang harus dipenuhi:

Penyimpanan konten harus diaktifkan untuk workspace. Jika penyimpanan dinonaktifkan, tidak ada yang disimpan untuk diunduh. Lihat arti respons 202.
Lampiran disimpan selama 30 hari setelah pengiriman. Setelah itu, unduhan mengembalikan 410 Gone.

404 berarti pesan tidak memiliki konten tersimpan atau tidak ada lampiran dengan ID tersebut; 425 Too Early berarti lampiran masih dalam proses penyimpanan dan permintaan dapat dicoba lagi sebentar kemudian.

Langkah selanjutnya

Mengirim email: sisa payload pengiriman, termasuk penerima, konten, tag, dan model async
Pengiriman batch: batch dan posisi lampiran di banyak pesan
Referensi API: membuat pesan: skema request lengkap, termasuk attachments
Referensi API: mengunduh lampiran: endpoint pengambilan dan kode statusnya

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Tonton panduannyaGetting started with email Jelajahi kemampuannyaEmail Ikuti jalur pembelajaranBuild your first integration Panduan implementasiSend your first email

Coba praktiknya dan dapatkan ringkasan implementasi