mailnix Docs
    mailnix / Sending domains and sender identities

    Core concepts

    Sending domains and sender identities

    Four pieces make up a working sending path: a destination (the provider that relays your mail), an SMTP credential or API key (how your app authenticates), a routing rule (which destination a given message uses), and a sending domain (proof that you own the domain in your From address). This guide covers the last piece and the per-mailbox identities you create under it.

    Why verify a domain

    Recipients' mailservers judge your mail by the From domain. If you send as hello@acme.com without owning acme.com's DNS, receivers will reject or junk the message no matter which provider relays it. Verifying the domain in mailnix does two things:

    • it unlocks From addresses under that domain for reply-to and sender-identity features, and
    • it gives the dashboard one place that shows whether the domain's DNS is in a sendable state.

    The claim flow

    1. Add the domain, in the dashboard under Settings, or via the MCP tool sending_domain_add(domain).
    2. mailnix answers with a challenge TXT record: publish a TXT record at _mailnix-challenge.<your domain> with the returned mailnix-verify=... token as its value.
    3. The status flips from pending to verified once the DNS probe observes the record. Probes run automatically in the background; you can also trigger one immediately with Recheck in the dashboard or sending_domain_recheck(id).

    The token proves control of the domain's DNS, nothing more. It does not replace SPF / DKIM / DMARC, those records authorize the provider that relays your mail and are covered in the destinations guide.

    Sender identities

    Once a domain is verified you can register sender identities under it, one row per mailbox you send as:

    • alice@acme.com for transactional mail
    • marketing@acme.com for the newsletter

    Each identity can carry an optional default destination. That gives you per-mailbox provider routing without writing routing rules: alice@ relays through Postmark while marketing@ goes out through SES.

    Resolution order at send time:

    1. A routing rule whose from_address / from_domain matches wins.
    2. Otherwise the identity's own default destination applies.
    3. Otherwise the SMTP credential's default destination is used.

    MCP tools: sender_identity_add, sender_identity_list, sender_identity_list_for_domain, sender_identity_set_destination, sender_identity_set_display_name, sender_identity_delete.

    Relationship to routing rules

    A routing rule with a from_domain match sends every message whose From is under that domain to a chosen destination. Sender identities refine this per mailbox. You need neither to send, a credential with a default destination is enough, but you need a verified sending domain for receivers to accept what you send, and identities are the cleanest way to split traffic across providers by mailbox.

    Verification vs deliverability

    sending_domain_add proves ownership to mailnix. Deliverability additionally needs the DNS trio on your domain, SPF, DKIM, DMARC, authorizing the destination provider. Check their live state any time with the MCP tool email_domain_verify_status(domain) or the domain-verification panel on the destination's page.