Skip to main content
Glama
Sign In
ClawAIMail

ClawAIMail

by joansongjr
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Hybrid

getting_started

Learn to use AI email inboxes: create, send, receive, search messages, and manage threads with step-by-step guidance.

Instructions

Interactive onboarding guide for ClawAIMail. Shows you everything you can do with your AI email, step by step.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "getting_started"
  }
}

Input Schema

NameRequiredDescriptionDefault
levelNoGuide level: "beginner" (default) for basics, "advanced" for power features

Implementation Reference

  • mcp/index.js:334-456 (registration)
    The tool 'getting_started' is registered via server.tool() with name 'getting_started' and a description about interactive onboarding.
    server.tool(
  'getting_started',
  'Interactive onboarding guide for ClawAIMail. Shows you everything you can do with your AI email, step by step.',
  {
    level: z.enum(['beginner', 'advanced']).optional().describe('Guide level: "beginner" (default) for basics, "advanced" for power features')
  },
  async ({ level = 'beginner' }) => {
    const inbox = await getDefaultInbox();
    const hasInbox = inbox && !inbox.error;
    const email = hasInbox ? (inbox.email || inbox.address) : null;

    if (level === 'advanced') {
      return { content: [{ type: 'text', text: JSON.stringify({
        title: '🚀 ClawAIMail Advanced Features',
        features: [
          {
            name: 'Multiple Inboxes',
            description: 'Create separate inboxes for different purposes (support, notifications, personal)',
            tool: 'create_inbox',
            example: { username: 'support' },
            result: 'Creates support@clawaimail.com'
          },
          {
            name: 'Custom Domains',
            description: 'Want bot@yourdomain.com instead of bot@clawaimail.com? Paid plan users can add their own domain. Steps: 1) POST /v1/domains { domain: "yourdomain.com" } 2) Add the DNS TXT record provided 3) POST /v1/domains/:id/verify to confirm',
            api_endpoint: 'POST /v1/domains',
            requires: 'Pro plan ($29/mo) or above',
            steps: [
              'Call POST /v1/domains with your domain name',
              'Add the TXT record to your DNS: _clawaimail.yourdomain.com → verification token',
              'Call POST /v1/domains/:id/verify to complete',
              'Now create inboxes with: create_inbox(username: "bot", domain: "yourdomain.com")'
            ]
          },
          {
            name: 'Email Search',
            description: 'Search emails by keyword across subject, body, and sender',
            tool: 'search_emails',
            example: { query: 'invoice' }
          },
          {
            name: 'Webhooks',
            description: 'Get HTTP notifications when new emails arrive. Set up via the REST API: POST /v1/webhooks with { url, events: ["email_received"] }',
            api_endpoint: 'POST /v1/webhooks'
          },
          {
            name: 'WebSocket Real-time',
            description: 'Connect to ws://api.clawaimail.com/v1/ws?key=YOUR_API_KEY for real-time email notifications',
            protocol: 'WebSocket'
          },
          {
            name: 'Account & Limits',
            description: 'Check your plan, usage, and limits',
            tool: 'account_info'
          }
        ],
        plans: {
          free: '3 inboxes, 3K emails/month, 100 sends/day',
          starter: '$5/mo — 10 inboxes, 5K emails/month, unlimited sends',
          pro: '$29/mo — 50 inboxes, 50K emails/month, custom domains',
          business: '$99/mo — 200 inboxes, 200K emails/month, everything unlimited'
        },
        tip: 'Want a custom domain like @yourstartup.com? Upgrade to Pro and follow the Custom Domains steps above.'
      }, null, 2) }] };
    }

    // Beginner guide — step 1 depends on whether user already has an inbox
    const step1 = hasInbox
      ? {
          step: 1,
          title: '✉️ Your Email is Ready',
          description: `Your email address is ${email}. Anyone can send emails to this address and you'll receive them.`,
          done: true,
          tip: 'Want a different name? Call my_email(preferred_name: "yourname") to create a new one.'
        }
      : {
          step: 1,
          title: '✉️ Choose Your Email Name',
          description: 'First, pick a name for your email address! Call my_email(preferred_name: "yourname") to create yourname@clawaimail.com. Pick something memorable — this is your agent\'s identity.',
          tool: 'my_email',
          example: { preferred_name: 'jarvis' },
          result: 'Creates jarvis@clawaimail.com (or jarvis-xxxx@clawaimail.com if taken)',
          done: false
        };

    return { content: [{ type: 'text', text: JSON.stringify({
      title: '📬 Welcome to ClawAIMail!',
      subtitle: 'Your AI agent now has its own email address. Follow these steps to get started:',
      your_email: email || '(not created yet — complete step 1!)',
      steps: [
        step1,
        {
          step: 2,
          title: '📤 Send Your First Email',
          description: 'Try sending an email to yourself or someone you know.',
          tool: 'send_email',
          example: {
            to: 'someone@gmail.com',
            subject: 'Hello from my AI agent!',
            text: 'This email was sent by my AI agent using ClawAIMail.'
          }
        },
        {
          step: 3,
          title: '📥 Check Your Inbox',
          description: 'See all emails you\'ve received. Ask someone to send a test email to your address!',
          tool: 'list_messages',
          tip: 'Use unread: true to see only new messages'
        },
        {
          step: 4,
          title: '🔍 Search Emails',
          description: 'Find specific emails by keyword.',
          tool: 'search_emails',
          example: { query: 'hello' }
        }
      ],
      next: 'Want more? Call getting_started(level: "advanced") to learn about custom domains (use your own @yourdomain.com!), webhooks, multiple inboxes, and more.',
      custom_domain_hint: 'Pro tip: Paid users can use their own domain — e.g. bot@yourstartup.com. Call getting_started(level: "advanced") for details.',
      help: 'https://clawaimail.com/docs'
    }, null, 2) }] };
  }
);
  • mcp/index.js:340-456 (handler)
    The async handler function that executes the tool logic. It takes an optional 'level' parameter ('beginner' or 'advanced'). For 'advanced', it returns a JSON guide of advanced features (multiple inboxes, custom domains, search, webhooks, websockets, account info) and pricing plans. For 'beginner', it returns a step-by-step onboarding guide (steps 1-4) that adapts based on whether the user already has an inbox.
      async ({ level = 'beginner' }) => {
    const inbox = await getDefaultInbox();
    const hasInbox = inbox && !inbox.error;
    const email = hasInbox ? (inbox.email || inbox.address) : null;

    if (level === 'advanced') {
      return { content: [{ type: 'text', text: JSON.stringify({
        title: '🚀 ClawAIMail Advanced Features',
        features: [
          {
            name: 'Multiple Inboxes',
            description: 'Create separate inboxes for different purposes (support, notifications, personal)',
            tool: 'create_inbox',
            example: { username: 'support' },
            result: 'Creates support@clawaimail.com'
          },
          {
            name: 'Custom Domains',
            description: 'Want bot@yourdomain.com instead of bot@clawaimail.com? Paid plan users can add their own domain. Steps: 1) POST /v1/domains { domain: "yourdomain.com" } 2) Add the DNS TXT record provided 3) POST /v1/domains/:id/verify to confirm',
            api_endpoint: 'POST /v1/domains',
            requires: 'Pro plan ($29/mo) or above',
            steps: [
              'Call POST /v1/domains with your domain name',
              'Add the TXT record to your DNS: _clawaimail.yourdomain.com → verification token',
              'Call POST /v1/domains/:id/verify to complete',
              'Now create inboxes with: create_inbox(username: "bot", domain: "yourdomain.com")'
            ]
          },
          {
            name: 'Email Search',
            description: 'Search emails by keyword across subject, body, and sender',
            tool: 'search_emails',
            example: { query: 'invoice' }
          },
          {
            name: 'Webhooks',
            description: 'Get HTTP notifications when new emails arrive. Set up via the REST API: POST /v1/webhooks with { url, events: ["email_received"] }',
            api_endpoint: 'POST /v1/webhooks'
          },
          {
            name: 'WebSocket Real-time',
            description: 'Connect to ws://api.clawaimail.com/v1/ws?key=YOUR_API_KEY for real-time email notifications',
            protocol: 'WebSocket'
          },
          {
            name: 'Account & Limits',
            description: 'Check your plan, usage, and limits',
            tool: 'account_info'
          }
        ],
        plans: {
          free: '3 inboxes, 3K emails/month, 100 sends/day',
          starter: '$5/mo — 10 inboxes, 5K emails/month, unlimited sends',
          pro: '$29/mo — 50 inboxes, 50K emails/month, custom domains',
          business: '$99/mo — 200 inboxes, 200K emails/month, everything unlimited'
        },
        tip: 'Want a custom domain like @yourstartup.com? Upgrade to Pro and follow the Custom Domains steps above.'
      }, null, 2) }] };
    }

    // Beginner guide — step 1 depends on whether user already has an inbox
    const step1 = hasInbox
      ? {
          step: 1,
          title: '✉️ Your Email is Ready',
          description: `Your email address is ${email}. Anyone can send emails to this address and you'll receive them.`,
          done: true,
          tip: 'Want a different name? Call my_email(preferred_name: "yourname") to create a new one.'
        }
      : {
          step: 1,
          title: '✉️ Choose Your Email Name',
          description: 'First, pick a name for your email address! Call my_email(preferred_name: "yourname") to create yourname@clawaimail.com. Pick something memorable — this is your agent\'s identity.',
          tool: 'my_email',
          example: { preferred_name: 'jarvis' },
          result: 'Creates jarvis@clawaimail.com (or jarvis-xxxx@clawaimail.com if taken)',
          done: false
        };

    return { content: [{ type: 'text', text: JSON.stringify({
      title: '📬 Welcome to ClawAIMail!',
      subtitle: 'Your AI agent now has its own email address. Follow these steps to get started:',
      your_email: email || '(not created yet — complete step 1!)',
      steps: [
        step1,
        {
          step: 2,
          title: '📤 Send Your First Email',
          description: 'Try sending an email to yourself or someone you know.',
          tool: 'send_email',
          example: {
            to: 'someone@gmail.com',
            subject: 'Hello from my AI agent!',
            text: 'This email was sent by my AI agent using ClawAIMail.'
          }
        },
        {
          step: 3,
          title: '📥 Check Your Inbox',
          description: 'See all emails you\'ve received. Ask someone to send a test email to your address!',
          tool: 'list_messages',
          tip: 'Use unread: true to see only new messages'
        },
        {
          step: 4,
          title: '🔍 Search Emails',
          description: 'Find specific emails by keyword.',
          tool: 'search_emails',
          example: { query: 'hello' }
        }
      ],
      next: 'Want more? Call getting_started(level: "advanced") to learn about custom domains (use your own @yourdomain.com!), webhooks, multiple inboxes, and more.',
      custom_domain_hint: 'Pro tip: Paid users can use their own domain — e.g. bot@yourstartup.com. Call getting_started(level: "advanced") for details.',
      help: 'https://clawaimail.com/docs'
    }, null, 2) }] };
  }
);
  • mcp/index.js:337-338 (schema)
    Input schema for the tool: an optional 'level' parameter using z.enum(['beginner', 'advanced']) validated via Zod.
    {
  level: z.enum(['beginner', 'advanced']).optional().describe('Guide level: "beginner" (default) for basics, "advanced" for power features')

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; the description doesn't disclose whether the tool is read-only, idempotent, or has side effects. The behavioral burden is on the description, which only states it's interactive without safety details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences that are front-loaded and convey core purpose without waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple onboarding tool with one optional parameter and no output schema, the description explains its function adequately. It lacks mention of output format or side effects, but is mostly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single parameter 'level', which includes an enum and description. The tool description adds no extra meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it is an 'Interactive onboarding guide' for ClawAIMail, using specific verbs ('shows', 'step by step'). It distinguishes from sibling tools (all focused on actual email operations) by being a learning resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied usage for new users ('onboarding', 'step by step') but no explicit when-to-use or when-not-to-use, nor alternatives among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools