Attachment Node: Single vs Multiple Mode

A reference for choosing between Single mode and Multiple mode on the Spojit Attachment node, what each output shape looks like, and how to Loop over the attachments list when a message carries more than one file.

Overview

The Attachment node fetches the actual bytes of files that arrived with a Mailhook trigger. The Mailhook trigger only hands you lightweight references for each attachment (id, filename, and contentType); the bytes are pulled on demand by the Attachment node so your workflow stays fast and only loads what it needs. The single most important setting on the node is Mode, because it decides whether you get one file back as a single object or a list of files you can iterate over.

Mentally, picture two outcomes. In Single mode you are saying "give me the one file I care about" and the node returns a flat object you can wire straight into a downstream node. In Multiple mode you are saying "give me every file that matches" and the node returns a list plus a count, which you then walk with a Loop node. Getting this choice right up front avoids template errors later, because the variable paths you reference differ between the two shapes. The Attachment node is only valid inside Mailhook workflows: the Spojit designer refuses to save it unless the trigger is a Mailhook.

Before You Start

Your workflow must use a Mailhook trigger. See Setting Up a Mailhook Trigger to generate the address.
Decide the matching criteria for the files you want: a Content type filter (for example application/pdf or image/*), a Filename pattern glob (for example *.pdf or invoice-*.csv), or an exact Attachment ID.
Keep the limits in mind: up to 10 MB per attachment and 25 MB per run by default. Received emails are retained for 30 days.

Choosing the Mode

Open the Attachment node, find the Mode field, and pick one of two values.

Single: returns the first attachment that matches your filters as a single object. Use this when a message carries exactly one relevant file, or when you only ever need the first match (for example an invoice PDF, or a single CSV export).
Multiple: returns every attachment that matches your filters as a list, along with a count and a total byte size. Use this when a message may carry several files and you want to process each one (for example a batch of receipts, or several images).

If you are unsure how many files arrive, start with Multiple and Loop over the list. A list of one element is still valid, whereas Single mode silently ignores any additional matches.

Output Shape in Single Mode

In Single mode the node binds a flat object to your output variable. Assuming the node's output variable is attachment, the shape is:

{
  "filename": "invoice-1042.pdf",
  "contentType": "application/pdf",
  "size": 184320,
  "content": "JVBERi0xLjQK..."
}

The content field is the file body encoded as base64. You reference it directly, for example {{ attachment.content }}, and feed it straight into a downstream node. Common destinations are the Send Email node's attachment input or the Knowledge node's Document Input field.

Output Shape in Multiple Mode

In Multiple mode the node binds a list wrapped in a small summary object. Assuming the output variable is attachment, the shape is:

{
  "attachments": [
    { "filename": "receipt-1.pdf", "contentType": "application/pdf", "size": 51200, "content": "JVBER..." },
    { "filename": "receipt-2.pdf", "contentType": "application/pdf", "size": 47104, "content": "JVBER..." }
  ],
  "count": 2,
  "totalBytes": 98304
}

Each element of attachments has the same fields as a Single mode result (filename, contentType, size, content). The count field tells you how many files matched, and totalBytes is their combined size, which is handy for a Condition guard before doing heavy work.

Looping Over the Attachments List

Multiple mode pairs naturally with a Loop node set to ForEach.

Add a Loop node after the Attachment node and connect them.
Point the Loop's collection at {{ attachment.attachments }} (the list inside the output object, not the wrapper itself).
Inside the loop body, reference the current item's bytes. For each iteration you have access to fields like content, filename, and contentType on the loop's current item, which you then pass into a Knowledge node, a Send Email node, or a Connector node that uploads the file.

If you only need a quick gate, add a Condition node first that checks {{ attachment.count }} is greater than zero before entering the loop. For the mechanics of iteration, see Using Loop Nodes.

Tips

Tighten your match before changing modes. A Filename pattern like *.pdf combined with a Content type of application/pdf keeps Single mode landing on the file you actually want.
An exact Attachment ID ignores the other filters entirely. Use it when the Mailhook output already gave you a specific reference and you want one precise file.
Turn on Fail if no attachment matches when a missing file should stop the run. It is off by default, so without it a no-match Single result is empty and a no-match Multiple result has count of 0.
Ask Miraxa, the intelligent layer across your automation, to scaffold the pattern: for example "Add an Attachment node in Multiple mode that matches *.pdf, then Loop over the attachments and embed each into a Knowledge collection." You can then fine-tune the fields in the properties panel.

Common Pitfalls

Using a Single mode variable path in Multiple mode. {{ attachment.content }} only works in Single mode. In Multiple mode the bytes live at {{ attachment.attachments }} per item inside a Loop, not on the top-level object.
Pointing a Loop at the wrapper object. Set the Loop collection to {{ attachment.attachments }}, not {{ attachment }}, or the loop has nothing to iterate.
Hitting the size limits. Multiple mode can pull several files at once and a run is capped at 25 MB by default. Use Min/Max size filters or check {{ attachment.totalBytes }} to avoid loading more than you need.
Adding the node outside a Mailhook workflow. The Attachment node is Mailhook-only and the Spojit designer will not save it with any other trigger type.