Skip to content

Quick Start

This page walks you through the core Titlani workflow: generating an identity, sending a message, and running a server.

1. Generate an Identity

Every Misfin participant needs an identity certificate. Generate one with the CLI:

titlani identity generate alice example.com --blurb "Alice Smith"

This creates two files:

  • alice.pem — Your identity certificate
  • alice.key — Your private key (keep this secret!)

Inspect your identity:

titlani identity info alice.pem

2. Send a Message

Send a message to another Misfin address:

titlani send bob@remote.host "Hello, Bob!" \
    --cert alice.pem --key alice.key \
    --subject "First contact"

The response shows the delivery status:

20 <fingerprint>     # Success — message delivered
51 Mailbox not found  # The recipient doesn't exist

See Status Codes for all possible responses.

3. Generate Config

Use the interactive wizard to generate server and client config files:

titlani init

The wizard asks for your hostname, port, mailbox directory, and which features to enable (GMAP, encryption, sender verification, etc.). It writes server.toml and config.toml to ~/.config/titlani/.

You can also specify a custom output directory:

titlani init --output-dir ./config

4. Start a Server

Start your server — it auto-discovers the config generated by titlani init:

mkdir -p mailboxes/bob
titlani serve

The server auto-generates TLS and identity certificates if not provided. Messages sent to bob@example.com are stored as .gemmail files in mailboxes/bob/.

You can also point to a specific config file:

titlani serve --config server.toml

5. Read Your Mail

List and read received messages using the mail commands:

# List messages (auto-detects mailbox from $USER and directory from config)
titlani mail list

# Read message #1 from the listing
titlani mail read 1

The client config generated by titlani init points to your server config, so mailbox directories are resolved automatically.

6. Programmatic Usage

Use the Python API for more control:

import asyncio
from titlani import MisfinClient

async def main():
    async with MisfinClient(
        client_cert="alice.pem",
        client_key="alice.key",
    ) as client:
        response = await client.send(
            to="bob@remote.host",
            body="Hello from Python!",
            subject="Programmatic message",
        )
        print(f"Status: {response.status}")
        print(f"Meta: {response.meta}")

asyncio.run(main())

Next Steps