Let customers edit their notifications

Ship a Notifications tab in your product. Each customer edits their own emails, and your send never changes. Every edit belongs to that customer’s tenant. You mount the editor, scope a token to one tenant, and keep sending one template that resolves differently for each of them.

What you will build

Prerequisites

A React app on 18.2.0 or newer

Seed the tenant’s template

Do this when your app creates the org. The editor opens on your wording instead of an empty page, and the send has content before anyone edits anything. The template_id is an id you choose. Use the same one for every tenant, so your send never branches. 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.

The full lifecycle of a tenant template, including versions and deletes, is in .

Put the editor in your app

Install the package

npm install @trycourier/react-designer

Issue a token scoped to one tenant

The editor runs in the browser, so it authenticates with a JWT rather than your API key. Mint one on your backend for the admin who is signed in, scoped to the tenant they belong to.

const { token } = await client.auth.issueToken({
  scope: "user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write tenant:acme-corp:brand:read tenant:acme-corp:brand:write",
  expires_in: "1 day",
});

response = client.auth.issue_token(
    scope="user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write tenant:acme-corp:brand:read tenant:acme-corp:brand:write",
    expires_in="1 day",
)

curl --request POST \
  --url https://api.courier.com/auth/issue-token \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "scope": "user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write tenant:acme-corp:brand:read tenant:acme-corp:brand:write",
    "expires_in": "1 day"
  }'

response = courier.auth.issue_token(
  scope: "user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write tenant:acme-corp:brand:read tenant:acme-corp:brand:write",
  expires_in: "1 day"
)

response, err := client.Auth.IssueToken(context.TODO(), courier.AuthIssueTokenParams{
  Scope:     "user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write tenant:acme-corp:brand:read tenant:acme-corp:brand:write",
  ExpiresIn: "1 day",
})

AuthIssueTokenParams params = AuthIssueTokenParams.builder()
    .scope("user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write tenant:acme-corp:brand:read tenant:acme-corp:brand:write")
    .expiresIn("1 day")
    .build();

var response = client.auth().issueToken(params);

$response = $client->auth->issueToken(
    scope: 'user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write tenant:acme-corp:brand:read tenant:acme-corp:brand:write',
    expiresIn: '1 day',
);

var response = await client.Auth.IssueToken(new AuthIssueTokenParams
{
    Scope = "user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write tenant:acme-corp:brand:read tenant:acme-corp:brand:write",
    ExpiresIn = "1 day"
});

courier auth issue-token \
  --scope "user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write tenant:acme-corp:brand:read tenant:acme-corp:brand:write" \
  --expires-in "1 day"

With Courier MCP, issue a one-day token for user_123 that can edit acme-corp's templates and brand.

Read the tenant id from your own session, never from the browser. A token carrying tenants: in place of tenant:acme-corp: grants every customer at once. Every scope is listed in .

Mount the editor on your settings page

TemplateProvider takes the template id you seeded, the tenant, and the token. brandEditor puts logo, colors, and footer beside the content, so one screen covers both.

import "@trycourier/react-designer/styles.css";
import { TemplateProvider, TemplateEditor } from "@trycourier/react-designer";

export function NotificationSettings({ tenantId, token }) {
  return (
    <TemplateProvider templateId="welcome" tenantId={tenantId} token={token}>
      <TemplateEditor routing={{ method: "single", channels: ["email"] }} brandEditor />
    </TemplateProvider>
  );
}

routing limits which channels the customer sees. Leave it out and they get every channel your workspace sends on. Every prop is in .

Publish on your own terms

The editor auto-saves a draft and ships its own Publish button. Hide that button when publishing should run through your own review or your own UI, then call the hook.

import { useTemplateActions } from "@trycourier/react-designer";

function PublishButton() {
  const { publishTemplate } = useTemplateActions();
  return <button onClick={() => publishTemplate()}>Save and publish</button>;
}

Render it beside <TemplateEditor hidePublish />. A draft the customer never publishes does not reach anyone, so the send keeps using the last published version.

Send what the customer published

Name the tenant's template

Reference it as tenant/<template_id> and set the tenant in the context. The word tenant is literal, and 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.

This is the whole payoff. The call is identical for every customer, and only tenant_id changes.

Reach the whole org

Swap to for a tenant_id and Courier sends to every member of that org, still in their own content and brand. covers each targeting shape.

Verify

Edit as a customer would

Open your settings page signed in as a user of acme-corp, change a line of copy and the logo, then publish.

Read the template back

and confirm the published content carries the edit.

Send and compare two orgs

Send to a user in acme-corp and a user in beta-inc, then open both in . Same call, same template id, two different messages.

Troubleshooting

Symptom	Cause	Fix
The editor renders blank	No template exists at that id for this tenant	Seed it with the create call above
Requests from the editor 401	The token expired, or it is missing a scope	Reissue with the `notifications` and `brand` scopes
Edits save but never arrive	The draft was never published	Publish from the editor, or call `publishTemplate`
The send renders your copy, not theirs	The `tenant/` prefix or `context.tenant_id` is missing	Send `template: "tenant/welcome"` in that tenant’s context
One customer sees another’s content	The token used a plural `tenants:` scope	Scope it to `tenant:<id>:` for the signed-in org

Brand, defaults, and templates all resolve from the same tenant, in the order set out in . To give a customer their own defaults as well as their own copy, see .

Get started

Send your first message

Build a notification

Send to many people

Send when something happens

Let users choose

Go live

Move to Courier

Let customers edit their notifications

What you will build

Prerequisites

Seed the tenant’s template

Put the editor in your app

Send what the customer published

Verify

Troubleshooting

​What you will build

​Prerequisites

​Seed the tenant’s template

​Put the editor in your app

​Send what the customer published

​Verify

​Troubleshooting

What you will build

Prerequisites

Seed the tenant’s template

Put the editor in your app

Send what the customer published

Verify

Troubleshooting