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

# XMPP federation and email bridging

> Use JIDs, presence, rosters, federation, and the optional SMTP bridge

XMPP is Neuron's real-time federation layer. A bare JID has the form `account@domain`; a connected resource uses `account@domain/resource`.

## Federation

A client authenticates to its home Neuron. For a remote-domain JID, the home broker establishes an authenticated server-to-server connection to the remote broker and routes the stanza. Federation gives global reach without a central message hub.

## Presence and consent

Roster relationships and presence subscriptions are part of authorization and anti-abuse design:

1. request a subscription;
2. the contact accepts or declines;
3. each side receives the presence allowed by the relationship;
4. unsubscribe and remove roster items when the relationship ends.

Do not send automated messages to arbitrary JIDs merely because federation can route them.

## Stanza types

| Stanza     | Use                                                    |
| ---------- | ------------------------------------------------------ |
| `message`  | Chat, notifications, and application payloads          |
| `presence` | Availability and subscription state                    |
| `iq`       | Request/response or set operations with structured XML |

Use end-to-end encryption for sensitive content that must remain private across brokers.

## Email bridge

When SMTP is enabled, an XMPP account can send and receive email through the same address. Incoming email becomes XMPP message content; outgoing XMPP text/Markdown/HTML is converted to an email after a short accumulation window.

Unlike ordinary email, the bridge enforces a presence/allowlist relationship. A first-time email sender receives a link to request presence; delivery proceeds after the XMPP recipient accepts.

Advanced email content and attachments require a client that understands the Neuron email XMPP extension. Plain text remains interoperable with basic clients.

## SMTP troubleshooting

* verify MX and SPF DNS records;
* inspect per-sender/recipient SMTP logs under the Neuron program-data SMTP folder;
* distinguish `IN` and `OUT` logs;
* resolve the expected incoming sender hosts from SPF and outgoing recipient hosts from MX;
* check roster subscription before investigating content conversion.