mail_attachments_selector

Odoo's document send wizard has two attachment widgets that work as a pair. One renders the list of files that will go out, including the invoice PDF that does not exist yet. This one is the control that lets a user add something of their own to that list.

It is more than a file input. Rather than creating an attachment record directly, it uploads through Odoo's messaging attachment service, against the thread of the document being sent. That means the upload goes through the same path as an attachment dropped on a chatter, with the same handling and the same server-side checks.

Once the upload completes, the widget appends an entry to the same structured field the list widget reads, carrying the new attachment's id, name and type, and marked as a manual upload. From that moment the list widget owns it, including the cleanup if the wizard is abandoned.

The reason to care about the routing is that it determines where the file ends up. Because the upload is made against the document's own thread, the attachment is attached to the invoice, not orphaned on a wizard record that disappears. Anything the customer receives is therefore also on the document afterwards, which is what an audit trail needs.

The manual flag is the other half of that. Files a user uploaded and then abandoned are deleted when the wizard closes unsaved, so a hesitant user does not leave debris behind. Files that survive a completed send stay attached, which is the correct asymmetry.

For anyone customizing the send flow, the pairing is the thing to preserve. Splitting the upload control from the list is what allows the wizard to place them in different parts of the form, but they share one field and one set of conventions, and replacing only one of them breaks the cleanup.

The core usage

<field name="mail_attachments_widget"
       widget="mail_attachments_selector"
       invisible="not display_attachments_widget"/>

Note that it points at the same field as the list widget. The two are two views of one value.

The fields it resolves the target from

# both read by literal name on the wizard
model     # the document's model
res_ids   # a JSON list; the first id is used

Only the first id is used to resolve the thread, which is why a batch send uploads against the first document.

The display half

<field name="mail_attachments_widget"
       widget="mail_attachments"/>

The paired widget that lists the files and handles removal and cleanup.

The upload path is worth following. When a file is chosen, the widget parses the record ids field, inserts a thread for the target model and the first id into the messaging store, wraps the uploaded data back into a file object, and hands it to the attachment upload service against that thread's composer. The service does the actual creation and returns the attachment.

The widget then builds a small entry with the attachment's id, name and mime type, marks it as not a placeholder and as a manual upload, and appends it to the field. Everything after that, including removal and the cleanup of abandoned uploads, belongs to the list widget reading the same field.

Two details are worth flagging. Only the first record id is used to resolve the thread, so on a batch send the upload is attached to the first document rather than to all of them. And the widget borrows the mail composer's own attachment selector template rather than defining its own, which keeps the control visually identical to the one in the chatter composer.

There is also a piece of dead code in the Odoo 19 file: the setup builds a set of x2many operations against an attachment relation and then never uses it. It does no harm, but it is a leftover from an earlier approach, and it disappears with the rename described below.

Odoo 20 is expected at Odoo Experience in Brussels, 24 to 26 September 2026. The development branch is unstable and this may still change; we re-verify the page after release.

The widget is renamed. On the development branch the file and the registered name both change to a send-specific name, and the wizard view is updated to match. A dedicated stylesheet appears alongside it, which suggests the control is being given its own presentation rather than borrowing the composer's.

A view still carrying the current name will not resolve on Odoo 20, so the upload control would silently disappear from a customized send wizard. Search custom views for this name before upgrading.