mail_attachments

Sending an invoice from Odoo attaches more than one thing. There is the invoice PDF, which does not exist yet when the wizard opens, because it is generated at send time. There may be an electronic invoicing file. There may be terms and conditions the company always attaches. And the user may want to add something of their own.

Those are different kinds of entry with different rules, and a plain attachment relation cannot express them. So the wizard uses a structured field holding a list of entries, each flagged as a placeholder for a document to be generated, as protected from deletion, or as a manual upload. This widget renders that list and manages the flags.

Visually it is a list of files with an upload button and a remove icon on each. What is behind each remove icon depends on the entry: some are truly removed, some are only marked to be skipped, and some queue a real deletion for later.

The behavior worth knowing about is the cleanup. Uploading a file to a wizard creates a real attachment record immediately, so abandoning the wizard would otherwise leave orphan files in the database. This widget deletes those on close, but only when the wizard was never saved, which is the correct rule: a saved wizard means the user meant it.

The three-way distinction also prevents a recurring support question. Removing the invoice PDF from the list does not stop the invoice from having a PDF; it stops that document being attached to this send. Marking the entry to be skipped rather than deleting it is what makes that possible, and it is why the entry sometimes reappears the next time the wizard opens.

The tooltip mechanism is the small quality touch. When a document cannot be included, for example because the format is not supported for that customer's electronic invoicing route, the reason appears on the file itself rather than in an error after sending.

The core usage

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

No options. The structure in the field decides which entries appear and how each one behaves when removed.

The entry shape

{
  "id": 4211,
  "name": "INV_2026_0007.pdf",
  "placeholder": true,
  "protect_from_deletion": false,
  "manual": false
}

The three flags are what the remove handler branches on. A placeholder is a document that will be generated at send time.

The tooltip companion

# on the wizard model, read by literal name
attachments_not_supported = fields.Json(...)
# { attachment_id: "reason shown as a tooltip" }

Optional in practice: without it the list simply shows no explanations.

The remove handler is where the widget's rules live. It walks the current list and, for the entry being removed, branches on two flags. If the entry is a placeholder or is protected from deletion, a copy of it is kept in the list with a skip marker set, so the server knows not to include it in this send. Otherwise the entry is dropped from the list and its attachment identifier is added to a set of things to delete. The rebuilt list is then written back to the field.

Nothing is deleted at that moment. The deletion set is drained when the component unmounts, which is what makes the cleanup safe: closing the wizard, navigating away or the dialog being destroyed all trigger it, and a user who changes their mind before then has simply changed a local list.

The unmount handler adds one more rule. If the wizard record has no database identifier, meaning it was never saved, every entry flagged as a manual upload is added to the deletion set as well. That is what stops abandoned uploads accumulating. A saved wizard keeps its uploads, because the user committed to them.

The tooltips are assembled by deep-copying the list and, for each entry whose identifier appears in the companion mapping, attaching the explanation. Deep-copying rather than mutating matters here: the rendered list is a throwaway view of the data, and the field itself keeps only the real entries.

Odoo 19 simplified the file: several presentation helpers, for building download URLs and reading file extensions, were moved out, and the two data accessors became getters. The behavior described above is unchanged from Odoo 17.

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

Byte-identical. The file on the development branch matches Odoo 19 exactly, including the three flags, the deletion queue and the unsaved-wizard cleanup. Any change to how attachments are presented will come from the template.