With the MailMergic API, you can easily generate transactional documents (both PDF and Word files) and reduce development and maintenance costs.
\nAPI access requires a Starter, Pro or Enterprise subscription plan. Users on other plans will receive a 403 error when authenticating with an API key.
\nAll API requests require an API key passed in the X-API-KEY header:
X-API-KEY: your-api-key-here\n\nYou can obtain your API key from the MailMergic dashboard.
\nThe templateId path parameter accepts both formats on all endpoints:
With prefix: tmpl_2LH43zXzZ1ighsivvkHa
Without prefix: 2LH43zXzZ1ighsivvkHa
Both formats are accepted interchangeably on every endpoint.
\nPlaceholders are the dynamic fields in your template that get replaced with the values you provide. Each placeholder is an object with a name and value field:
{\n \"placeholders\": [\n {\"name\": \"First Name\", \"value\": \"Peter\"},\n {\"name\": \"Age\", \"value\": \"31\"}\n ]\n}\n\nAll API error responses use this format:
\n{\"error\":{\"code\":\"ERROR_CODE\",\"message\":\"Human-readable description\"}}\n\nTriggers the creation of a single PDF document that is merged with the data provided in the request. Returns an HTTP 201 response with the merge details and a temporary signed URL to download the generated PDF.
\nThe templateId path parameter accepts both formats: with prefix (e.g., tmpl_2LH43zXzZ1ighsivvkHa) or without (e.g., 2LH43zXzZ1ighsivvkHa).
(Required) Template unique identifier
\n","type":"text/plain"},"type":"any","value":"{{tmpl_templateId}}","key":"templateId"}]}},"response":[{"id":"948ddb5c-3079-47e8-9423-6722603f7c3f","name":"Generate Document","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"data\": [\r\n {\r\n \"placeholder\": \"First Name\", // Placeholder name matching the one in your template\r\n \"value\": \"Peter\" // The value to be printed in the PDF can be specified here.\r\n },\r\n {\r\n \"placeholder\": \"Age\",\r\n \"value\": \"31\"\r\n },\r\n {\r\n \"placeholder\": \"Image\", // Image placeholders can be printed if the placeholder type has been saved as \"Image\" through the web app\r\n \"value\": \"dog.jpeg\" // Upload the image through the web app and send the filename as value (case sensitivity is enforced for both uppercase and lowercase letters)\r\n }\r\n ],\r\n \"formOutput\": \"flatten\", // optional, possible values: 'keep', 'flatten'\r\n \"customDocumentName\": \"Document Name without extension\" // string without a filename extension, it cannot include special characters such as <>:\"/|?*.\r\n}\r\n","options":{"raw":{"language":"json"}}},"url":{"raw":"{{base_url}}/v1/templates/:templateId/merges","host":["{{base_url}}"],"path":["v1","templates",":templateId","merges"],"variable":[{"key":"templateId","value":"{{tmpl_templateId}}","description":"(Required) Template unique identifier"}]}},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"vary","value":"Origin, Accept-Encoding"},{"key":"x-powered-by","value":"Express"},{"key":"access-control-allow-origin","value":"*"},{"key":"x-ratelimit-limit","value":"2"},{"key":"x-ratelimit-remaining","value":"1"},{"key":"x-ratelimit-reset","value":"1699457400"},{"key":"ratelimit-policy","value":"2;w=1"},{"key":"ratelimit-limit","value":"2"},{"key":"ratelimit-remaining","value":"1"},{"key":"ratelimit-reset","value":"1"},{"key":"content-type","value":"application/json; charset=utf-8"},{"key":"etag","value":"W/\"10f18-Icbll9y+SAHH5xuhtRxkBMEDoFw\""},{"key":"Content-Encoding","value":"gzip"},{"key":"X-Cloud-Trace-Context","value":"f1f9fa64abb6c18f2907025fc0c16e0d;o=1"},{"key":"Date","value":"Wed, 08 Nov 2023 15:30:11 GMT"},{"key":"Server","value":"Google Frontend"},{"key":"Cache-Control","value":"private"},{"key":"Transfer-Encoding","value":"chunked"}],"cookie":[],"responseTime":null,"body":"{\n \"createdAt\": \"2023-11-08T15:30:11.514Z\",\n \"templateId\": \"tmpl_dvvUDyVpCcRWKMlyUu9G\",\n \"mergeId\": \"mrg_619c98ba-c0a0-4705-9ce4-c20858988e4a\",\n \"file\": {\n \"type\": \"application/pdf\",\n \"name\": \"Document Name without extension.\",\n \"extension\": \"pdf\",\n \"data\": \"data:application/pdf;base64, ...base64Data... ==\"\n },\n \"request\": {\n \"data\": [\n {\n \"placeholder\": \"First Name\",\n \"value\": \"Peter\"\n },\n {\n \"placeholder\": \"Age\",\n \"value\": \"31\"\n },\n {\n \"placeholder\": \"Image\",\n \"value\": \"peter.jpg\"\n }\n ],\n \"formOutput\": \"flatten\",\n \"customDocumentName\": \"Document Name without extension\"\n }\n}"},{"id":"40298c0f-a740-4335-82ad-9f46e718c8de","name":"Successful Generation","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"placeholders\": [\n {\"name\": \"First Name\", \"value\": \"Peter\"},\n {\"name\": \"Age\", \"value\": \"31\"},\n {\"name\": \"Image\", \"value\": \"peter.jpg\"}\n ],\n \"formOutput\": \"flatten\",\n \"customDocumentName\": \"Document Name without extension\",\n \"passwordProtection\": {\n \"modify\": \"123\", \n \"read\": \"abc\"\n }\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"{{base_url}}/v1/templates/:templateId/merges","host":["{{base_url}}"],"path":["v1","templates",":templateId","merges"],"variable":[{"key":"templateId","value":"tmpl_2LH43zXzZ1ighsivvkHa","enabled":true}]}},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","enabled":true}],"cookie":[],"responseTime":null,"body":"{\\n \"createdAt\": \"2026-03-27T10:30:00.000Z\",\\n \"templateId\": \"tmpl_2LH43zXzZ1ighsivvkHa\",\\n \"mergeId\": \"mrg_550e8400-e29b-41d4-a716-446655440000\",\\n \"file\": {\\n \"mimeType\": \"application/pdf\",\\n \"filename\": \"Document Name.pdf\",\\n \"url\": \"https://storage.googleapis.com/...signed-url...\"\\n },\\n \"request\": {\\n \"data\": [\\n {\"name\": \"First Name\", \"value\": \"Peter\"},\\n {\"name\": \"Age\", \"value\": \"31\"}\\n ],\\n \"formOutput\": \"flatten\",\\n \"customDocumentName\": \"Document Name without extension\",\\n \"passwordProtection\": {\\n \"modify\": \"123\",\\n \"read\": \"abc\"\\n }\\n }\\n}"}],"_postman_id":"0223fd54-e8cf-4a14-8a7a-c0b75cac2276"},{"name":"Generate Document & Send by Email","event":[{"listen":"test","script":{"id":"26741423-3c1a-4fd0-a226-8903b090253b","exec":["pm.test(\"Successful POST request\", function () {\r"," pm.expect(pm.response.code).to.be.oneOf([200, 201]);\r","});"],"type":"text/javascript","packages":{},"requests":{}}}],"id":"65780181-ce0d-4bad-8457-9601fa61e7fa","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"placeholders\": [\r\n {\r\n \"name\": \"First Name\", // Placeholder name matching the one in your template\r\n \"value\": \"Peter\" // The value to be printed in the PDF can be specified here.\r\n },\r\n {\r\n \"name\": \"Age\",\r\n \"value\": \"31\"\r\n },\r\n {\r\n \"name\": \"Image\", // Image placeholders can be printed if the placeholder type has been saved as \"Image\" through the web app\r\n \"value\": \"peter.jpg\" // Upload the image through the web app and send the filename as value (case sensitivity is enforced for both uppercase and lowercase letters)\r\n }\r\n ],\r\n \"formOutput\": \"flatten\", // optional, possible values: 'keep', 'flatten'\r\n \"customDocumentName\": \"Document Name without extension\", // string without a filename extension, it cannot include special characters such as <>:\"/|?*.\r\n \"passwordProtection\": {\r\n // The password fields accepts only Latin alphabet characters (A–Z, a–z), digits (0–9), and the following special characters: !@#$%^&*()\r\n \"modify\": \"123\", \r\n \"read\": \"abc\"\r\n },\r\n \"email\": {\r\n \"isEnabled\": true, // Set to true to enable email sending\r\n \"to\": \"peter@example.com\", // Enter recipient's email address; only one address is allowed\r\n \"cc\": \"jane@example.com\", // Enter CC recipient's email address; only one address is allowed\r\n \"bcc\": \"john@example.com\", // Enter BCC recipient's email address; only one address is allowed\r\n \"from\": {\r\n \"email\": \"lennart.guth@gmail.com\", // Specify the email address of the sender; it must be created and verified in advance at my.mailmergic.com\r\n \"name\": \"Peter Doe\" // Specify the name of the sender\r\n },\r\n \"subject\": \"Important Message\", // Enter the subject of the email\r\n \"content\": \"Dear recipient…\" // Add the content of the email, simple HTML tags are supported (https://pdfmailmerger.com/faq/email-text-formatting)\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/v1/templates/:templateId/merges","description":"Triggers the creation of a single PDF document that is merged with the data specified in the request and sent to the specified recipients. Returns an HTTP 201 response with the merge details, a temporary signed URL to download the generated PDF, and the email delivery status.
\nThe templateId path parameter accepts both formats: with prefix (e.g., tmpl_2LH43zXzZ1ighsivvkHa) or without (e.g., 2LH43zXzZ1ighsivvkHa).
Note: The from.email must be a verified sender in your MailMergic account. Unverified senders will fail with error code UNVERIFIED_SENDER.
(Required) Template unique identifier
\n","type":"text/plain"},"type":"any","value":"{{tmpl_templateId}}","key":"templateId"}]}},"response":[{"id":"b75ddfa0-01d2-4dd8-8015-f91af6e2b162","name":"Generate Document & Send by Email","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"data\": [\r\n {\r\n \"placeholder\": \"First Name\", // Placeholder name matching the one in your template\r\n \"value\": \"Peter\" // The value to be printed in the PDF can be specified here.\r\n },\r\n {\r\n \"placeholder\": \"Age\",\r\n \"value\": \"31\"\r\n },\r\n {\r\n \"placeholder\": \"Image\", // Image placeholders can be printed if the placeholder type has been saved as \"Image\" through the web app\r\n \"value\": \"peter.jpg\" // Upload the image through the web app and send the filename as value (case sensitivity is enforced for both uppercase and lowercase letters)\r\n }\r\n ],\r\n \"formOutput\": \"flatten\", // optional, possible values: 'keep', 'flatten'\r\n \"customDocumentName\": \"Document Name without extension\", // string without a filename extension, it cannot include special characters such as <>:\"/|?*.\r\n \"email\": {\r\n \"isEnabled\": true, // Set to true to enable email sending\r\n \"to\": \"support@pdfmailmerger.com\", // Enter recipient's email address; only one address is allowed\r\n \"cc\": \"support2@pdfmailmerger.com\", // Enter CC recipient's email address; only one address is allowed\r\n \"bcc\": \"support3@pdfmailmerger.com\", // Enter BCC recipient's email address; only one address is allowed\r\n \"from\": {\r\n \"email\": \"support@pdfmailmerger.com\", // Specify the email address of the sender; it must be created and verified in advance in the web app\r\n \"name\": \"PDF Mail Merger Support\" // Specify the name of the sender\r\n },\r\n \"subject\": \"Important Message\", // Enter the subject of the email\r\n \"content\": \"Dear recipient…\" // Add the content of the email, simple HTML tags are supported (https://pdfmailmerger.com/faq/email-text-formatting)\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"{{base_url}}/v1/templates/:templateId/merges","host":["{{base_url}}"],"path":["v1","templates",":templateId","merges"],"variable":[{"key":"templateId","value":"{{tmpl_templateId}}","description":"(Required) Template unique identifier"}]}},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"vary","value":"Origin, Accept-Encoding"},{"key":"x-powered-by","value":"Express"},{"key":"access-control-allow-origin","value":"*"},{"key":"x-ratelimit-limit","value":"2"},{"key":"x-ratelimit-remaining","value":"1"},{"key":"x-ratelimit-reset","value":"1699457888"},{"key":"ratelimit-policy","value":"2;w=1"},{"key":"ratelimit-limit","value":"2"},{"key":"ratelimit-remaining","value":"1"},{"key":"ratelimit-reset","value":"1"},{"key":"content-type","value":"application/json; charset=utf-8"},{"key":"etag","value":"W/\"d488-QdPpPhTnqkI6BHoHVZZS+zT9Ch0\""},{"key":"Content-Encoding","value":"gzip"},{"key":"X-Cloud-Trace-Context","value":"8a590bf86cc421a41e311cbcd1166a4e;o=1"},{"key":"Date","value":"Wed, 08 Nov 2023 15:38:13 GMT"},{"key":"Server","value":"Google Frontend"},{"key":"Cache-Control","value":"private"},{"key":"Transfer-Encoding","value":"chunked"}],"cookie":[],"responseTime":null,"body":"{\n \"createdAt\": \"2023-11-08T15:38:13.407Z\",\n \"templateId\": \"tmpl_dvvUDyVpCcRWKMlyUu9G\",\n \"mergeId\": \"mrg_ffe3e80c-d5e3-4666-a064-5bcac7d15cad\",\n \"file\": {\n \"type\": \"application/pdf\",\n \"name\": \"Document Name without extension\",\n \"extension\": \"pdf\",\n \"data\": \"data:application/pdf;base64, ...base64Data... ==\"\n },\n \"email\": {\n \"status\": \"accepted\",\n \"isEnabled\": true,\n \"to\": \"peter@example.com\",\n \"cc\": \"jane@example.com\",\n \"bcc\": \"john@example.com\",\n \"from\": {\n \"email\": \"support@example.com\",\n \"name\": \"Peter Doe\"\n },\n \"subject\": \"Important Message\",\n \"content\": \"Dear recipient…\"\n },\n \"request\": {\n \"data\": [\n {\n \"placeholder\": \"First Name\",\n \"value\": \"Peter\"\n },\n {\n \"placeholder\": \"Age\",\n \"value\": \"31\"\n },\n {\n \"placeholder\": \"Image\",\n \"value\": \"peter.jpg\"\n }\n ],\n \"formOutput\": \"flatten\",\n \"customDocumentName\": \"Document Name without extension\"\n }\n}"},{"id":"c183cc75-eda4-41e5-8304-e95533ff2a58","name":"Successful Generation with Email","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"placeholders\": [\n {\"name\": \"First Name\", \"value\": \"Peter\"},\n {\"name\": \"Age\", \"value\": \"31\"},\n {\"name\": \"Image\", \"value\": \"peter.jpg\"}\n ],\n \"formOutput\": \"flatten\",\n \"customDocumentName\": \"Document Name without extension\",\n \"passwordProtection\": {\n \"modify\": \"123\", \n \"read\": \"abc\"\n },\n \"email\": {\n \"isEnabled\": true,\n \"to\": \"peter@example.com\",\n \"cc\": \"jane@example.com\",\n \"bcc\": \"john@example.com\",\n \"from\": {\n \"email\": \"support@example.com\",\n \"name\": \"Peter Doe\"\n },\n \"subject\": \"Important Message\",\n \"content\": \"Dear recipient\\u2026\"\n }\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"{{base_url}}/v1/templates/:templateId/merges","host":["{{base_url}}"],"path":["v1","templates",":templateId","merges"],"variable":[{"key":"templateId","value":"tmpl_2LH43zXzZ1ighsivvkHa","enabled":true}]}},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","enabled":true}],"cookie":[],"responseTime":null,"body":"{\\n \"createdAt\": \"2026-03-27T10:30:00.000Z\",\\n \"templateId\": \"tmpl_2LH43zXzZ1ighsivvkHa\",\\n \"mergeId\": \"mrg_550e8400-e29b-41d4-a716-446655440000\",\\n \"file\": {\\n \"mimeType\": \"application/pdf\",\\n \"filename\": \"Document Name.pdf\",\\n \"url\": \"https://storage.googleapis.com/...signed-url...\"\\n },\\n \"request\": {\\n \"data\": [\\n {\"name\": \"First Name\", \"value\": \"Peter\"},\\n {\"name\": \"Age\", \"value\": \"31\"}\\n ],\\n \"formOutput\": \"flatten\",\\n \"customDocumentName\": \"Document Name without extension\",\\n \"passwordProtection\": {\\n \"modify\": \"123\",\\n \"read\": \"abc\"\\n }\\n },\\n \"email\": {\\n \"status\": \"accepted\",\\n \"isEnabled\": true,\\n \"to\": \"peter@example.com\",\\n \"cc\": \"jane@example.com\",\\n \"bcc\": \"john@example.com\",\\n \"from\": {\\n \"email\": \"support@example.com\",\\n \"name\": \"Peter Doe\"\\n },\\n \"subject\": \"Important Message\",\\n \"content\": \"Dear recipient...\"\\n }\\n}"}],"_postman_id":"65780181-ce0d-4bad-8457-9601fa61e7fa"},{"name":"Validate API Key","id":"1c034351-0372-4256-905e-0964a42dce47","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"{{base_url}}/v1/apiKeys/validate","description":"Checks whether the API key provided in the request is valid and active. Returns the user's account details including their billing plan.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"X-API-KEY"},{"key":"value","value":"{{key_apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"a8a79e21-b514-4cd8-b21f-2c11d7a2785c","id":"a8a79e21-b514-4cd8-b21f-2c11d7a2785c","name":"MailMergic API","type":"collection"}},"urlObject":{"path":["v1","apiKeys","validate"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[{"id":"2719b0ed-ce86-48dc-9b8d-b2d9280a3c51","name":"Invalid API Key","originalRequest":{"method":"GET","header":[],"url":"{{base_url}}/v1/apiKeys/validate"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"vary","value":"Origin, Accept-Encoding"},{"key":"x-powered-by","value":"Express"},{"key":"access-control-allow-origin","value":"*"},{"key":"x-ratelimit-limit","value":"2"},{"key":"x-ratelimit-remaining","value":"1"},{"key":"x-ratelimit-reset","value":"1753272815"},{"key":"ratelimit-policy","value":"2;w=1"},{"key":"ratelimit-limit","value":"2"},{"key":"ratelimit-remaining","value":"1"},{"key":"ratelimit-reset","value":"1"},{"key":"content-type","value":"application/json; charset=utf-8"},{"key":"etag","value":"W/\"37-+ZlBVU7bsW7nZKN3HAWSixldQb4\""},{"key":"x-cloud-trace-context","value":"5758bfa737b9627021e4e7bb3dbad0b9"},{"key":"date","value":"Wed, 23 Jul 2025 12:13:33 GMT"},{"key":"server","value":"Google Frontend"},{"key":"Content-Length","value":"55"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"Unauthorized. Missing or invalid API token.\"\n}"},{"id":"b38ed729-2515-48ed-8883-8ee4c538338f","name":"Valid API Key","originalRequest":{"method":"GET","header":[],"url":"{{base_url}}/v1/apiKeys/validate"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[],"cookie":[],"responseTime":null,"body":"{\\n \"uid\": \"abc123def456ghi78901\",\\n \"billingPlan\": \"Pro\",\\n \"firstName\": \"Peter\",\\n \"lastName\": \"Doe\",\\n \"email\": \"peter@example.com\"\\n}"}],"_postman_id":"1c034351-0372-4256-905e-0964a42dce47"},{"name":"Get Placeholders","id":"cff05fed-a5f4-47cb-b5b6-0fe222e4f2dd","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"{{base_url}}/v1/templates/:templateId","description":"Retrieves all data for a specific template, including its metadata and placeholders.
\nThe templateId path parameter accepts both formats: with prefix (e.g., tmpl_2LH43zXzZ1ighsivvkHa) or without (e.g., 2LH43zXzZ1ighsivvkHa).
Use Template ID without tmpl_ prefix
\n","type":"text/plain"},"type":"any","value":"{{tmpl_templateId}}","key":"templateId"}]}},"response":[],"_postman_id":"cff05fed-a5f4-47cb-b5b6-0fe222e4f2dd"},{"name":"List Merges","id":"2a74d954-d477-4170-9cce-85b271db9c57","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"{{base_url}}/v1/templates/:templateId/merges","description":"Lists all merges for a specific template. Returns an array of merge records with their status and details.
\nThe templateId path parameter accepts both formats: with prefix (e.g., tmpl_2LH43zXzZ1ighsivvkHa) or without (e.g., 2LH43zXzZ1ighsivvkHa).
Retrieves the status and details of a specific merge, including the file download URL if the merge is complete.
\nThe templateId path parameter accepts both formats: with prefix (e.g., tmpl_2LH43zXzZ1ighsivvkHa) or without (e.g., 2LH43zXzZ1ighsivvkHa).
Deletes a specific merge and its associated files permanently.
\nThe templateId path parameter accepts both formats: with prefix (e.g., tmpl_2LH43zXzZ1ighsivvkHa) or without (e.g., 2LH43zXzZ1ighsivvkHa).
Cancels a merge that is currently in progress. Only merges with a pending or processing status can be cancelled.
\nThe templateId path parameter accepts both formats: with prefix (e.g., tmpl_2LH43zXzZ1ighsivvkHa) or without (e.g., 2LH43zXzZ1ighsivvkHa).