---
title: "Bundling Attachments"
canonical: "https://test.abhinandan.one/node-sdk-attachment-bundling"
markdown_url: "https://test.abhinandan.one/node-sdk-attachment-bundling.md"
publisher: "Primitive SDKs"
kind: "guide"
content_type: "reference"
category: "Node.js SDK"
description: "Bundle attachments extracted from a parsed email into a single content-addressed tar.gz archive using the Node.js SDK's parser subpath."
keywords: ["bundleAttachments", "tar.gz attachment bundle", "content-addressed archive", "ParsedData attachments", "parseEmail attachments", "@primitivedotdev/sdk/parser"]
last_modified: "2026-08-21T18:22:43.359885+00:00"
published_at: "2026-08-11T18:54:53.453+00:00"
sections:
  - {anchor: "where-bundling-lives-in-the-sdk", title: "Where bundling lives in the SDK"}
  - {anchor: "what-you-need-first", title: "What you need first"}
  - {anchor: "bundle-versus-primitive-payloads", title: "Bundle versus Primitive Payloads"}
  - {anchor: "next-steps", title: "Next steps"}
---

> Documentation index: https://test.abhinandan.one/llms.txt

# 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.

> **Note:** 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](https://test.abhinandan.one/node-sdk-payloads.md), 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.

> **Warning:** 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)](https://test.abhinandan.one/node-sdk-parsing-email.md) 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](https://test.abhinandan.one/node-sdk-payloads.md) |
| Attach small files directly on `send`/`reply`/`forward` | Inline `attachments` with `content_base64` ([Sending, Replying, and Forwarding Email](https://test.abhinandan.one/node-sdk-sending-email.md)) |

> **Tip:** 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](https://test.abhinandan.one/node-sdk-payloads.md).