> For the complete documentation index, see [llms.txt](https://www.center.daxium-air.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.center.daxium-air.com/api-reference/mail-merge.md).
# Mail Merge
## List mail-merge templates
> Returns the mail-merge templates available for a form (\`structure\`) or a\
> submission (\`submission\`). Provide one \*\*or\*\* the other parameter.
```json
{"openapi":"3.0.3","info":{"title":"Daxium Air API","version":"v1.3"},"tags":[{"name":"publipostages"}],"servers":[{"url":"https://api.daxium-air.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"parameters":{"AppShort":{"name":"app_short","in":"path","required":true,"description":"Short name of the workspace instance (e.g. `daxium-test`)","schema":{"type":"string"}}},"schemas":{"ReportTemplateListResponse":{"type":"object","properties":{"templates":{"type":"array","items":{"$ref":"#/components/schemas/ReportTemplate"}},"total_count":{"type":"integer"},"total_pages":{"type":"integer"},"server_time":{"type":"integer","format":"int64"}}},"ReportTemplate":{"type":"object","description":"Mail-merge template","properties":{"id":{"type":"integer","description":"Template identifier"},"name":{"type":"string","description":"Template name"},"listingMode":{"type":"boolean","description":"Whether the template is in listing mode"},"templateEngine":{"type":"string","description":"Template generation engine (e.g. docxopenxml, xlsxaspose)"}}}}},"paths":{"/{app_short}/report_templates":{"get":{"summary":"List mail-merge templates","description":"Returns the mail-merge templates available for a form (`structure`) or a\nsubmission (`submission`). Provide one **or** the other parameter.\n","tags":["publipostages"],"operationId":"listReportTemplates","parameters":[{"$ref":"#/components/parameters/AppShort"},{"name":"structure","in":"query","description":"Form identifier whose templates to retrieve","schema":{"type":"integer"}},{"name":"submission","in":"query","description":"Submission identifier (UUID) whose templates to retrieve","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Available mail-merge templates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportTemplateListResponse"}}}}}}}}}
```
## List mail merges for a submission
> Returns all mail merges generated for a given submission.
```json
{"openapi":"3.0.3","info":{"title":"Daxium Air API","version":"v1.3"},"tags":[{"name":"publipostages"}],"servers":[{"url":"https://api.daxium-air.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"parameters":{"AppShort":{"name":"app_short","in":"path","required":true,"description":"Short name of the workspace instance (e.g. `daxium-test`)","schema":{"type":"string"}}},"schemas":{"ReportListResponse":{"type":"object","properties":{"reports":{"type":"array","items":{"$ref":"#/components/schemas/Report"}},"total_count":{"type":"integer"},"next_page":{"type":"integer"},"server_time":{"type":"integer","format":"int64"}}},"Report":{"type":"object","description":"Generated mail merge","properties":{"id":{"type":"integer","description":"Mail merge identifier"},"status":{"type":"string","description":"Mail merge status (e.g. finished, error)"},"original_document":{"type":"object","description":"File generated in the original format","properties":{"file_uuid":{"type":"string","description":"UUID of the generated file"},"file_name":{"type":"string","description":"Name of the generated file"}}},"pdf_document":{"type":"object","description":"File generated in PDF format","properties":{"file_uuid":{"type":"string"},"file_name":{"type":"string"}}},"errorMessage":{"type":"string","description":"Error message, if any"}}}}},"paths":{"/{app_short}/reports":{"get":{"summary":"List mail merges for a submission","description":"Returns all mail merges generated for a given submission.","tags":["publipostages"],"operationId":"listReportsBySubmission","parameters":[{"$ref":"#/components/parameters/AppShort"},{"name":"submission","in":"query","required":true,"description":"Submission identifier (UUID)","schema":{"type":"string","format":"uuid"}},{"name":"per_page","in":"query","description":"Number of mail merges per page (default 10, max 1000)","schema":{"type":"integer"}},{"name":"page","in":"query","description":"Number of the requested page","schema":{"type":"integer"}},{"name":"updated_since","in":"query","description":"Filter mail merges updated after this date (timestamp)","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Paginated list of mail merges","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportListResponse"}}}}}}}}}
```
## Start a mail merge
> Starts mail-merge generation for a submission from a template.\
> The \`api\_callback\` URL is called (PUT method) once generation completes;\
> \`{publipostage\_id}\` is replaced by the identifier of the created mail merge.
```json
{"openapi":"3.0.3","info":{"title":"Daxium Air API","version":"v1.3"},"tags":[{"name":"publipostages"}],"servers":[{"url":"https://api.daxium-air.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"parameters":{"AppShort":{"name":"app_short","in":"path","required":true,"description":"Short name of the workspace instance (e.g. `daxium-test`)","schema":{"type":"string"}}},"schemas":{"ReportInput":{"type":"object","required":["template_id","submission_id","api_callback"],"description":"Body for starting a mail merge","properties":{"template_id":{"type":"integer","description":"Template identifier (mandatory)"},"submission_id":{"type":"string","format":"uuid","description":"Submission identifier (mandatory)"},"api_callback":{"type":"string","description":"URL called (PUT) when generation completes; `{publipostage_id}` is substituted (mandatory)"},"header_name":{"type":"string","description":"HTTP header name to send during the callback (optional)"},"header_value":{"type":"string","description":"HTTP header value to send during the callback (optional)"},"join_format":{"type":"string","enum":["original","pdf","original,pdf"],"description":"Output format: `original`, `pdf`, or `original,pdf` (two reports generated)"}}}}},"paths":{"/{app_short}/reports":{"post":{"summary":"Start a mail merge","description":"Starts mail-merge generation for a submission from a template.\nThe `api_callback` URL is called (PUT method) once generation completes;\n`{publipostage_id}` is replaced by the identifier of the created mail merge.\n","tags":["publipostages"],"operationId":"startReport","parameters":[{"$ref":"#/components/parameters/AppShort"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportInput"}}}},"responses":{"200":{"description":"Mail merge created","content":{"application/json":{"schema":{"type":"object","properties":{"report_id":{"type":"integer","description":"Identifier of the created mail merge"}}}}}}}}}}}
```
## Get mail merge information
> Returns the status and generated files of a mail merge by its identifier.
```json
{"openapi":"3.0.3","info":{"title":"Daxium Air API","version":"v1.3"},"tags":[{"name":"publipostages"}],"servers":[{"url":"https://api.daxium-air.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"parameters":{"AppShort":{"name":"app_short","in":"path","required":true,"description":"Short name of the workspace instance (e.g. `daxium-test`)","schema":{"type":"string"}}},"schemas":{"Report":{"type":"object","description":"Generated mail merge","properties":{"id":{"type":"integer","description":"Mail merge identifier"},"status":{"type":"string","description":"Mail merge status (e.g. finished, error)"},"original_document":{"type":"object","description":"File generated in the original format","properties":{"file_uuid":{"type":"string","description":"UUID of the generated file"},"file_name":{"type":"string","description":"Name of the generated file"}}},"pdf_document":{"type":"object","description":"File generated in PDF format","properties":{"file_uuid":{"type":"string"},"file_name":{"type":"string"}}},"errorMessage":{"type":"string","description":"Error message, if any"}}}}},"paths":{"/{app_short}/reports/{report_id}":{"get":{"summary":"Get mail merge information","description":"Returns the status and generated files of a mail merge by its identifier.","tags":["publipostages"],"operationId":"getReport","parameters":[{"$ref":"#/components/parameters/AppShort"},{"name":"report_id","in":"path","required":true,"description":"Mail merge identifier","schema":{"type":"integer"}}],"responses":{"200":{"description":"Mail merge information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}}}}}}}
```
## Download a generated mail-merge file
> Returns the binary file generated by a mail merge from its UUID.
```json
{"openapi":"3.0.3","info":{"title":"Daxium Air API","version":"v1.3"},"tags":[{"name":"publipostages"}],"servers":[{"url":"https://api.daxium-air.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"parameters":{"AppShort":{"name":"app_short","in":"path","required":true,"description":"Short name of the workspace instance (e.g. `daxium-test`)","schema":{"type":"string"}}}},"paths":{"/{app_short}/reports/{report_id}/results/{file_uuid}":{"get":{"summary":"Download a generated mail-merge file","description":"Returns the binary file generated by a mail merge from its UUID.","tags":["publipostages"],"operationId":"getReportResultFile","parameters":[{"$ref":"#/components/parameters/AppShort"},{"name":"report_id","in":"path","required":true,"description":"Mail merge identifier","schema":{"type":"integer"}},{"name":"file_uuid","in":"path","required":true,"description":"UUID of the generated file","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Binary content of the generated file","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://www.center.daxium-air.com/api-reference/mail-merge.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.