# Meshes

> Meshes is a universal event routing and integration platform for SaaS applications. It replaces hand-rolled integration code with a single API that routes product events (signups, payments, user actions) to tools like HubSpot, Salesforce, Intercom, Mailchimp, Webhooks, and more — with automatic retries, fan-out, and multi-tenant workspace isolation.

Canonical: https://meshes.io/llms-full.txt
Short index: https://meshes.io/llms.txt
Last updated: 2026-02-24

Meshes is designed for solo developers and engineering teams at SaaS companies of any size who currently maintain custom integration code. Instead of building and maintaining webhook delivery, retry logic, OAuth token management, and field mappings for each destination, teams emit events once and Meshes handles routing and delivery.

The platform is a full integration layer — not just webhook delivery, but complete connection management with built-in OAuth token handling, field mappings, and multi-tenant workspace isolation.

---

## Core Concepts

Meshes has four primitives:

### Workspace
A tenant-scoped container. Each workspace has its own connections, rules, event history, and a publishable key. Recommended pattern for multi-tenant SaaS: one workspace per customer tenant. Workspaces provide complete isolation between tenants.

### Connection
A configured destination within a workspace. Examples: a HubSpot OAuth connection, a Salesforce API key, a webhook URL. Connections store destination auth/config metadata and expose available actions. Each connection specifies an integration type and stores the authentication details needed to communicate with the destination.

### Rule
A routing rule that binds an event type to a connection action. Rules typically include `workspace`, `connection`, `event`, optional `resource` and `resource_id` filters, and a `metadata` object with at minimum an `action` field that determines what the destination does (e.g., `add_to_list`, `create_or_update_contact`, `send_webhook`).

### Event
A JSON payload emitted by your application (e.g., `user.signup`, `payment.failed`, `lead.created`). Events are routed to matching rules within a workspace. Each event tracks delivery status across all matched rules with `rule_events`, providing full observability into what happened with each delivery attempt.

---

## API Architecture

### Base URLs

- OpenAPI server / base URL: `https://api.meshes.io/api/v1`
- Browser-friendly event ingestion alias: `https://events.meshes.io/api/v1` (CORS-enabled, for `POST /events` and `POST /events/bulk`)

### Authentication

Meshes supports two authentication methods:

#### Bearer Token (Management API)
For server-side operations — managing workspaces, connections, rules, and reading events. Uses short-lived HS256 machine JWTs (maximum 60 seconds).

JWT conventions:
- `kid` header uses access key
- `iss` is `urn:meshes:m2m:<ACCESS_KEY>`
- `aud` is `meshes-api`
- `org` is organization UUID

The `@mesheshq/api` SDK handles token generation automatically.

```typescript
const headers = {
  'Authorization': 'Bearer YOUR_JWT_TOKEN',
  'Content-Type': 'application/json',
};
```

Never expose machine access keys or secret keys in frontend code.

#### Publishable Key (Event Ingestion)
For emitting events — safe to expose in frontend code and public repositories. Sent via the `X-Meshes-Publishable-Key` header. Only grants access to `POST /events` and `POST /events/bulk`. Each workspace has its own publishable key, returned when you `GET /workspaces/{workspace_id}`.

```typescript
const headers = {
  'X-Meshes-Publishable-Key': 'pk_live_...',
  'Content-Type': 'application/json',
};
```

For browser-based event emission, use `https://events.meshes.io` (CORS-enabled) instead of `https://api.meshes.io`.

### Pagination

List responses use cursor-based pagination with a standard envelope:
- `count` — number of records in this page
- `limit` — page size
- `next_cursor` — cursor for the next page (null if no more)
- `records` — array of results

Some list endpoints accept `cursor` and `limit` query params.

---

## Event Ingestion

This is the primary integration point. Your app emits events; Meshes handles routing and delivery.

### Single Event — POST /events

Accepts either Bearer token or Publishable Key authentication.

```json
{
  "event": "user.signup",
  "payload": {
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+15551234567"
  },
  "resource": "user",
  "resource_id": "usr_abc123",
  "workspace": "ws_xyz"
}
```

**Recognized payload fields:** `email` (required for most integrations), `id`, `name`, `first_name`, `last_name`, `phone`, `ip_address`, `resource_url`. Additional properties are passed through via `additionalProperties`.

### Bulk Events — POST /events/bulk

Request body is a JSON array of up to 100 events:

```json
[
  {
    "event": "user.signup",
    "payload": { "email": "jane@example.com" }
  },
  {
    "event": "user.signup",
    "payload": { "email": "john@example.com" }
  }
]
```

Returns `201` on full success or `207` on partial success with per-event results.

---

## Supported Integrations

Meshes supports 10 integration types. Each has specific authentication requirements, available actions, and field mappings.

| Integration    | Auth Type        | Key Actions                                              |
| -------------- | ---------------- | -------------------------------------------------------- |
| ActiveCampaign | API key          | add_to_list, remove_from_list, add_tag, remove_tag       |
| AWeber         | OAuth            | add_to_list, remove_from_list                            |
| HubSpot        | OAuth            | add_to_list, remove_from_list, update_property           |
| Intercom       | OAuth            | add_tag, remove_tag                                      |
| Mailchimp      | OAuth            | add_to_list, remove_from_list                            |
| MailerLite     | API key          | add_to_group, remove_from_group                          |
| Resend         | API key          | add_to_segment, remove_from_segment, send_email_template |
| Salesforce     | OAuth            | add_to_campaign, remove_from_campaign, update_property   |
| Webhook        | Config-only (URL)| send_webhook                                             |
| Zoom           | OAuth            | add_meeting_registrant, add_webinar_registrant           |

### Integration & Rules Workflow

Typical API flow:

1. `GET /integrations` — discover integration metadata and action schemas
2. `POST /connections` — create a connection (for OAuth integrations, typically initiated via dashboard OAuth flow)
3. `GET /connections/{connection_id}/actions` — fetch live action data (lists, tags, campaigns, properties, etc.)
4. Optionally inspect/update field mappings:
   - `GET /connections/{connection_id}/fields` — get field catalog
   - `GET /connections/{connection_id}/mappings/default` — get default mappings
   - `PUT /connections/{connection_id}/mappings/default` — update mappings
5. `POST /rules` — bind event → connection → action
6. `POST /events` (or `/events/bulk`) — test delivery

### Field Mappings

Field mappings control how event payload fields map to destination fields. Each mapping has:
- `dest`: The destination field name
- `source`: Either `path` (extract from event payload, e.g., `"email"`, `"user.email"`) or `literal` (hardcoded value)
- `transforms`: Optional array of transforms — `trim`, `lower`, `upper`, `to_string`, `to_number`, `to_boolean`, `to_date`, `to_datetime`, `substring`, `default`
- `on_error`: What to do on mapping failure — `skip_field`, `warn_action`, or `fail_action`

Default mappings are created automatically when a connection is set up. You can customize them per connection. Maximum 250 field mappings per connection, 10 transforms per field.

---

## Endpoint Map

### Workspaces
- `GET /workspaces` — List all workspaces
- `POST /workspaces` — Create a workspace
- `GET /workspaces/{workspace_id}` — Get workspace (includes publishable key)
- `PUT /workspaces/{workspace_id}` — Update a workspace

Workspace-scoped listings:
- `GET /workspaces/{workspace_id}/connections` — List connections in workspace
- `GET /workspaces/{workspace_id}/rules` — List rules in workspace
- `GET /workspaces/{workspace_id}/events` — List events in workspace (filterable by event, resource, resource_id, status)

### Connections
- `GET /connections` — List all connections (org-wide)
- `POST /connections` — Create a connection
- `GET /connections/{connection_id}` — Get connection
- `PUT /connections/{connection_id}` — Update connection
- `DELETE /connections/{connection_id}` — Delete connection (supports `force_delete`)
- `GET /connections/{connection_id}/actions` — Get available actions
- `GET /connections/{connection_id}/fields` — Get field catalog (supports `refresh` param)
- `GET /connections/{connection_id}/mappings/default` — Get default field mappings
- `PUT /connections/{connection_id}/mappings/default` — Update default field mappings

### Rules
- `GET /rules` — List all rules (filterable by event, resource, resource_id)
- `POST /rules` — Create a rule
- `GET /rules/{rule_id}` — Get rule
- `DELETE /rules/{rule_id}` — Delete rule

### Events
- `POST /events` — Send a single event
- `POST /events/bulk` — Send up to 100 events
- `GET /events` — List events (supports cursor/limit pagination)
- `GET /events/{event_id}` — Get event with delivery details
- `GET /events/{event_id}/payload` — Get event including full payload
- `POST /events/{event_id}/rules/{rule_id}/retry` — Retry a failed delivery

### Integrations
- `GET /integrations` — List all available integration types with metadata, auth requirements, and action schemas

---

## SDKs

### Node.js / TypeScript Management SDK
```bash
npm install @mesheshq/api
```

```typescript
import MeshesApiClient from '@mesheshq/api';

const client = new MeshesApiClient(
  process.env.MESHES_ORGANIZATION_ID!,
  process.env.MESHES_ACCESS_KEY!,
  process.env.MESHES_SECRET_KEY!,
);

const workspaces = await client.get('/workspaces');
```

### Node.js / TypeScript Events SDK
```bash
npm install @mesheshq/events
```

```typescript
import MeshesEventsClient from '@mesheshq/events';

const events = new MeshesEventsClient(process.env.WORKSPACE_PUBLISHABLE_KEY!);

await events.emit({
  event: 'user.signup',
  payload: {
    email: 'jane@example.com',
    first_name: 'Jane',
  },
});
```

### Go SDK
```bash
go get github.com/mesheshq/go-meshes
```

---

## Multi-Tenant Pattern

Recommended operational pattern for multi-tenant SaaS apps:

1. Create one workspace per customer/tenant
2. Persist the workspace ID alongside your tenant record
3. Let each tenant configure their own connections (e.g., their HubSpot account)
4. Emit events with the tenant's workspace ID — Meshes routes to their specific connections
5. Use the workspace's publishable key for client-side event emission if needed
6. Keep publishable keys and machine credentials scoped per environment

This gives each tenant isolated credentials, separate event logs, and independent connection configurations.

---

## Common Anti-Patterns

- **Don't build retry logic** — Meshes handles retries with exponential backoff automatically
- **Don't fan out manually** — Send one event; Meshes delivers to all matching rules
- **Don't expose machine keys client-side** — Use publishable keys for frontend/client event emission
- **Don't hardcode workspace IDs** — Store them dynamically per tenant
- **Don't assume ordered processing** for bulk ingestion

---

## AI-Native Developer Tools

Meshes provides AI-assisted development tools:

- **Cursor Rules**: A `.cursor/rules/meshes.mdc` file that teaches AI coding agents (Cursor, Windsurf, etc.) the full Meshes API — endpoints, auth patterns, payload schemas, field mappings, and anti-patterns
- **MCP Server**: A Model Context Protocol server that gives AI agents direct read access to Meshes resources (workspaces, connections, rules, events, connectors)

Resources:
- AI tools overview: https://meshes.io/docs/ai/ai
- AI docs index: https://meshes.io/docs/ai/llms
- Cursor rules: https://meshes.io/docs/ai/cursor-rules
- MCP server: https://meshes.io/docs/ai/mcp-server
- Repository: https://github.com/mesheshq/meshes-ai-tools

---

## Pricing

| Plan       | Price      | Events/Month | Best For                              |
| ---------- | ---------- | ------------ | ------------------------------------- |
| Dev        | Free       | 100          | Testing and evaluation                |
| Builder    | $49/mo     | 2,500        | Early-stage SaaS, first integrations  |
| Pro        | $199/mo    | 25,000       | Growing SaaS with multiple tenants    |
| Scale      | $499/mo    | 100,000      | High-volume production workloads      |
| Enterprise | Custom     | Custom       | Custom limits, dedicated support, SLAs|

Pricing page: https://meshes.io/pricing

---

## Links

- Website: https://meshes.io
- Documentation: https://meshes.io/docs
- API Reference (OpenAPI): https://docs.meshes.dev
- Getting Started: https://meshes.io/docs/getting-started/getting-started
- Integrations & Rules: https://meshes.io/docs/api/integrations-and-rules
- Send Events: https://meshes.io/docs/events/send-events
- Bulk Events: https://meshes.io/docs/events/bulk-events
- Status Page: https://meshes.statuspage.io/
- Blog: https://meshes.io/blog
- Compare: Meshes vs. DIY: https://meshes.io/compare
- GitHub: https://github.com/mesheshq
- AI Tools: https://github.com/mesheshq/meshes-ai-tools
- npm (Management SDK): https://www.npmjs.com/package/@mesheshq/api
- npm (Events SDK): https://www.npmjs.com/package/@mesheshq/events
- Go SDK: https://github.com/mesheshq/go-meshes