Tenant default preferences

and cover the concepts behind this page.

Preferences are usually the first reason people reach for tenants. A customer’s admin wants a category of notification switched off across their whole company, and that has to hold for users who never open a preference center. A tenant default sets a topic’s starting state for everyone in that organization. It overrides the workspace default for any send that names the tenant, and each user can still change their own from there. A tenant default is not a way to force a setting. A user who opts out stays opted out, because their own preference sits below the tenant’s in the . Mark a topic REQUIRED when it is transactional and nobody should be able to switch it off, which is the only status that ignores what the user chose.

A tenant default sets a topic’s status and nothing else. Channel routing is read from each user’s own preference record. A tenant’s has_custom_routing and custom_routing have no effect at send time, even though the API accepts and returns them, so a tenant that looks correctly configured can route nothing. To route a topic to specific channels, set it on the .

Prerequisites

Set tenant defaults

Set defaults in the console

In the console, a tenant stores its defaults as a single default_preferences JSON object that you edit directly. Go to the tenant in the (Directory → Tenants) and open its Details tab. In the Default Preferences section, paste a JSON object whose items array holds one entry per topic. Each entry takes the topic_id as id and a status of OPTED_IN, OPTED_OUT, or REQUIRED. Save.

A tenant's Details tab with the Default Preferences JSON editor holding three topic entries and reporting Valid JSON — The Default Preferences JSON editor on a tenant's Details tab in the console.

This example opts one topic in, makes a second impossible to turn off, and opts out of a third. Topics you leave out keep their workspace default:

{
  "items": [
    {
      "id": "pt_01kx4h2jdafq8bk996nn92357r",
      "status": "OPTED_IN"
    },
    {
      "id": "pt_01kx4h9m2rdvc7yq5tb8n30k4e",
      "status": "REQUIRED"
    },
    {
      "id": "pt_01kx4hb7t8fzs2mp6wc4j91xgd",
      "status": "OPTED_OUT"
    }
  ]
}

Set a default with the API

sets tenant defaults one topic at a time from your backend. Only the topics you include override the workspace default. Topics you leave out fall back to their workspace default state. The same default_preferences object shown above is what you send when you create or replace the tenant through the . Set one topic’s default with a body shaped like a topic, carrying its status.

import Courier from '@trycourier/courier';

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

await client.tenants.preferences.items.update('pt_01kx4h2jdafq8bk996nn92357r', {
  tenant_id: 'acme-corp',
  status: 'OPTED_IN',
});

import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
client.tenants.preferences.items.update(
    topic_id="pt_01kx4h2jdafq8bk996nn92357r",
    tenant_id="acme-corp",
    status="OPTED_IN",
)

curl -X PUT https://api.courier.com/tenants/acme-corp/default_preferences/items/pt_01kx4h2jdafq8bk996nn92357r \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "OPTED_IN" }'

require "courier"

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

result = courier.tenants.preferences.items.update("pt_01kx4h2jdafq8bk996nn92357r", tenant_id: "acme-corp", status: :OPTED_IN)

puts(result)

err := client.Tenants.Preferences.Items.Update(
	context.TODO(),
	"pt_01kx4h2jdafq8bk996nn92357r",
	courier.TenantPreferenceItemUpdateParams{
		TenantID: "acme-corp",
		SubscriptionTopicNew: courier.SubscriptionTopicNewParam{
			Status: courier.SubscriptionTopicNewStatusOptedIn,
		},
	},
)

ItemUpdateParams params = ItemUpdateParams.builder()
    .tenantId("acme-corp")
    .topicId("pt_01kx4h2jdafq8bk996nn92357r")
    .subscriptionTopicNew(SubscriptionTopicNew.builder()
        .status(SubscriptionTopicNew.Status.OPTED_IN)
        .build())
    .build();
client.tenants().preferences().items().update(params);

$result = $client->tenants->preferences->items->update(
  'pt_01kx4h2jdafq8bk996nn92357r',
  tenantID: 'acme-corp',
  status: 'OPTED_IN',
);

ItemUpdateParams parameters = new()
{
    TenantID = "acme-corp",
    TopicID = "pt_01kx4h2jdafq8bk996nn92357r",
    Status = Status.OptedIn,
};

await client.Tenants.Preferences.Items.Update(parameters);

courier tenants:preferences:items update \
  --api-key "$COURIER_API_KEY" \
  --tenant-id acme-corp \
  --topic-id pt_01kx4h2jdafq8bk996nn92357r \
  --status OPTED_IN

With Courier MCP, opt acme-corp into that topic by default.

Remove a tenant default

removes a tenant default for a topic, reverting it to the workspace default:

import Courier from '@trycourier/courier';

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

await client.tenants.preferences.items.delete('pt_01kx4h2jdafq8bk996nn92357r', { tenant_id: 'acme-corp' });

import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
client.tenants.preferences.items.delete(
    topic_id="pt_01kx4h2jdafq8bk996nn92357r",
    tenant_id="acme-corp",
)

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

require "courier"

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

result = courier.tenants.preferences.items.delete("pt_01kx4h2jdafq8bk996nn92357r", tenant_id: "acme-corp")

puts(result)

err := client.Tenants.Preferences.Items.Delete(
	context.TODO(),
	"pt_01kx4h2jdafq8bk996nn92357r",
	courier.TenantPreferenceItemDeleteParams{
		TenantID: "acme-corp",
	},
)

ItemDeleteParams params = ItemDeleteParams.builder()
    .tenantId("acme-corp")
    .topicId("pt_01kx4h2jdafq8bk996nn92357r")
    .build();
client.tenants().preferences().items().delete(params);

$result = $client->tenants->preferences->items->delete(
  'pt_01kx4h2jdafq8bk996nn92357r', tenantID: 'acme-corp'
);

ItemDeleteParams parameters = new()
{
    TenantID = "acme-corp",
    TopicID = "pt_01kx4h2jdafq8bk996nn92357r",
};

await client.Tenants.Preferences.Items.Delete(parameters);

courier tenants:preferences:items delete \
  --api-key "$COURIER_API_KEY" \
  --tenant-id acme-corp \
  --topic-id pt_01kx4h2jdafq8bk996nn92357r

With Courier MCP, remove acme-corp's default for that topic.

Read the defaults back

Read the tenant back to confirm its defaults. The default_preferences field on the returned tenant holds the topics you set. Call the :

import Courier from '@trycourier/courier';

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

const tenant = await client.tenants.retrieve('acme-corp');

console.log(tenant.default_preferences);

import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
tenant = client.tenants.retrieve("acme-corp")
print(tenant.default_preferences)

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

require "courier"

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

tenant = courier.tenants.retrieve("acme-corp")

puts(tenant.default_preferences)

tenant, err := client.Tenants.Get(context.TODO(), "acme-corp")

Tenant tenant = client.tenants().retrieve("acme-corp");

$tenant = $client->tenants->retrieve('acme-corp');

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

var tenant = await client.Tenants.Retrieve(parameters);

courier tenants retrieve \
  --api-key "$COURIER_API_KEY" \
  --tenant-id acme-corp

With Courier MCP, show me acme-corp's tenant settings and default preferences.

Verify the tenant default

Pick a user with no preference set for the Topic. Send them a message mapped to it in the Tenant’s context, including tenant_id. Confirm delivery follows the Tenant default, not the workspace default.

Limits & behavior

Reading a user’s preferences does not show you the tenant default. The call returns the topic-level default_status even when , so a tenant default you set correctly looks absent from the user’s side. Read the tenant itself for its defaults, and use a test send to confirm what a user receives.
Topics you leave out keep the workspace default. default_preferences is a partial override rather than a full replacement, so removing a topic from it restores the workspace state rather than clearing the topic.
A tenant default only applies to sends that name the tenant. The same user, sent to without a tenant_id, falls back to the workspace default unless auto-infer resolves the tenant for you.

Get started

Send messages

Journeys

Broadcasts

Design

Recipients

Tenants

Monitoring

Workspaces

Resources

Tenant default preferences

Prerequisites

Set tenant defaults

Limits & behavior

​Prerequisites

​Set tenant defaults

​Limits & behavior

Prerequisites

Set tenant defaults

Limits & behavior