POST /render | Docs

Overview

The /render endpoint hydrates a template with variables and returns the resulting HTML. Use this when you want to render emails but handle sending yourself.

Endpoint

POST /v1/render

Request Body

Field	Type	Required	Description
`template_id`	string	Yes	The ID of the template to render
`variables`	object	No	Key-value pairs for variable substitution

Example Request

curl -X POST https://api.mailsh.it/v1/render \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tmpl_abc123",
    "variables": {
      "firstName": "Alice",
      "orderNumber": "12345",
      "trackingUrl": "https://example.com/track/12345"
    }
  }'

Response

Success (200)

{
  "html": "<!DOCTYPE html><html>...</html>",
  "subject": "Your order #12345 has shipped"
}

Field	Type	Description
`html`	string	The fully rendered HTML email
`subject`	string	The email subject (from template or variables)

Error (400)

{
  "error": "template_id is required"
}

Error (404)

{
  "error": "Template not found"
}

Variable Substitution

Variables in templates use the {{name|default}} syntax:

{{firstName}} - Required variable, no default
{{firstName|Friend}} - Uses “Friend” if not provided
{{company|}} - Empty string if not provided

When you call /render:

Variables you provide replace the placeholders
Variables you don’t provide use their inline defaults
The final HTML contains no raw {{}} syntax

Code Examples

JavaScript

const response = await fetch('https://api.mailsh.it/v1/render', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.MAILSHIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    template_id: 'tmpl_abc123',
    variables: {
      firstName: 'Alice',
    },
  }),
})

const { html, subject } = await response.json()

Python

import requests

response = requests.post(
    'https://api.mailsh.it/v1/render',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json',
    },
    json={
        'template_id': 'tmpl_abc123',
        'variables': {
            'firstName': 'Alice',
        },
    },
)

data = response.json()
html = data['html']
subject = data['subject']

Use Cases

Preview emails before sending
Store rendered HTML for later sending
Use your own sending infrastructure (SMTP, other providers)
Generate email content for testing