Bundling Attachments
Package the downloadable attachments extracted from a parsed email into a single content-addressed tar.gz archive, useful when you need one artifact to store or hand off instead of many individual files.
Bundling packages downloadable attachments extracted from a parsed email into a single content-addressed tar.gz archive for storage. Reach for it when you want one artifact to archive or hand off instead of many loose attachment files.
Bundling is for attachments you have already pulled out of a parsed email. It is not how you send or receive large attachments over the wire, that is Primitive Payloads, which streams content-addressed, end-to-end-encrypted objects with pushFile, pushBytes, and pullFile.
Where bundling lives in the SDK#
Bundling is part of the Node-only parser surface of @primitivedotdev/sdk, alongside the raw MIME helpers. The contract and parser subpaths are Node-only modules, so they are not available in the Workers-safe /api entry point used inside Primitive Functions.
Do not import the parser subpath into a Primitive Function handler. Function handlers should import from @primitivedotdev/sdk/api, which is the Workers-safe entry point.
What you need first#
Bundling consumes attachments that have already been extracted from a raw MIME message, so parse the message before you bundle. Parsing Raw Email (.eml) covers the parser subpath and the address helpers it exports.
Bundle versus Primitive Payloads#
Bundling produces a stored archive; Primitive Payloads delivers a large attachment as part of an email. Both are content-addressed, but they solve different problems.
| Goal | Use |
|---|---|
| Archive several already-extracted attachments as one file | Bundling (parser subpath) |
| Deliver an attachment larger than the inline cap on a send | Primitive Payloads |
Attach small files directly on send/reply/forward | Inline attachments with content_base64 (Sending, Replying, and Forwarding Email) |
If the file needs to reach the recipient rather than your own storage, skip bundling. Upload it with pushFile or pushBytes and deliver it by reference, as described in Primitive Payloads: Streaming Large Attachments.
Next steps#
Produce the parsed message that bundling consumes.
Primitive Payloads: Streaming Large AttachmentsUpload and reference large attachments instead of bundling them.
Sending, Replying, and Forwarding EmailAttach files inline or by reference when sending outbound mail.
Node.js SDK Agent GuideLook up every import path and method signature in one dense reference.
Was this page helpful?