Quickstart

Hello Tidy in 15 minutes

By the end of this walkthrough you'll have made your first authenticated API call against your own Tidy workspace, listed your emails, sent an email, and subscribed to a live webhook.

1. Get access

Tidy is in an invite-only beta. If you don't have a workspace yet, request an invite.

2. Create a personal access token

In Tidy, open Settings → Security → Personal Access Tokens and create a token. It's shown exactly once. Paste it into a shell variable:

export TIDY_PAT="tidy_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

3. Make your first API call

Fetch your account profile. This is the canonical way to verify your PAT is working.

curl https://qa.tidy.engineering/api/v1/accounts/me \
  -H "Authorization: Bearer $TIDY_PAT"

Expected response:

{
  "id": "…",
  "email": "[email protected]",
  "home_timezone": "America/New_York",
  "active_timezone": "America/New_York",
  …
}

4. List your emails

The five most recent emails in your workspace.

curl "https://qa.tidy.engineering/api/v1/emails?limit=5" \
  -H "Authorization: Bearer $TIDY_PAT"

5. Send yourself an email

This really sends, from the account connected to your workspace, so put your own address in to.

curl -X POST https://qa.tidy.engineering/api/v1/emails/send \
  -H "Authorization: Bearer $TIDY_PAT" \
  -H "Content-Type: application/json" \
  -d '{"to":"[email protected]","subject":"Hello Tidy","body":"First send."}'

6. Subscribe to webhooks

Every change in your workspace can trigger a signed outbound webhook. For a quick test, use webhook.site to get a receiving URL, then:

curl -X POST https://qa.tidy.engineering/api/v1/event_subscriptions \
  -H "Authorization: Bearer $TIDY_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://webhook.site/YOUR-UNIQUE-ID",
    "event_types": ["email.created"]
  }'

The delivery will carry a Tidy-Signature header. Verify it with the samples on the Webhooks page.

7. Connect via MCP

Drop this into your Claude Desktop or Cursor config to expose Tidy as a live MCP server to the agent. See the MCP guide for the full walkthrough.

{
  "mcpServers": {
    "tidy": {
      "url": "https://qa.tidy.engineering/api/v1/mcp",
      "oauth": {
        "authorize_url": "https://qa.tidy.engineering/api/v1/oauth/authorize",
        "token_url": "https://qa.tidy.engineering/api/v1/oauth/token"
      }
    }
  }
}

You're in.

Next stops: the live OpenAPI explorer, the event catalog, and the examples.