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.

그래픽 개체에 `.graphic.object`와 같은 안정적인 이름을 지정하세요 MergeImage. 속성 대화 상자는 버전에 따라 다를 수 있으므로 Writer에서 어떤 개체를 노출하는지 확실하지 않은 경우 도구 > 개발자 도구를 사용하세요 . LibreOffice의 개발자 도구는 현재 문서의 그래픽 개체, 속성, 메서드 및 인터페이스를 검사할 수 있습니다. 따라서 내부 개체 이름을 추측하는 것보다 더 안전한 진단 도구입니다.

일관된 레이아웃을 위해 모든 원본 이미지에 동일한 가로세로 비율을 사용하거나 원하는 자르기 방식을 결정하세요. Writer는 그래픽 크기를 자리 표시자의 크기에 맞게 조정할 수 있지만, 세로 사진을 가로 배너 모양 프레임에 삽입하면 파일을 먼저 정규화하지 않으면 여전히 어색하게 보일 수 있습니다.

4단계: 가변 이미지 및 문서 내보내기 자동화

핵심 자동화 작업은 간단합니다. 템플릿을 열고 텍스트 자리 표시자를 바꾸고, 이름이 지정된 그래픽 개체를 찾고, 해당 행의 이미지 파일을 그 개체에 로드한 다음 결과를 내보내면 됩니다. LibreOffice의 UNO API 문서에는 getGraphicObjects()내장 및 링크된 그래픽에 액세스하는 방법과 TextGraphicObject그래픽 속성에 대한 서비스가 나와 있습니다. 해당 GraphicURL속성은 일반적인 개체 저장에는 더 이상 사용되지 않으며 대신 다른 방법이 권장되지만 Graphic, 현재 API에서는 외부 URL을 설정하면 해당 이미지가 그래픽 개체에 로드된다고 명시적으로 언급하고 있습니다. 따라서 로컬 파일 경로를 사용하는 간단한 Basic 매크로를 작성하는 데 편리합니다.

다음 예시는 의도적으로 간략하게 구성되었습니다. 세 개의 경로, 시트 이름, 열 인덱스 및 자리 표시자 이름을 자신의 파일에 맞게 변경하십시오. 대량 작업을 실행하기 전에 두 개의 레코드를 대상으로 테스트하십시오.

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

이 매크로는 패턴일 뿐, 범용 프로그램이 아닙니다. LibreOffice 설치 환경에 따라 매크로 보안 정책, 운영 체제 경로 규칙, 템플릿 레이아웃이 다를 수 있습니다. 중요한 검증된 API 개념은 Writer가 그래픽 개체 모음을 노출하고 LibreOffice가 외부 URL에서 그래픽을 설정할 수 있다는 것입니다. 대규모 배포 환경에서는 Graphic호환성 동작에 의존하기보다는 최신 API를 통해 그래픽을 로드하는 것을 고려하십시오 GraphicURL. 공식 참조는 XTextGraphicObjectsSupplier 및 TextGraphicObject 입니다 .

5단계: 소량 생산을 실행하고 결과를 확인합니다.

전체 데이터 소스를 처리하기 전에, 의도적으로 서로 다른 두세 개의 행을 실행해 보세요. 하나는 JPG 형식, 하나는 PNG 형식, 그리고 가능하면 가로세로 비율이 다른 이미지 하나를 선택하세요. 확대하기 전에 다음 사항들을 모두 확인하세요.

• 문서에 있는 수신자 이름이 스프레드시트의 같은 행에 있는 이미지와 일치합니다.
• 최종 문서에는 이미지 경로가 텍스트로 그대로 표시되지 않습니다.
• 출력 파일 이름은 의도한 레코드와 일치하며 다른 수신자의 파일을 덮어쓰지 않습니다.
• 이미지가 예약된 영역에 딱 맞게 들어가면서 텍스트를 새 페이지로 넘기거나 다른 개체를 가리지 않습니다.
• 생성된 PDF 또는 ODT 파일은 LibreOffice와 Calc를 닫은 후에도 자동으로 열립니다.

마지막 확인 사항이 중요한 이유는 링크된 그래픽과 포함된 그래픽의 동작 방식이 다르기 때문입니다. 최신 Writer 가이드에 따르면 링크된 이미지는 별도의 파일 참조로 유지되는 반면, 포함된 이미지는 문서의 일부가 됩니다. ODT 파일을 다른 컴퓨터로 전송하는 경우, 병합을 수행한 컴퓨터에만 존재하는 로컬 경로에 결과가 의존하지 않는지 확인해야 합니다.

흔히 발생하는 문제점과 가장 빠른 해결책

출력 결과에는 이미지 대신 파일 경로가 표시됩니다.

일반 메일 병합 필드처럼 삽입하셨군요 ImagePath. 그러면 텍스트가 생성되는 것이 당연합니다. 데이터 소스의 경로는 유지하되, 매크로가 해당 데이터를 명명된 그래픽 개체에 로드하도록 하세요.

모든 레코드에 동일한 이미지가 표시됩니다.

템플릿 이미지가 레코드 간에 변경되지 않았거나, 루프가 고정된 셀을 읽고 있는 것 같습니다. ImagePath두 레코드를 실행하여 테스트하는 동안 행 번호를 로그로 기록해 보세요. 경로가 변경되었지만 이미지가 변경되지 않으면 개발자 도구를 사용하여 그래픽 객체 이름을 검사해 보세요.

매크로에서 MergeImage가 존재하지 않는다고 합니다.

그래픽 파일의 이름이 변경되었거나, 다른 파일로 교체되었거나, 예상하는 이름으로 표시되지 않을 수 있습니다. 이미지를 선택하고 도구 > 개발자 도구를 사용하여 검사하십시오 . UNO API는 그래픽 객체를 이름으로 노출하므로 매크로와 템플릿의 이름이 정확히 일치해야 합니다.

다른 컴퓨터에서는 이미지가 사라집니다.

아마도 외부 파일을 참조하는 문서를 저장했을 가능성이 높습니다. 휴대성이 중요하다면 생성된 파일에 이미지가 포함되도록 하거나 이미지를 불러온 후 PDF로 내보내세요. LibreOffice의 이미지 가이드에서는 링크된 이미지와 포함된 이미지의 차이점, 그리고 링크를 해제하여 파일을 포함하는 방법을 설명합니다.

HTML 메일 병합 시 이미지가 손실됩니다.

이는 이메일 출력 형식을 선택하기 전에 확인해야 할 문서화된 제한 사항입니다. LibreOffice 도움말에 따르면 양식 편지가 HTML 형식인 경우, 포함되거나 링크된 이미지는 이메일과 함께 전송되지 않습니다. 이미지가 필수적인 경우, HTML 메일 병합에서 이미지가 유지될 것이라고 가정하지 말고 PDF 첨부 파일을 사용하거나 다른 전송 워크플로를 테스트해 보세요. 양식 편지 만들기(Creating a Form Letter)를 참조하십시오 .

LibreOffice의 MailMerge UNO 서비스를 사용해야 하는 경우는 언제일까요?

텍스트 필드에서 이미 Writer의 기본 데이터베이스 메일 병합 기능을 사용하고 있고 출력에 대한 프로그래밍 방식 제어가 필요한 경우, LibreOffice에서 제공하는 MailMerge서비스를 사용할 수 있습니다. 해당 서비스의 문서화된 속성에는 DataSourceName, Command, DocumentURL, OutputURL, FileNameFromColumn및 가 포함됩니다 SaveAsSingleFile. 이 API는 코드에서 표준 메일 병합을 자동화하려는 경우 유용합니다. 하지만 이 서비스 자체에는 레코드별 이미지 파일 경로 필드가 문서화되어 있지 않으므로, 메일 병합 실행과 그래픽 객체 처리를 함께 수행해야 할 수도 있습니다. 자세한 내용은 공식 MailMerge 서비스 참조를 확인하세요 .

최종 체크리스트

• 이미지가 모든 수신자에게 동일하게 표시되는 경우 일반 Writer 메일 병합 기능을 사용하세요.
• ImagePath레코드별로 이미지가 다른 경우, 하나의 깨끗한 열을 사용하십시오 .
• Writer 그래픽 자리 표시자의 이름을 지정하고 크기를 일정하게 유지하세요.
• 자동화 과정에서 이미지 경로를 직접 처리해야 합니다. 텍스트 병합 필드가 자동으로 이미지로 변환될 것이라고 기대하지 마십시오.
• 전체 배치 작업을 실행하기 전에 두세 개의 레코드를 테스트해 보세요.
• 원본 문서를 닫은 후 내보낸 파일을 열어 출력물이 자체적으로 완전한지 확인하십시오.

대부분의 소규모 및 중규모 작업에는 Calc 스프레드시트와 Writer 템플릿, 그리고 간단한 Basic 매크로를 사용하는 것이 투명성과 제어 측면에서 최적의 균형을 제공합니다. 일반적인 텍스트 메일 병합보다 설정 과정이 다소 복잡하지만, 각 이미지가 어떤 행에서 제공되는지 정확하게 확인하고, 출력 파일 이름을 지정하고, 수백 개의 개인화된 파일을 보내기 전에 결과를 검증할 수 있습니다.