How to Create an Automated Mail Merge with Images in LibreOffice Writer

You can build a perfectly good LibreOffice Writer mail merge for names, addresses, dates, and other text fields, then discover that the moment each recipient needs a different photo, signature, product image, QR code, or badge, the simple workflow stops being simple. The reason is important: Writer’s documented mail merge fields are database fields used as text placeholders. LibreOffice also supports embedded and linked graphics, but its current help does not document a native “mail merge image field” that automatically replaces an image from a file-path column for every record.

That leaves two practical choices. If every merged document uses the same logo or background image, use normal Writer mail merge and keep that image fixed in the template. If the image must change for every row, the more controllable approach is to keep the text and image data in Calc, reserve a named graphic object in the Writer template, and automate the merge with a LibreOffice Basic macro. This guide uses that second approach.

The instructions are aligned with LibreOffice 26.2 documentation available in 2026. Menus can differ slightly in other releases or on macOS. LibreOffice’s current Writer guide states that images can be embedded or linked, while the UNO API exposes Writer graphic objects through XTextGraphicObjectsSupplier and lets automation set a graphic from an external URL. Those pieces make a per-record image workflow possible even though the standard Mail Merge Wizard does not expose it as a dedicated image field.

Choose the right workflow before you start

If your use case is only a fixed company logo, stop here and use the normal LibreOffice form-letter workflow. The rest of this article is for variable images.

Step 1: Prepare a clean Calc data source

Create a Calc sheet with one header row and one record per row. Keep image references in their own column. A practical layout is CustomerID, FirstName, LastName, Email, ImagePath, and OutputName.

Use absolute paths while you are building and testing the merge. They are less portable, but they remove ambiguity. For example, C:\MailMerge\Imageslice.jpg on Windows or /home/user/mailmerge/images/alice.jpg on Linux is easier to diagnose than a relative path whose base directory changes depending on how the document was opened.

Do not mix Windows and Linux path formats in the same production file. The mixed examples in the illustration simply show the type of value the column holds. Your real data source should use paths valid on the machine that runs the merge.

A good OutputName column also prevents filename collisions. Prefer a stable ID or sanitized name rather than an email address or arbitrary free text. If the same value appears twice, decide in advance whether the macro should overwrite, append a suffix, or fail.

Step 2: Confirm that Writer can read the records

Writer’s standard mail merge uses a registered data source. You can use the Mail Merge Wizard, an address data source, or the data-source browser. Current LibreOffice help documents Tools > Mail Merge Wizard and also allows database fields to be inserted through Insert > Field > More Fields > Database. See the official Database fields reference.

This check is useful even if the final macro reads the spreadsheet directly. It catches common problems early: the wrong sheet, unexpected header names, empty records, or a spreadsheet that was moved after registration.

For ordinary text-only mail merge, you can drag a column heading into the document or insert a mail merge field from the Database tab. The official Writer help confirms that these fields are replaced with database content when the merge runs. For the variable image, however, do not assume that dragging ImagePath into the page will turn the path into an image. It will remain data unless code interprets it and updates a graphic object.

Step 3: Build the Writer template and name the image placeholder

Create the letter, certificate, badge, or report layout in Writer. For the text values, either use normal mail merge fields or use unmistakable tokens such as {FirstName}, {LastName}, and {CustomerID} if your macro will replace them itself.

Next insert a sample image where the variable image should appear. Set the desired size, wrapping, and anchor before automating it. LibreOffice documents image sizing, positioning, anchoring, wrapping, and linked-image behavior in the current Writer 26.2 Images and Graphics chapter.

Asigne al objeto gráfico un nombre estable, como MergeImage. El cuadro de diálogo de propiedades exacto puede variar según la versión, así que si no está seguro de qué objeto expone Writer, utilice Herramientas > Herramientas de desarrollo . Las Herramientas de desarrollo de LibreOffice pueden inspeccionar objetos gráficos, propiedades, métodos e interfaces en el documento actual. Esto la convierte en una herramienta de diagnóstico más segura que intentar adivinar el nombre interno de un objeto.

Para un diseño predecible, utilice la misma relación de aspecto para todas las imágenes de origen o decida cómo desea recortarlas. Writer puede redimensionar un gráfico a las dimensiones del marcador de posición, pero una foto vertical insertada en un marco ancho con forma de banner seguirá viéndose mal a menos que normalice los archivos previamente.

Paso 4: Automatizar la exportación de imágenes y documentos variables.

La operación de automatización clave es sencilla: abrir la plantilla, reemplazar los marcadores de posición de texto, encontrar el objeto gráfico con nombre, cargar el archivo de imagen de la fila en ese objeto y, a continuación, exportar el resultado. La API UNO de LibreOffice documenta getGraphicObjects()el acceso a gráficos incrustados y vinculados, así como el TextGraphicObjectservicio para propiedades gráficas. La GraphicURLpropiedad está obsoleta para el almacenamiento general de objetos en favor de Graphic, pero la API actual indica explícitamente que establecer una URL externa carga esa imagen en el objeto gráfico. Esto resulta conveniente para una macro básica simple que utilice rutas de archivo locales.

El siguiente ejemplo es intencionadamente sencillo. Modifique las tres rutas, el nombre de la hoja, los índices de columna y los nombres de los marcadores de posición para que coincidan con sus propios archivos. Pruébelo con dos registros antes de procesar un lote grande.

Sub MailMergeWithImages()
    Dim calcDoc As Object, sheet As Object, doc As Object
    Dim graphics As Object, imageObj As Object
    Dim row As Long
    Dim firstName As String, lastName As String
    Dim imagePath As String, outputName As String
    Dim sourceURL As String, templateURL As String, outputDir As String

    sourceURL = ConvertToURL("C:\MailMerge\customers.ods")
    templateURL = ConvertToURL("C:\MailMerge\LetterTemplate.odt")
    outputDir = ConvertToURL("C:\MailMerge\Output")

    calcDoc = StarDesktop.loadComponentFromURL(sourceURL, "_blank", 0, Array())
    sheet = calcDoc.Sheets.getByName("Sheet1")

    row = 1  ' row 0 contains headers
    Do While sheet.getCellByPosition(0, row).String <> ""
        firstName = sheet.getCellByPosition(1, row).String
        lastName = sheet.getCellByPosition(2, row).String
        imagePath = sheet.getCellByPosition(4, row).String
        outputName = sheet.getCellByPosition(5, row).String

        doc = StarDesktop.loadComponentFromURL(templateURL, "_blank", 0, Array())

        ReplaceAll doc, "{FirstName}", firstName
        ReplaceAll doc, "{LastName}", lastName

        graphics = doc.getGraphicObjects()
        If graphics.hasByName("MergeImage") Then
            imageObj = graphics.getByName("MergeImage")
            imageObj.GraphicURL = ConvertToURL(imagePath)
        Else
            MsgBox "Graphic object MergeImage was not found."
            doc.close(True)
            Exit Sub
        End If

        Dim args(1) As New com.sun.star.beans.PropertyValue
        args(0).Name = "FilterName"
        args(0).Value = "writer_pdf_Export"
        args(1).Name = "Overwrite"
        args(1).Value = True

        doc.storeToURL(outputDir & outputName & ".pdf", args())
        doc.close(True)
        row = row + 1
    Loop

    calcDoc.close(True)
End Sub

Sub ReplaceAll(doc As Object, findText As String, replacement As String)
    Dim d As Object
    d = doc.createReplaceDescriptor()
    d.SearchString = findText
    d.ReplaceString = replacement
    doc.replaceAll(d)
End Sub

Esta macro es un patrón, no un programa universal de inserción. Las instalaciones de LibreOffice pueden tener diferentes políticas de seguridad de macros, reglas de ruta del sistema operativo y diseños de plantillas. Los conceptos importantes de la API verificada son que Writer expone su colección de objetos gráficos y LibreOffice puede establecer un gráfico desde una URL externa. Para implementaciones más grandes, considere cargar el gráfico a través de la GraphicAPI moderna en lugar de depender del comportamiento de compatibilidad de GraphicURL. Las referencias oficiales son XTextGraphicObjectsSupplier y TextGraphicObject .

Paso 5: Ejecuta un lote pequeño y verifica el resultado.

Antes de procesar toda la fuente de datos, ejecute dos o tres filas deliberadamente diferentes: una JPG, una PNG e idealmente una imagen con una relación de aspecto diferente. Confirme todo lo siguiente antes de ampliar:

• El nombre del destinatario en el documento coincide con la imagen de la misma fila de la hoja de cálculo.
• En el documento final no se muestra la ruta de la imagen como texto literal.
• El nombre del archivo de salida coincide con el registro previsto y no sobrescribe el de otro destinatario.
• La imagen se ajusta al área reservada sin desplazar el texto a una página nueva ni tapar otro objeto.
• El archivo PDF o ODT generado se abre de forma independiente después de cerrar LibreOffice y Calc.

Esa última comprobación es importante porque los gráficos vinculados y los gráficos incrustados se comportan de forma diferente. La guía actual de Writer explica que una imagen vinculada sigue siendo una referencia de archivo independiente, mientras que una imagen incrustada pasa a formar parte del documento. Si va a entregar archivos ODT a otro equipo, verifique que el resultado no dependa de una ruta local que solo exista en el equipo que realizó la combinación.

Fallos comunes y la solución más rápida

La salida muestra la ruta del archivo en lugar de la imagen.

Lo insertaste ImagePathcomo un campo de combinación de correspondencia normal. Se espera que genere texto. Mantén la ruta en el origen de datos, pero deja que la macro la cargue en el objeto gráfico con nombre.

Cada registro obtiene la misma imagen.

La imagen de la plantilla no se modificó entre registros, o bien el bucle está leyendo una celda fija. Registre el número de fila ImagePathdurante una prueba con dos registros. Si la ruta cambia pero la imagen no, inspeccione el nombre del objeto gráfico con las Herramientas de desarrollo.

La macro dice que MergeImage no existe.

El gráfico fue renombrado, reemplazado o no se muestra con el nombre esperado. Seleccione la imagen e inspecciónela con Herramientas > Herramientas de desarrollo . La API de UNO muestra los objetos gráficos por nombre, por lo que la macro y la plantilla deben coincidir exactamente.

Las imágenes desaparecen en otro ordenador.

Probablemente guardaste un documento que aún hace referencia a archivos externos. Si la portabilidad es importante, asegúrate de que el documento generado incluya la imagen o expórtalo a PDF después de cargar la imagen. La guía de imágenes de LibreOffice explica la diferencia entre gráficos vinculados e incrustados y cómo se pueden romper los vínculos para incrustar archivos.

La combinación de correspondencia HTML pierde imágenes.

Esta es una limitación documentada que conviene verificar antes de elegir la salida de correo electrónico. La ayuda de LibreOffice indica que, cuando una carta modelo está en formato HTML, las imágenes incrustadas o vinculadas no se envían con el correo electrónico. Si la imagen es esencial, utilice un archivo PDF adjunto o pruebe otro flujo de entrega en lugar de asumir que la combinación de correspondencia HTML la conservará. Consulte Creación de una carta modelo .

¿Cuándo utilizar el servicio MailMerge UNO de LibreOffice?

Si sus campos de texto ya utilizan la combinación de correspondencia de base de datos nativa de Writer y necesita control programático sobre la salida, LibreOffice también expone un MailMergeservicio. Sus propiedades documentadas incluyen DataSourceName, Command, DocumentURL, OutputURL, FileNameFromColumn, y SaveAsSingleFile. Esa API es útil cuando desea automatizar la combinación de correspondencia estándar desde código. Sin embargo, por sí sola no documenta un campo de ruta de archivo de imagen por registro, por lo que es posible que deba combinar la ejecución de la combinación de correspondencia con el manejo de objetos gráficos. Consulte la referencia oficial del servicio MailMerge .

Lista de verificación final

• Utilice la función de combinación de correspondencia normal de Writer cuando la imagen sea fija para cada destinatario.
• Utilice una ImagePathcolumna limpia cuando la imagen varíe según el registro.
• Nombre el marcador de posición gráfico del escritor y mantenga sus dimensiones estables.
• Resuelva la ruta de la imagen de forma automatizada; no espere que un campo de combinación de texto se convierta automáticamente en una imagen.
• Pruebe con dos o tres registros antes de ejecutar un lote completo.
• Abra los archivos exportados después de cerrar los documentos de origen para comprobar que el resultado es autónomo.

Para la mayoría de los trabajos pequeños y medianos, una hoja de cálculo de Calc, una plantilla de Writer y una macro sencilla de Basic ofrecen el mejor equilibrio entre transparencia y control. Requiere más configuración que la combinación de correspondencia de texto convencional, pero permite ver con precisión qué fila proporciona cada imagen, elegir el nombre del archivo de salida y validar el resultado antes de enviar cientos de archivos personalizados.