Where to Find Examples of Macro Usage: Official Docs, SDKs, and In-Repo Code Samples

Macro provides official documentation at docs.macro.com, Rust and TypeScript SDK examples in crates/ and packages/, and runnable CLI samples in tooling/seed_cli.

Macro is an open-source productivity platform combining email, messaging, documents, and AI agents. Whether you're building integrations with the Macro API or experimenting with the SDKs, you'll find authoritative usage examples across three primary locations: the online product documentation, the repository's README, and concrete code samples embedded throughout the codebase according to the macro-inc/macro source code.

Official Documentation and Quick-Start Links

The entry point for all Macro examples is the repository README, which aggregates links to product-specific documentation and SDK guides.

README.md as the Central Hub

In README.md, Macro maintains curated links to:

• Product docs for each core block: Email, Messages, Channels, Tasks, Docs, Agents, and CRM
• SDK documentation covering MCP (Model Context Protocol) integration and authentication flows
• Quick-start guides for getting a development environment running

This file lives at the repository root and serves as the authoritative starting point for developers asking where to find examples of Macro usage.

Online Product Documentation

The full reference documentation at https://docs.macro.com contains the most extensive collection of usage examples. Each product block includes:

• REST and GraphQL payload examples
• SDK initialization patterns
• Authentication flow diagrams
• Code snippets for creating and linking entities

For instance, the Email documentation demonstrates how to compose messages, attach files, and leverage AI-powered drafting.

In-Repo CLI Examples: tooling/seed_cli

For runnable, real-world code, the tooling/seed_cli directory provides a Rust-based CLI tool that seeds workspaces with test data. This is where you'll find concrete command patterns and JSON payload structures.

seed_cli README and Test Files

Location	What It Contains
tooling/seed_cli/README.md	Step-by-step tutorial for creating users, emails, documents, and channel messages
tooling/seed_cli/src/entity/user/test.rs	CLI examples for user creation
tooling/seed_cli/src/entity/document/test.rs	Document seeding with markdown content
tooling/seed_cli/src/entity/channel/test.rs	Channel and message creation patterns

These test files double as minimal, verified examples of how to structure API requests. The CLI commands map directly to the underlying REST endpoints, making them valuable reference implementations.

Example: Seeding a Document via CLI

# From the repo root

cargo run --bin seed_cli document create \
  --owner "macro|alice@example.com" \
  --title "Project Plan" \
  --content "## Goals\n- ship MVP\n- gather feedback"

Source: tooling/seed_cli/src/entity/document/test.rs

The --owner prefix (macro|) denotes the provider namespace, a pattern you'll see consistently across Macro's entity linking system.

Rust SDK Examples in crates/

Macro's core libraries live in crates/, with macro_db_client being the primary entry point for programmatic usage.

Key Rust Client Files

File	Purpose
crates/macro_db_client/src/lib.rs	Client initialization and configuration
crates/macro_db_client/src/user.rs	UserClient with create_user and related methods
crates/macro_db_client/src/document.rs	Document CRUD operations
crates/macro_db_client/src/message.rs	Message and channel operations

All Rust examples require an MCP token loaded via the macro_env_var crate or environment variables.

Example: Creating a User with the Rust Client

use macro_db_client::user::UserClient;
use macro_env_var::env;

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
    // Load MCP token from environment (set via .env or Doppler)
    let token = env::var("MCP_TOKEN")?;
    let client = UserClient::new(&token);

    // Create a new user
    let user = client
        .create_user(&macro_db_client::user::CreateUser {
            email: "alice@example.com".into(),
            username: Some("alice".into()),
            ..Default::default()
        })
        .await?;

    println!("Created user: {}", user.id);
    Ok(())
}

Source: crates/macro_db_client/src/user.rs

The CreateUser struct uses builder-style defaults, letting you specify only the fields you need while the SDK handles serialization and request signing.

TypeScript SDK Examples in packages/

Frontend and Node.js developers should explore packages/macro-client/, which powers both the web client and Tauri desktop application.

Key TypeScript Files

File	Purpose
packages/macro-client/src/index.ts	Main export and client factory
packages/macro-client/src/channelMessages.ts	Channel message creation and retrieval
packages/macro-client/src/documents.ts	Document API wrappers
packages/macro-client/src/auth.ts	Token management and refresh flows

Example: Creating a Channel Message

import { MacroClient } from '@macro/client';

const client = new MacroClient({
  token: process.env.MCP_TOKEN!,   // MCP token from .env
});

async function postMessage() {
  const channelId = 'channel-123';
  const result = await client.channelMessages.create({
    channelId,
    senderId: 'macro|bob@example.com',
    content: 'Hey team, the latest build is live!',
  });
  console.log('Message ID:', result.id);
}

postMessage().catch(console.error);

Source: packages/macro-client/src/channelMessages.ts

The TypeScript client mirrors the Rust client's structure, using the same entity ID conventions (macro|{email} format) and automatic @link relationship creation.

How the Pieces Fit Together

Understanding where to find examples of Macro usage requires knowing how authentication, API surface, and entity relationships connect:

1. Authentication — All SDKs require an MCP token, generated via the web UI or CLI (claude mcp add …)
2. API surface — Public endpoints live under /api/v1/… with OpenAPI specs generated in-repo
3. Entity creation — seed_cli examples reveal exact JSON structures, identical across Rust and TypeScript clients
4. Bidirectional linking — SDKs automatically create @link relationships (e.g., linking a task to its originating email), demonstrated in the "linked markdown docs" examples

Summary

• docs.macro.com — Most comprehensive examples for each product block (Email, Tasks, Agents, etc.)
• tooling/seed_cli/ — Runnable CLI commands and test files showing real payload structures
• crates/macro_db_client/ — Rust SDK with typed client functions in src/user.rs, src/document.rs, etc.
• packages/macro-client/ — TypeScript SDK used by web and desktop apps
• README.md — Central hub linking all documentation and quick-start resources

Frequently Asked Questions

Where are the most complete Macro examples located?

The online product documentation at https://docs.macro.com contains the most extensive examples, with dedicated pages for Email, Messages, Tasks, Docs, Agents, and CRM. Each page includes REST/GraphQL payloads, SDK snippets, and authentication flow diagrams.

Can I run the Macro examples without setting up a full environment?

Yes. The tooling/seed_cli provides standalone, runnable commands that work against any Macro workspace. Install the CLI with cargo run --bin seed_cli, set your MCP_TOKEN environment variable, and execute commands like seed_cli user create or seed_cli document create immediately.

What is the difference between the Rust and TypeScript Macro SDKs?

Both SDKs wrap the same /api/v1/ endpoints and use identical entity ID conventions. The Rust client (crates/macro_db_client/) offers typed async functions for backend services and CLI tools. The TypeScript client (packages/macro-client/) provides the same capabilities for frontend applications and Node.js scripts, with additional helpers for browser-specific concerns like token refresh.

How do I authenticate with the Macro API in my own code?

All Macro SDKs require an MCP token. Generate one through the web UI under Settings → API Tokens, or via the CLI with claude mcp add. Pass this token to UserClient::new() in Rust or new MacroClient({ token }) in TypeScript. The macro_env_var crate simplifies loading tokens from .env files or secret managers like Doppler.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}