Email Publishing API

Generate and export personalized documents (Word or PDF) from email templates with data, packaged for email distribution.

---

Base URL

https://app.datapublisher.io/api/email-publishing-exports

---

Authentication

All endpoints require JWT authentication via Authorization: Bearer header.

---

Overview

The Email Publishing API allows you to:

Create export configurations (template + data + email settings)

Generate personalized documents for each record in your data

Package documents as attachments for email campaigns

Export in DOCX or PDF format

Configure email field mappings (recipient, subject)

Test mode for verification before full run

Include static attachments (same file for all recipients)

Use Cases:

Personalized invoices sent via email

Custom reports for each customer

Individualized contracts or agreements

Personalized marketing materials

---

Endpoints

Create Email Publishing Export

Create a new export configuration that defines how to generate and email documents.

Endpoint: POST /

Headers:

Authorization: Bearer

Content-Type: application/json

Request Body:

{ "exportName": "Monthly Invoice Export", "dataFileId": "csv-file-uuid", "dataFileName": "customers.csv", "templateId": "template-uuid", "templateName": "Invoice Template", "format": "pdf", "emailField": "CustomerEmail", "subjectField": "InvoiceSubject", "defaultSubject": "Your Monthly Invoice from {{CompanyName}}", "testMode": false, "recordCount": 150, "staticAttachments": [ { "fileName": "Terms.pdf", "fileUrl": "/uploads/static/terms.pdf" } ], "wizardProgress": { "step": "complete", "lastUpdated": "2026-02-12T10:00:00Z" }

}

Field Descriptions:

exportName (required): Display name for this export

dataFileId (required): UUID of CSV data file

dataFileName (required): Name of data file

templateId (required): UUID of Word template

templateName (required): Template display name

format (required): Output format (docx or pdf)

emailField (required): Column name containing recipient email addresses

subjectField (optional): Column name for custom email subjects

defaultSubject (required): Default subject line (supports {{variables}})

testMode (optional): Run in test mode (default: false)

recordCount (optional): Number of records in data file

staticAttachments (optional): Files attached to all emails

wizardProgress (optional): UI wizard state

Response (201 Created):

{ "success": true, "export": { "id": "uuid", "exportName": "Monthly Invoice Export", "dataFileId": "csv-file-uuid", "dataFileName": "customers.csv", "templateId": "template-uuid", "templateName": "Invoice Template", "format": "pdf", "emailField": "CustomerEmail", "subjectField": "InvoiceSubject", "defaultSubject": "Your Monthly Invoice from {{CompanyName}}", "testMode": false, "recordCount": 150, "status": "configured", "createdAt": "2026-02-12T10:00:00Z" }, "message": "Email publishing export saved successfully"

}

Error Responses:

400 Bad Request - Missing required fields:

{ "success": false, "error": "Missing required fields: exportName, dataFileId, dataFileName, templateId, templateName, format, emailField, defaultSubject"

}

400 Bad Request - Invalid format:

{
  "success": false,

  "error": "Format must be either \"docx\" or \"pdf\""

}

409 Conflict - Export name already exists:

{ "success": false, "error": "Export with name 'Monthly Invoice Export' already exists"

}

---

List Email Publishing Exports

Get all export configurations for the user.

Endpoint: GET /

Headers:

Authorization: Bearer

Response (200 OK):

{ "success": true, "exports": [ { "id": "uuid", "exportName": "Monthly Invoice Export", "dataFileName": "customers.csv", "templateName": "Invoice Template", "format": "pdf", "recordCount": 150, "status": "completed", "lastRunAt": "2026-02-10T14:30:00Z", "createdAt": "2026-01-15T10:00:00Z" } ], "count": 1

}

---

Get Email Publishing Export

Retrieve detailed information about a specific export configuration.

Endpoint: GET /:id

Headers:

Authorization: Bearer

Response (200 OK):

{ "success": true, "export": { "id": "uuid", "exportName": "Monthly Invoice Export", "dataFileId": "csv-file-uuid", "dataFileName": "customers.csv", "templateId": "template-uuid", "templateName": "Invoice Template", "format": "pdf", "emailField": "CustomerEmail", "subjectField": "InvoiceSubject", "defaultSubject": "Your Monthly Invoice from {{CompanyName}}", "testMode": false, "recordCount": 150, "staticAttachments": [], "status": "completed", "zipFilePath": "/exports/user-uuid/monthly-invoice-2026-02-10.zip", "zipFileSize": 5242880, "createdAt": "2026-01-15T10:00:00Z", "lastRunAt": "2026-02-10T14:30:00Z" }

}

Error Responses:

404 Not Found:

{
  "success": false,

  "error": "Export not found"

}

---

Update Email Publishing Export

Update an export configuration.

Endpoint: PUT /:id

Headers:

Authorization: Bearer

Content-Type: application/json

Request Body (all fields optional):

{ "exportName": "Updated Export Name", "format": "docx", "defaultSubject": "New subject line", "testMode": true

}

Response (200 OK):

{ "success": true, "export": { "id": "uuid", "exportName": "Updated Export Name", "format": "docx", "updatedAt": "2026-02-12T11:00:00Z" }, "message": "Export updated successfully"

}

Error Responses:

404 Not Found:

{
  "success": false,

  "error": "Export not found or access denied"

}

---

Generate Documents

Execute the export to generate personalized documents.

Endpoint: POST /:id/generate

Headers:

Authorization: Bearer

Response (202 Accepted):

{ "success": true, "message": "Document generation started", "jobId": "job-uuid", "estimatedTime": "5 minutes"

}

Notes:

Document generation runs asynchronously

Poll GET /:id/status to check progress

When complete, ZIP file is available for download

---

Check Generation Status

Check the status of document generation.

Endpoint: GET /:id/status

Headers:

Authorization: Bearer

Response (200 OK):

{ "success": true, "status": "in_progress", "progress": { "completed": 75, "total": 150, "percentage": 50 }, "startedAt": "2026-02-12T10:00:00Z", "estimatedCompletion": "2026-02-12T10:05:00Z"

}

Status Values:

configured: Not yet run

in_progress: Currently generating

completed: Successfully completed

failed: Error occurred

---

Download Export ZIP

Download ZIP file containing all generated documents.

Endpoint: GET /:id/download

Headers:

Authorization: Bearer

Response (200 OK):

Binary file stream (application/zip)

Content-Disposition: attachment; filename="export-name-YYYY-MM-DD.zip"

ZIP Structure:

monthly-invoice-2026-02-10.zip ├── invoice-customer1.pdf ├── invoice-customer2.pdf ├── invoice-customer3.pdf ├── ... └── static/

└── Terms.pdf

---

Delete Email Publishing Export

Delete export configuration and generated files.

Endpoint: DELETE /:id

Headers:

Authorization: Bearer

Response (200 OK):

{
  "success": true,

  "message": "Export deleted successfully"

}

---

Document Generation Process

Step 1: Configuration

Upload CSV data file with email addresses

Upload Word template with {{variables}}

Create export configuration via API

Map email field and subject field

Set output format (DOCX or PDF)

Step 2: Generation

Call POST /:id/generate

System reads CSV row by row

For each row:

- Replace {{variables}} in template with row data

- Generate document (DOCX or PDF)

- Name file based on row data

- Add to ZIP archive

Include static attachments

Save ZIP file for download

Step 3: Distribution

Download ZIP file

Extract documents

Use with email campaign

Or integrate with email automation

---

Variable Replacement

Variables in templates are replaced with data from CSV columns:

Template:

Invoice for {{CompanyName}}
Amount Due: {{TotalAmount}}

Due Date: {{DueDate}}

CSV Data:

CompanyName,TotalAmount,DueDate,CustomerEmail

Acme Corp,5000,2026-03-01,billing@acme.com

Generated Document:

Invoice for Acme Corp Amount Due: 5000

Due Date: 2026-03-01

---

Test Mode

Enable testMode: true to:

Generate only first 5 documents

Verify template and data mapping

Check output format and quality

Test before full production run

---

File Naming

Generated files are named using pattern:

{templateName}-{uniqueIdentifier}.{format}

Examples:

invoice-customer-12345.pdf

report-acme-corp.docx

---

Rate Limiting

Create/Update: 100 requests per 15 minutes

Generate: 10 concurrent generations per user

Download: 50 downloads per 15 minutes

---

Common Error Codes

| Status Code | Description |

|-------------|-------------|

| 400 | Invalid request data or format |

| 401 | Unauthorized - missing or invalid JWT token |

| 404 | Export not found or access denied |

| 409 | Export name already exists |

| 413 | Data file or template too large |

| 429 | Too many requests |

| 500 | Internal server error |

---

Best Practices

Test First: Always run in test mode before full generation

File Size: Keep templates under 5 MB for faster processing

Data Quality: Validate CSV data before generation

Subject Lines: Use variables to personalize email subjects

Static Attachments: Use for common files (terms, policies)

Polling: Poll status every 5-10 seconds during generation

Cleanup: Delete old exports to save storage space

---

Email Publishing API

Base URL

Authentication

Overview

Endpoints

Create Email Publishing Export

List Email Publishing Exports

Get Email Publishing Export

Update Email Publishing Export

Generate Documents

Check Generation Status

Download Export ZIP

Delete Email Publishing Export

Document Generation Process

Step 1: Configuration

Step 2: Generation

Step 3: Distribution

Variable Replacement

Test Mode

File Naming

Rate Limiting

Common Error Codes

Best Practices

Related Documentation