> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Domains and channels

> Manage organization addresses, short-link domains, email-domain verification, and notification policy as separate systems with separate proof and rollback.

“Domain” and “channel” are often grouped under administration, but they do not solve the same problem. An organization subdomain identifies where staff use KayanOS; a custom short-link domain controls selected short URLs; an email domain is a verified mail identity/configuration boundary; and notification preferences decide whether an eligible member may be alerted through a configured channel. One successful setting does not activate the others.

For the Directorate of Citizen Services, keep these controls distinct. A change must have an owner, evidence of verification, a date, a rollback plan, and a safe test that does not send a citizen-facing message or expose a live service link.

## Goal

Configure each address or communication control for its actual purpose, prove it is ready, and avoid dangerous assumptions such as “the DNS record is verified, so every email or notification will be delivered.”

## Four systems, four boundaries

| System                   | Purpose                                                                                   | What it does not prove                                                                            |
| ------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Organization subdomain   | The Directorate’s organization-specific KayanOS address                                   | That a custom short-link domain, email domain, or portal is configured                            |
| Short-link custom domain | The host used for approved generated short links                                          | That a recipient is authorized to open the target or that the target is public                    |
| Email domain             | A domain verification/configuration control for organizational mail                       | That a member has an active mailbox, an allowed sender identity, or successful delivery           |
| Notification policy      | Catalog, organization, and member preference/readiness for in-app and configured channels | That every member has consent, contact data, a device permission, or an external delivery outcome |

Start with the system that has the actual business need. Do not configure a DNS record merely because an organization wants a more polished address.

## Organization address

The organization subdomain is maintained in [Organization settings](/admin/organization-settings). It accepts a lower-case 3–63 character label using letters, digits, and internal hyphens. KayanOS checks availability and redirects the browser to the new origin after a successful save.

Before changing it:

1. Confirm the approved Directorate name and the DNS/deployment owner responsible for the organization address.
2. Inventory staff bookmarks, internal references, approved portal links, and integrations that may use the current address.
3. Check availability in the form and have a second administrator verify the spelling.
4. Save in a controlled window, then open the new address, sign in if required, and confirm the correct organization context.
5. Update only the approved references after the new address works. Retain the old address information in the change record according to policy.

This address is not a public-access switch. A direct link still requires the recipient’s applicable access and the record’s scope.

## Add and verify a short-link domain

Use a custom short-link domain only when the Directorate has a controlled reason to distribute short KayanOS links. The short-link domain screen presents the domain and the DNS records needed for verification.

1. Obtain written approval for the domain owner, intended link audience, retention period, and incident contact.
2. Add the requested domain in **Administration → Domains and channels**.
3. Copy the exact DNS record name, type, and value shown by KayanOS to the organization’s DNS provider. Do not invent a record based on a different provider’s example.
4. Wait for DNS propagation, then use the verification/status control in KayanOS. Keep the domain unavailable for operational use until it reports the required verified/active state.
5. Create a controlled short link to an approved non-production target. Open it as an authorized test member and an unauthorized test member.
6. Confirm that the authorized test reaches the intended target and the unauthorized test remains denied or empty according to access rules.

Deleting, disabling, or changing a custom short-link domain can affect links that use it. Inventory issued links and communicate a migration/retirement path before removing a domain. A short link is navigation, not proof of identity, consent, or access.

## Verify an email domain without overpromising delivery

Email-domain administration is separate from the Email workspace and from a member’s email account. Follow the organization’s approved email-domain verification process:

1. Confirm that the Directorate controls the proposed domain and that an email/domain administrator owns the change.
2. Add the domain and publish the exact DNS evidence requested by KayanOS.
3. Wait for the verification status. If DNS has not propagated or the record differs, correct the provider record rather than repeatedly changing the KayanOS domain entry.
4. Record the verified status, owner, date, and any approved sender policy.
5. Separately configure member mailbox accounts and sender identities where required. A verified domain does not create a mailbox or authorize every member to send from it.
6. Test a policy-approved internal message only when the mailbox, sender identity, recipients, and delivery process are all ready. Review the send result; a send attempt can fail or be partial.

Do not publish an external service address just because the domain appears in an administration list. Service communication requires its own approved content, recipient, retention, and delivery controls.

## Manage notification policy and readiness

Notification settings are not DNS settings. Effective delivery follows the notification catalog, organization policy, and member preference, then the readiness of the selected channel.

For each notification type, decide:

* which event should create the in-app item;
* which members or roles should be eligible to receive it;
* whether an external configured channel is permitted by policy;
* what contact data, consent, device registration, or browser permission is required;
* how quiet hours and priority exceptions should behave; and
* what staff should do if a channel is unavailable.

In-app activity can remain visible even when a non-in-app delivery is delayed by quiet hours or unavailable. Staff should open the related task or record for the current state; a notification preference is never proof that a decision was received or a citizen was contacted.

## Directorate scenario

The Directorate adopts an approved organization address, then considers a separate short-link domain for internal service reminders. The administrator verifies the DNS record in a non-production or controlled context and tests a link to a synthetic Citizen Service Request. The authorized Registry Officer reaches the record; a member outside the Service Centre scope does not gain access.

Separately, the mail administrator verifies a Directorate domain. The service team then connects only the approved mailbox and checks a draft/send result using an internal recipient. Finally, the notification owner enables an in-app task alert and tests quiet-hour behavior without treating any external alert as a citizen communication.

## Validation and rollback

| Change                 | Positive test                                                    | Negative/safe test                                                                              |
| ---------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Organization subdomain | New origin loads the correct organization context                | Old bookmarks are reviewed; no user receives broader access from the URL                        |
| Short-link domain      | Verified status and authorized controlled link open              | Unauthorized member cannot use the link to bypass record scope                                  |
| Email domain           | Verification status is recorded                                  | No member assumes a mailbox/sender/delivery right from verification alone                       |
| Notification policy    | Intended in-app alert appears for the configured eligible member | Missing contact/device/consent or quiet hours prevents/defers non-in-app delivery as configured |

For rollback, retain the prior approved organization address/domain status, disable further distribution of affected links, and notify the owner before deleting or redirecting anything. Do not remove evidence of a domain configuration while an incident is under review.

## Troubleshooting

| Symptom                                            | Check first                                                                                    | Safe response                                                                              |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| A short-link domain remains unverified             | Exact DNS name/type/value, propagation, and domain status                                      | Correct the DNS record at its owner; do not create duplicate domain entries                |
| A short link opens but target is denied            | Target record scope and recipient role                                                         | This is expected for unauthorized users; adjust access only when business need is approved |
| A verified email domain cannot send                | Active mailbox, allowed sender identity, recipient policy, and delivery result                 | Configure the required mailbox/sender separately; save a draft until authorized            |
| A notification did not arrive externally           | Member preference, channel readiness, consent/contact data, device permission, and quiet hours | Check in-app activity and the underlying work; do not assume the event was missed          |
| A domain change breaks a known link                | Which domain the link used and whether it was replaced/changed                                 | Stop distributing it, restore or migrate through the approved domain owner                 |
| Team expects a public portal from a domain setting | Portal publication, form eligibility, and public access configuration                          | Configure the portal separately; a domain does not publish a form                          |

## Related guides

* Change the organization address safely in [Organization settings](/admin/organization-settings).
* Connect, draft, and verify mail outcomes in [Email](/work/email).
* Configure everyday alert behavior in [Home and notifications](/work/home-and-notifications).
* Design controlled public intake in [Public portal](/build/public-portal).

![KayanOS domain and channel settings for the Directorate of Citizen Services.](https://kayanos.app/docs-images/en/admin/domains-and-channels.png)