Templates

List and retrieve email templates. Templates are created and edited through the TopMail dashboard, and can be referenced when sending emails via the API.

GET

/templates

List all templates with optional search.

Query Parameters

Name	Type	Required	Description
search	string	Optional	Search templates by name.
limit	integer	Optional	Number of templates to return (default: 100, max: 1000).
offset	integer	Optional	Number of templates to skip for pagination (default: 0).

curl "https://api.topmail.so/api/v1/templates?search=welcome&limit=10" \
  -H "Authorization: Bearer tm_live_abc123"

The list endpoint does not include HTML content to reduce payload size. Use the single template endpoint below to retrieve the full content.

GET

/templates/:id

Retrieve a single template with its HTML content.

curl https://api.topmail.so/api/v1/templates/TEMPLATE_ID \
  -H "Authorization: Bearer tm_live_abc123"

{
  "data": {
    "id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "name": "Welcome Email",
    "html": "<html><body><h1>Welcome, {{first_name}}!</h1><p>Thanks for signing up.</p></body></html>",
    "json_structure": null,
    "created_at": "2025-01-05T12:00:00.000Z",
    "updated_at": "2025-01-12T09:30:00.000Z"
  }
}

Using templates when sending emails

You can reference a template by its ID when sending an email via the Email Send API. Use template_id instead of html, and optionally pass template_data to substitute variables.

curl -X POST https://api.topmail.so/api/v1/email/send \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "jane@example.com",
    "subject": "Welcome to Acme!",
    "template_id": "TEMPLATE_ID",
    "template_data": {
      "first_name": "Jane",
      "company": "Acme Inc"
    }
  }'

Template variables use double-brace syntax: {{variable_name}}. Contact attributes like {{first_name}} and {{email}} are automatically populated from the contact record when the recipient exists in your workspace.