Subscribe one or more users or other objects TO this object. The recipient list can mix users and objects in a single call.

Recipients: users by distinct_id, objects by object_type + id. Each entry's shape follows the SuprSend recipient format. Optional properties attach metadata to each subscription (role, joined_at, etc.).

When NOT to use:

• To remove subscribers — there is no remove tool; use the SuprSend API directly.

• For mailing-list / segment membership — those are managed via the Lists API.

• For preference changes on existing subscribers — use the per-user / per-object preference tools.

Side effects: each successful subscription is a separate row. Calling this twice with the same recipient creates duplicate-looking entries; check existing state with get_suprsend_object_subscriptions first if duplicates would be a problem.

Returns: the created subscription records on success.

Fetch the full content of a SuprSend documentation page when a snippet from search_suprsend_documentation is insufficient.

When to use: after search_suprsend_documentation, when the snippet excerpt doesn't fully answer and you need surrounding context, code examples, or full reference material.

When NOT to use: to discover documentation — search first; don't construct uris yourself.

Returns: the page contents as markdown.

Get a SuprSend object's full state by object_type + object_id. Objects are non-user entities — organizations, projects, vehicles, devices — namespaced by object_type.

When to use: the user references an object by id and you need its stored properties or channel identifiers.

When NOT to use:

• For users — use get_suprsend_user.

• For preferences only — use get_suprsend_object_preferences.

• For followers / members — use get_suprsend_object_subscriptions.

Returns: YAML mirroring get_suprsend_user's shape — object_type, object_id, properties (custom fields), created_at, updated_at, and a channels array (each entry has channel value, status, perma_status).

Read an object's category-level notification preferences and (optionally) per-channel overrides.

When to use:

• Before update_suprsend_category_preference_object, to read current state.

• Before sending to an object, to check delivery permission.

When NOT to use:

• For the object's identity or channels — use get_suprsend_object.

• For users — use get_suprsend_user_preferences.

Returns: the object's preference tree. Pass category to scope to one preference; omit for the full tree. Set channel_preferences=true to include per-channel overrides.

List users / objects subscribed TO this object (its followers / members). Subscriptions are stored on the followed object.

When to use: the user asks "who follows project X?", "who's a member of organization Y?", or you need to enumerate an object's inbound subscribers.

When NOT to use:

• For the inverse direction (what a user follows) — use get_suprsend_user_objects_subscriptions.

• For mailing-list members — use get_suprsend_user_list_subscriptions on each user.

Returns: a paginated list of subscriber {type, id} entries. Set channel_preferences=true to also include each subscriber's channel preferences for this object. Default limit is 20.

Get a tenant's settings, branding metadata, and custom properties by tenant_id. Tenants are sub-accounts of a workspace, modeling end-customers in multi-tenant SaaS deployments.

When to use: the user references a tenant by id and you need its full state.

When NOT to use:

• To enumerate all tenants — use get_suprsend_tenants.

• For tenant-level preference defaults — use get_tenant_default_preference.

Returns: the tenant's settings (branding URLs, contact info, custom fields).

List all tenants in the workspace. Use to discover tenant_ids before calling get_suprsend_tenant or upsert_suprsend_tenant.

Returns: up to limit tenants (default 100) with their id and properties.

Get a SuprSend user's full state by distinct_id. Users are end recipients of notifications, identified by your application's user id.

When to use: the user references a recipient by id and you need their stored properties or channel identifiers.

When NOT to use:

• For non-user entities (organizations, projects, vehicles) — use get_suprsend_object.

• For preferences only — use get_suprsend_user_preferences.

• For mailing-list / object subscriptions — use get_suprsend_user_list_subscriptions or get_suprsend_user_objects_subscriptions.

Returns: YAML with distinct_id, properties (custom fields like name, plan, lang), created_at, updated_at, and a channels array — each entry has the channel value, status, and perma_status (e.g., bounced, blocked, soft-bounced).

List the SuprSend Lists this user belongs to. Lists are workspace-level recipient groups (segments / mailing lists), distinct from object follows.

When to use: the user asks "what mailing lists is X on?" or "what segments include X?".

When NOT to use:

• For object follows (X follows project Y) — use get_suprsend_user_objects_subscriptions.

• For followers OF an object — use get_suprsend_object_subscriptions.

Returns: a paginated list of List metadata. Default limit is 20; raise it for larger results.

List the objects this user is subscribed TO — what the user follows.

When to use: the user asks "what does X follow?", "what projects is X in?", or you need to enumerate a user's outbound subscriptions.

When NOT to use:

• For followers OF an object (inverse direction) — use get_suprsend_object_subscriptions.

• For mailing-list / segment membership — use get_suprsend_user_list_subscriptions.

Returns: a paginated list of {object_type, object_id} entries. Default limit is 20.

Read a user's category-level notification preferences and (optionally) per-channel overrides.

When to use:

• Before update_suprsend_users_preferences, to read current state.

• The user asks what categories a recipient is opted in/out of.

• Before sending, to check delivery permission for a category or channel.

When NOT to use:

• For the user's identity or channel identifiers — use get_suprsend_user.

• For tenant-level defaults — use get_tenant_default_preference.

• For object preferences — use get_suprsend_object_preferences.

Returns: the user's preference tree. Pass category to scope to one preference; omit for the full tree. Set channel_preferences=true to include per-channel overrides.

Read a tenant's default category preferences — the inheritance baseline applied to new users in this tenant.

When to use:

• Before update_suprsend_tenant_default_preference, to read current defaults.

• To diagnose why new users have unexpected preference state.

When NOT to use:

• For individual user / object preferences — use get_suprsend_user_preferences or get_suprsend_object_preferences.

Returns: the tenant's full default-preference tree.

List notification workflows in a workspace, in either draft or live mode.

mode=live returns the currently-active version of each workflow; mode=draft returns the staged-but-not-yet-promoted version. The two can differ — workflows often have a draft change in flight.

Returns: workflow slug, name, status, category, enabled state, and tags.

Search SuprSend's product documentation for technical guidance — APIs, SDKs, workflows, templates, tenants, lists, vendors, and connectors.

When to use:

• The user asks how a SuprSend feature works or how to integrate one.

• You need to verify a behavior before calling a write tool.

• You're debugging an integration error.

When NOT to use: for runtime operations on SuprSend resources (users, objects, tenants, workflows) — those have dedicated tools.

Returns: a JSON array of {uri, snippet}. Snippets are excerpts; if a snippet doesn't fully answer, follow up with fetch_suprsend_documentation on the relevant uri.

Tips: use precise technical terms ("workflow trigger conditions", not "the rule thing"); add synonyms if the first query returns nothing.

Set ONE category's preference for ONE object — opted in, opted out, or cant_unsubscribe (locked) — plus per-channel opt-outs within that category.

Replaces, does not merge. This call overwrites the existing preference for the named category. Previous opt-outs within the same category are lost; pass them again in opt_out_channels if you want to keep them.

When to use: changing a single category on a single object.

When NOT to use:

• For object-wide channel toggles ("block all SMS") — use update_suprsend_object_channel_preference.

• For users — use update_suprsend_users_preferences.

• For tenant defaults — use update_suprsend_tenant_default_preference.

Preference values: opt_in enables; opt_out disables; cant_unsubscribe locks the object from toggling this category.

Returns: updated preference state on success; structured error on failure.

Block or allow specific delivery channels for ONE object, applied across ALL categories.

is_restricted semantics: true blocks delivery on that channel; false re-enables it. Each entry in channel_preferences is a {channel, is_restricted} pair.

When NOT to use:

• For per-category control — use update_suprsend_category_preference_object.

• For users — use update_suprsend_user_channel_preference.

Side effects: takes effect on the next workflow run; in-flight notifications may still send.

Returns: updated channel-preference state on success.

Set the default category preference inherited by NEW users created in this tenant. Existing users are not affected; their preferences are independent.

preference values:

• opt_in — new users are opted into this category.

• opt_out — new users are opted out.

• cant_unsubscribe — new users are opted in AND locked from toggling.

mandatory_channels — channels users cannot disable for this category. blocked_channels — channels that cannot be enabled. visible_to_subscriber — whether end-users see this category in their preference UI.

When NOT to use:

• For per-user overrides — use update_suprsend_users_preferences.

• For per-object overrides — use update_suprsend_category_preference_object.

Side effects: changes apply only to users created AFTER this call. To retroactively update existing users, call update_suprsend_users_preferences per user.

Returns: the updated tenant default preference on success.

Block or allow specific delivery channels for ONE user, applied across ALL categories. Use this for "block all SMS to this user" or "allow only email" patterns.

is_restricted semantics: true blocks delivery on that channel; false re-enables it. Each entry in channel_preferences is a {channel, is_restricted} pair.

When NOT to use:

• For per-category control — use update_suprsend_users_preferences.

• For permanent invalidation (e.g., a bounced email) — that's set by SuprSend automatically as perma_status; don't try to override it here.

• For objects — use update_suprsend_object_channel_preference.

Side effects: takes effect on the next workflow run; in-flight notifications already in the queue may still send.

Returns: updated channel-preference state on success.

Set ONE category's preference for ONE user — opted in, opted out, or cant_unsubscribe (locked) — plus per-channel opt-outs within that category.

Replaces, does not merge. This call overwrites the existing preference for the named category. Previous opt-outs within the same category are lost; pass them again in opt_out_channels if you want to keep them.

When to use: changing a single category for a single user.

When NOT to use:

• For tenant-wide defaults — use update_suprsend_tenant_default_preference.

• For cross-category channel toggles ("block all SMS") — use update_suprsend_user_channel_preference.

• For the same flow on objects — use update_suprsend_category_preference_object.

Preference values: opt_in enables; opt_out disables; cant_unsubscribe locks the user from toggling this category in their preference UI.

Returns: updated preference state on success; structured error on failure (e.g., unknown category slug).

Modify properties or channel identifiers on a SuprSend object — a non-user entity like an organization, project, or vehicle. One call performs ONE action; for multiple changes, call this tool multiple times.

Actions:

• set, set_once, unset, remove — modify a scalar property by key/value. remove permanently deletes the key.

• append, increment — modify array / numeric values.

• add_email / remove_email, add_sms / remove_sms, add_whatsapp / remove_whatsapp, add_androidpush / remove_androidpush, add_iospush / remove_iospush, add_slack / remove_slack, add_ms_teams / remove_ms_teams, add_webpush / remove_webpush — register or deregister a delivery channel.

Channel registration is special. For channel identifiers ALWAYS use the dedicated add_ / remove_ actions — generic set / unset will not register the channel correctly with the delivery router. Slack and MS Teams additionally require the corresponding slack_details / ms_teams_details payload alongside the action; channel id alone is not enough.

When to use: creating an object or modifying its stored state — properties, channels, identifiers.

When NOT to use:

• For users — use upsert_suprsend_user instead.

• For preferences — use update_suprsend_category_preference_object (per category) or update_suprsend_object_channel_preference (across categories).

• For followers / members — use add_suprsend_object_subscriptions.

Side effects: remove and unset permanently delete data. add_ makes the object reachable on that channel for any future workflow run; remove_ stops delivery immediately.

object_type namespaces the object (e.g., "organization", "project") and is required.

Returns: the updated object on success; structured error with field reasons on failure.

Create a new tenant or update an existing tenant's properties. Tenants are sub-accounts of a workspace, used to model end-customers in multi-tenant SaaS apps.

tenant_properties is merged with existing — not replaced. Pass only the fields you want to change. Common fields include name, branding URLs, and contact info.

When NOT to use:

• For preference defaults — use update_suprsend_tenant_default_preference.

• For users / objects within a tenant — use upsert_suprsend_user / upsert_suprsend_object.

Returns: the updated tenant on success.

Modify properties or channel identifiers on a SuprSend user. One call performs ONE action; for multiple changes, call this tool multiple times.

Actions:

• set, set_once, unset, remove — modify a scalar property by key/value. remove permanently deletes the key.

• append, increment — modify array / numeric values.

• set_preferred_language, set_timezone — locale and timezone on the user.

• add_email / remove_email, add_sms / remove_sms, add_whatsapp / remove_whatsapp, add_androidpush / remove_androidpush, add_iospush / remove_iospush, add_slack / remove_slack — register or deregister a delivery channel.

Channel registration is special. For channel identifiers ALWAYS use the dedicated add_ / remove_ actions — generic set / unset will not register the channel correctly with the delivery router. Slack additionally requires the slack_details payload alongside the action.

When to use: creating a new user or modifying an existing user's stored state.

When NOT to use:

• For non-user entities — use upsert_suprsend_object.

• For preferences — use update_suprsend_users_preferences (per category) or update_suprsend_user_channel_preference (across categories).

• For tenant settings — use upsert_suprsend_tenant.

Side effects: remove and unset permanently delete data. add_ makes the user reachable on that channel for any future workflow run; remove_ stops delivery immediately.

Returns: the updated user on success; structured error with field reasons on failure.