Messaging & Calling Backend
Home Install Email Architecture

Install and setup

Build on top of the SDK in your own product

The project now includes Python packaging metadata so you can install it into an existing FastAPI application directly from GitHub. The current distribution path is GitHub install URLs, not PyPI.

Install from GitHub main 
pip install "git+https://github.com/ukemeikot/messaging-and-calling-backend.git@main#subdirectory=messaging_and_calling_backend"
Copy-Item .env.example .env
alembic upgrade head
uvicorn messaging_sdk.main:app --reload
Install a tagged release 
pip install "git+https://github.com/ukemeikot/messaging-and-calling-backend.git@v1.0.0#subdirectory=messaging_and_calling_backend"
Minimal environment 
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/messaging_db
SECRET_KEY=replace-this-with-a-long-random-secret-key
EMAIL_PROVIDER=console
FRONTEND_URL=http://localhost:3000
ENVIRONMENT=development
DEBUG=false
CORS_ORIGINS=["http://localhost:3000"]

Package state

What is package-ready now

  • `pyproject.toml` defines build metadata and a CLI entry point
  • Email templates are included as package data
  • `messaging-sdk` can be used as a console command after installation
  • The SDK still works from source for local integration and iteration
  • The repository is currently set up for GitHub installs rather than PyPI publication

Before public publication, you should still decide on a final license, repository URLs, and the exact distribution channel you want to use.

Promotion flow

How code moves to production

feature/my-change
  -> pull request to develop
develop
  -> pull request to main
main
  -> changelog update + draft release + website deploy

The repository includes a pull request policy workflow that rejects invalid promotion paths.

CLI

Scaffold a project or inspect config

Scaffold project 
messaging-sdk init --project-name my_app
messaging-sdk init --project-name my_app --template full
Inspect config 
messaging-sdk config
messaging-sdk db --check-config

Generated projects include editable email templates, theme values, and hook files so teams can customize the SDK behavior immediately.

Customization

Override built-in email behavior

The email system is layered. You can use packaged defaults, override template files through `EMAIL_TEMPLATE_DIR`, or register Python hooks through `EmailCustomization`.

Email config 
EMAIL_TEMPLATE_DIR=app/email_templates
EMAIL_THEME_APP_NAME=Messaging Platform
EMAIL_THEME_PRIMARY_COLOR=#1d4ed8
EMAIL_THEME_ACCENT_COLOR=#0f172a
EMAIL_THEME_SUPPORT_EMAIL=support@example.com
EMAIL_THEME_FOOTER_TEXT=Sent by Messaging Platform
Programmatic customization 
from messaging_sdk import MessagingApp
from messaging_sdk.core.config import Settings
from messaging_sdk.emailing import EmailCustomization, EmailTheme


def build_password_reset_link(context):
    token = context.tokens["reset_token"]
    return f"https://accounts.example.com/reset/{token}"


settings = Settings()
email_customization = EmailCustomization(
    template_dir=settings.email_template_dir,
    theme=EmailTheme(
        app_name="Acme Chat",
        primary_color="#2563eb",
        accent_color="#111827",
        support_email="support@acme.test",
        footer_text="Sent by Acme Chat",
    ),
    link_builders={"password_reset": build_password_reset_link},
)

app = MessagingApp(settings=settings, email_customization=email_customization)
Scaffold hook example 
def before_render(context):
    context.data["subject"] = "Please confirm your account"
    return context


def after_render(message, context):
    message.text_body += "\n\nSent from Acme Chat"
    return message

Authentication

Built-in identity flows

  • `/api/v1/auth/register` and `/api/v1/auth/login` for local account auth
  • `/api/v1/auth/me` for the current authenticated user
  • `/api/v1/auth/resend-verification` and `/api/v1/auth/verify-email` for verification
  • `/api/v1/auth/forgot-password` and `/api/v1/auth/reset-password` for password recovery
  • `/api/v1/auth/google/*` for Google OAuth web and mobile flows

Messaging

Contacts, conversations, and realtime chat

  • Direct conversations require accepted contact relationships
  • Group chats support admins, member management, and admin-only add-member settings
  • Messages support send, edit, delete, typing events, and read receipts
  • Conversation membership is enforced before reads and writes are allowed

Calling

Voice and video call lifecycle

  • Initiate, answer, decline, end, and invite participants to calls
  • Separate participant and invitation records for group call growth
  • WebSocket signaling membership is validated against stored call participation

Architecture

Implementation schema

MessagingApp
|
+-- api/v1/      routers and websocket endpoints
+-- services/    business rules
+-- models/      SQLAlchemy entities
+-- core/        config, security, dependencies
+-- emailing.py  template composition and theme runtime
+-- providers/   delivery transports
+-- cli/         project scaffolding and config helpers
Client
  -> FastAPI routers
    -> dependencies and auth checks
      -> service layer
        -> database / websocket manager / email service
          -> email composer
            -> templates + theme
          -> provider delivery