Skip to content

Templates

Jump to bottom
Greg Svoboda edited this page Mar 4, 2026 · 1 revision

Templates

Template management is done through ServerClient. Template pushes across servers use AccountClient.

import postmark

client = postmark.ServerClient("your-server-token")
account = postmark.AccountClient("your-account-token")

Send with a Template

Send a single email using a Postmark template. Reference the template by ID or alias.

import asyncio
from postmark.models.templates import TemplateEmail

async def main():
    # By template ID
    response = await client.outbound.send_with_template(
        TemplateEmail(
            sender="you@example.com",
            to="recipient@example.com",
            template_id=12345,
            template_model={
                "name": "Alice",
                "action_url": "https://example.com/confirm",
            },
        )
    )
    print(f"Sent: {response.message_id}")

    # By template alias (using a dict)
    response = await client.outbound.send_with_template({
        "From": "you@example.com",
        "To": "recipient@example.com",
        "TemplateAlias": "welcome-email",
        "TemplateModel": {
            "name": "Bob",
            "action_url": "https://example.com/confirm",
        },
    })
    print(f"Sent: {response.message_id}")

asyncio.run(main())

Send Batch with Templates

Send multiple templated emails in a single API call.

import asyncio

async def main():
    responses = await client.outbound.send_batch_with_template([
        {
            "From": "you@example.com",
            "To": "alice@example.com",
            "TemplateAlias": "welcome-email",
            "TemplateModel": {"name": "Alice"},
        },
        {
            "From": "you@example.com",
            "To": "bob@example.com",
            "TemplateAlias": "welcome-email",
            "TemplateModel": {"name": "Bob"},
        },
    ])
    for resp in responses:
        print(f"  {resp.message_id}")

asyncio.run(main())

List Templates

async def main():
    result = await client.templates.list()
    print(f"Total: {result.total}")
    for t in result.items:
        print(f"  [{t.template_id}] {t.name}  alias={t.alias}")

Get a Template

Retrieve a template by its ID or alias.

async def main():
    # By ID
    template = await client.templates.get(12345)
    print(f"Name:    {template.name}")
    print(f"Subject: {template.subject}")

    # By alias
    template = await client.templates.get("welcome-email")

Create a Template

import asyncio
from postmark.models.templates import CreateTemplateRequest

async def main():
    result = await client.templates.create(
        CreateTemplateRequest(
            name="Welcome Email",
            alias="welcome-email",
            subject="Welcome, {{name}}!",
            html_body="<p>Hi {{name}}, thanks for joining!</p>",
            text_body="Hi {{name}}, thanks for joining!",
        )
    )
    print(f"Created: id={result.template_id}  alias={result.alias}")

asyncio.run(main())

Edit a Template

async def main():
    result = await client.templates.edit(
        12345,
        {"Subject": "Updated subject — {{name}}!"},
    )
    print(f"Updated: {result.template_id}")

Delete a Template

async def main():
    await client.templates.delete(12345)
    print("Deleted")

Validate a Template

Check template syntax and preview rendered output before sending.

async def main():
    result = await client.templates.validate({
        "Subject": {"Content": "Hello, {{name}}!", "TestRenderModel": {"name": "Alice"}},
        "HtmlBody": {"Content": "<p>Hi {{name}}</p>", "TestRenderModel": {"name": "Alice"}},
    })
    print(f"Subject valid: {result.subject.content_is_valid}")

Push Templates to Another Server

Copy templates from one server to another using AccountClient.

import asyncio
from postmark.models.templates import PushTemplatesRequest

async def main():
    # Dry run — preview what would change
    result = await account.templates.push({
        "SourceServerID": "source-server-id",
        "DestinationServerID": "destination-server-id",
        "PerformChanges": False,
    })
    print(f"Dry run — {result.total_count} template(s) would be affected:")
    for t in result.templates:
        print(f"  action={t.action}  [{t.template_id}]  {t.name}")

    # Apply — push templates for real
    result = await account.templates.push(
        PushTemplatesRequest(
            SourceServerID="source-server-id",
            DestinationServerID="destination-server-id",
            PerformChanges=True,
        )
    )
    print(f"Pushed — {result.total_count} template(s) updated.")

asyncio.run(main())

Further Reading

Clone this wiki locally