Tenant templates

covers the concepts behind this page.

A tenant template overrides one of your templates for a single customer, keyed by an id you choose. Their admin can rewrite the copy in their own voice, and only their users see it. Everyone else keeps the default. You create, publish, and delete tenant templates through the API, then reference them in a send with the tenant/<template_id> format. A tenant template is not a separate template you have to route to. Your send logic does not branch on which customer it is for. It names the same id every time, and Courier merges the tenant’s version over the message when one exists. Leave the tenant/ prefix off and the send succeeds with the wrong content. Courier reads template: "welcome" as your workspace template and renders that, because a template id that resolves is not an error. The customer’s edits are not in the message.

Tenant templates have no console UI, so create, list, and delete them through the API, as every step below does. To hand the editing to your customer instead, in your own app.

Prerequisites

Manage tenant templates

Create or update a tenant template

Create or replace a tenant’s template with the . The template_id is an ID you choose for this tenant’s template. Every element sits inside a channel block, the same rule follow.

import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const response = await client.tenants.templates.replace('welcome', {
  tenant_id: 'acme-corp',
  template: {
    content: {
      version: '2022-01-01',
      elements: [
        {
          type: 'channel',
          channel: 'email',
          elements: [{ type: 'text', content: 'Welcome to Acme Corp!' }],
        },
      ],
    },
  },
});

console.log(response.id);

import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.tenants.templates.replace(
    template_id="welcome",
    tenant_id="acme-corp",
    template={
        "content": {
            "version": "2022-01-01",
            "elements": [
                {
                    "type": "channel",
                    "channel": "email",
                    "elements": [{"type": "text", "content": "Welcome to Acme Corp!"}],
                }
            ],
        }
    },
)
print(response.id)

curl -X PUT https://api.courier.com/tenants/acme-corp/templates/welcome \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "channel",
            "channel": "email",
            "elements": [{ "type": "text", "content": "Welcome to Acme Corp!" }]
          }
        ]
      }
    }
  }'

require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.tenants.templates.replace(
  "welcome",
  tenant_id: "acme-corp",
  template: {
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "channel",
          channel: "email",
          elements: [{ type: "text", content: "Welcome to Acme Corp!" }]
        }
      ]
    }
  }
)

puts(response)

// The typed elemental model has no field for a channel's child elements, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "channel",
      "channel": "email",
      "elements": [{ "type": "text", "content": "Welcome to Acme Corp!" }]
    }
  ]
}`))

response, err := client.Tenants.Templates.Replace(
	context.TODO(),
	"welcome",
	courier.TenantTemplateReplaceParams{
		TenantID: "acme-corp",
		PutTenantTemplateRequest: courier.PutTenantTemplateRequestParam{
			Template: courier.TenantTemplateInputParam{Content: content},
		},
	},
)

TemplateReplaceParams params = TemplateReplaceParams.builder()
    .tenantId("acme-corp")
    .templateId("welcome")
    .putTenantTemplateRequest(PutTenantTemplateRequest.builder()
        .template(TenantTemplateInput.builder()
            .content(ElementalContent.builder()
                // The channel builder has no addElement, so its children go in as an additional property.
                .addElement(ElementalChannelNodeWithType.builder()
                    .type(ElementalChannelNodeWithType.Type.CHANNEL)
                    .channel("email")
                    .putAdditionalProperty("elements", JsonValue.from(java.util.List.of(
                        java.util.Map.of("type", "text", "content", "Welcome to Acme Corp!"))))
                    .build())
                .version("2022-01-01")
                .build())
            .build())
        .build())
    .build();
client.tenants().templates().replace(params);

$response = $client->tenants->templates->replace(
  'welcome',
  tenantID: 'acme-corp',
  template: [
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'channel',
          'channel' => 'email',
          'elements' => [['type' => 'text', 'content' => 'Welcome to Acme Corp!']],
        ],
      ],
    ],
  ],
);

TemplateReplaceParams parameters = new()
{
    TenantID = "acme-corp",
    TemplateID = "welcome",
    Template = new()
    {
        Content = new()
        {
            Version = "2022-01-01",
            Elements =
            [
                // Elemental nodes expose no typed content property, so build the node from raw JSON.
                ElementalChannelNodeWithType.FromRawUnchecked(
                    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
                    {
                      "type": "channel",
                      "channel": "email",
                      "elements": [{ "type": "text", "content": "Welcome to Acme Corp!" }]
                    }
                    """)),
            ],
        },
    },
};

await client.Tenants.Templates.Replace(parameters);

courier tenants:templates replace \
  --api-key "$COURIER_API_KEY" \
  --tenant-id acme-corp \
  --template-id welcome \
  --template '{"content":{"version":"2022-01-01","elements":[{"type":"channel","channel":"email","elements":[{"type":"text","content":"Welcome to Acme Corp!"}]}]}}'

With Courier MCP, create a welcome template for acme-corp that greets their users.

Publish the template

Changes take effect once published. to make it live.

import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const response = await client.tenants.templates.publish('welcome', {
  tenant_id: 'acme-corp',
});

console.log(response.id);

import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.tenants.templates.publish(
    template_id="welcome",
    tenant_id="acme-corp",
)
print(response.id)

curl -X POST https://api.courier.com/tenants/acme-corp/templates/welcome/publish \
  -H "Authorization: Bearer $COURIER_API_KEY"

require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.tenants.templates.publish("welcome", tenant_id: "acme-corp")

puts(response)

response, err := client.Tenants.Templates.Publish(
	context.TODO(),
	"welcome",
	courier.TenantTemplatePublishParams{
		TenantID: "acme-corp",
	},
)

TemplatePublishParams params = TemplatePublishParams.builder()
    .tenantId("acme-corp")
    .templateId("welcome")
    .build();
client.tenants().templates().publish(params);

$response = $client->tenants->templates->publish(
  'welcome', tenantID: 'acme-corp'
);

TemplatePublishParams parameters = new()
{
    TenantID = "acme-corp",
    TemplateID = "welcome",
};

await client.Tenants.Templates.Publish(parameters);

courier tenants:templates publish \
  --api-key "$COURIER_API_KEY" \
  --tenant-id acme-corp \
  --template-id welcome

With Courier MCP, publish acme-corp's welcome template.

List and read templates

, , or read a .

import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const templates = await client.tenants.templates.list('acme-corp');

console.log(templates.has_more);

import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
templates = client.tenants.templates.list(
    tenant_id="acme-corp",
)
print(templates.has_more)

curl -X GET https://api.courier.com/tenants/acme-corp/templates \
  -H "Authorization: Bearer $COURIER_API_KEY"

require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

templates = courier.tenants.templates.list("acme-corp")

puts(templates)

templates, err := client.Tenants.Templates.List(
	context.TODO(),
	"acme-corp",
	courier.TenantTemplateListParams{},
)

TemplateListResponse templates = client.tenants().templates().list("acme-corp");

$templates = $client->tenants->templates->list('acme-corp');

TemplateListParams parameters = new() { TenantID = "acme-corp" };

var templates = await client.Tenants.Templates.List(parameters);

courier tenants:templates list \
  --api-key "$COURIER_API_KEY" \
  --tenant-id acme-corp

With Courier MCP, list acme-corp's templates.

Delete a template

removes it. This is the only way to remove one, since there is no console UI for it.

import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

await client.tenants.templates.delete('welcome', { tenant_id: 'acme-corp' });

import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
client.tenants.templates.delete(
    template_id="welcome",
    tenant_id="acme-corp",
)

curl -X DELETE https://api.courier.com/tenants/acme-corp/templates/welcome \
  -H "Authorization: Bearer $COURIER_API_KEY"

require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

result = courier.tenants.templates.delete("welcome", tenant_id: "acme-corp")

puts(result)

err := client.Tenants.Templates.Delete(
	context.TODO(),
	"welcome",
	courier.TenantTemplateDeleteParams{
		TenantID: "acme-corp",
	},
)

TemplateDeleteParams params = TemplateDeleteParams.builder()
    .tenantId("acme-corp")
    .templateId("welcome")
    .build();
client.tenants().templates().delete(params);

$result = $client->tenants->templates->delete(
  'welcome', tenantID: 'acme-corp'
);

TemplateDeleteParams parameters = new()
{
    TenantID = "acme-corp",
    TemplateID = "welcome",
};

await client.Tenants.Templates.Delete(parameters);

courier tenants:templates delete \
  --api-key "$COURIER_API_KEY" \
  --tenant-id acme-corp \
  --template-id welcome

With Courier MCP, delete acme-corp's welcome template.

Send with the tenant template

Reference the tenant template in a send with template: "tenant/<template_id>", and set the tenant in the context. The word tenant is literal. Your tenant ID goes in context.tenant_id.

import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const { requestId } = await client.send.message({
  message: {
    template: 'tenant/welcome',
    context: { tenant_id: 'acme-corp' },
    to: { user_id: 'user_123' },
  },
});

console.log(requestId);

import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.send.message(
    message={
        "template": "tenant/welcome",
        "context": {"tenant_id": "acme-corp"},
        "to": {"user_id": "user_123"},
    },
)
print(response.request_id)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "tenant/welcome",
      "context": { "tenant_id": "acme-corp" },
      "to": { "user_id": "user_123" }
    }
  }'

require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.send_.message(
  message: {
    template: "tenant/welcome",
    context: { tenant_id: "acme-corp" },
    to: { user_id: "user_123" }
  }
)

puts(response)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		Template: courier.String("tenant/welcome"),
		Context:  shared.MessageContextParam{TenantID: courier.String("acme-corp")},
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .template("tenant/welcome")
        .context(JsonValue.from(java.util.Map.of("tenant_id", "acme-corp")))
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .build())
    .build();
client.send().message(params);

$response = $client->send->message(
  message: [
    'template' => 'tenant/welcome',
    'context' => ['tenantID' => 'acme-corp'],
    'to' => ['userID' => 'user_123'],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        Template = "tenant/welcome",
        Context = new MessageContext { TenantID = "acme-corp" },
        To = new UserRecipient { UserID = "user_123" },
    },
};

await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"template":"tenant/welcome","context":{"tenant_id":"acme-corp"},"to":{"user_id":"user_123"}}'

With Courier MCP, send acme-corp's welcome template to user_123.

At send time, Courier merges the tenant template’s content over the message and routes it normally.

Verify the template

After publishing, and confirm the content is what you sent. Then send with template: "tenant/<template_id>" in the tenant’s context and check the message log to confirm the tenant’s content rendered.

Limits & behavior

A draft that is never published reaches nobody. Creating or replacing a tenant template writes a draft, and the send keeps rendering the last published version until you publish the new one.
The tenant id sits in a different place per method. list takes it positionally while retrieve, replace, and publish take it in the body. Check the installed SDK types under resources/tenants/ before writing against these.
Tenant templates have no console UI. No screen creates, lists, or deletes them, so a template that exists only for one customer is invisible to anyone looking in .

Get started

Send messages

Journeys

Broadcasts

Design

Recipients

Tenants

Monitoring

Workspaces

Resources

Tenant templates

Prerequisites

Manage tenant templates

Limits & behavior

​Prerequisites

​Manage tenant templates

​Limits & behavior

Prerequisites

Manage tenant templates

Limits & behavior