# 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, Slack, 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-09-06

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, multi-tenant workspace isolation, and an embedded workspace product for customer-facing SaaS applications.

---

## 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.

Event and rule status use the same vocabulary: `pending`, `processing`, `retrying`, `completed`, `failed`, `canceled`. Every delivery attempt is recorded with timing and a structured `outcome_code` (such as `delivered`, `rejected_server_error`, `rate_limited`, `auth_failed`, `timeout`, `network_error`, `mapping_error`). Authorized users can cancel a single rule or an entire event, and can force the next attempt immediately for a rule in a retry loop.

---

## 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`.

#### Session Token (Embedded Workspace Runtime)

For the embedded workspace product, your backend can mint a workspace-scoped session token from the private management API. This token is not a replacement for machine authentication in your backend. It is a short-lived runtime credential used by the iframe after bootstrap.

Embedded sessions also return a `launch_url`:

- `launch_url` bootstraps the initial iframe document request
- the session token is sent later with `postMessage`
- a hard iframe reload should use a fresh `launch_url`

### 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.

---

## Embedded Workspace and Session Layer

Meshes also supports embedding selected workspace pages inside your own application with an iframe-based runtime.

### Supported Embedded Pages

The current supported embed surface is:

- dashboard
- connections
- rules
- events
- event detail
- connection mappings

`members` and `settings` remain web-only.

### Two-Step Bootstrap Model

The embed runtime uses two related credentials:

1. **Launch URL / launch token**
   - short-lived
   - used only for the initial iframe request

2. **Session token**
   - workspace-scoped runtime credential
   - sent to the iframe after it loads
   - used for the authenticated workspace experience

Typical host flow:

1. backend calls `POST /api/v1/sessions`
2. backend returns `launch_url` and `access_token` to the frontend
3. frontend renders `<iframe src="{launch_url}">`
4. iframe posts `meshes:ready`
5. host posts `meshes:auth` with the session token
6. iframe loads workspace data

### Session API

The current embedded workspace session endpoints are:

- `POST /api/v1/sessions`
- `POST /api/v1/sessions/{session_id}/refresh`
- `GET /api/v1/sessions`
- `DELETE /api/v1/sessions/{session_id}`

Session minting accepts:

- `workspace_id`
- `role`
- `session_type`
- `external_user_id`
- `ttl_seconds`
- `launch_ttl_seconds`
- `launch_page`
- `resource`
- `resource_id`
- `allowed_origins`
- `scopes`

Session minting returns:

- `session_id`
- `access_token`
- `expires_at`
- `launch_url`

Use `launch_url` directly in the iframe.

### Roles and Scopes

Current session roles are:

- `member`
- `admin`
- `owner`

Important behavior notes:

- use the lowest role that still supports the embedded workflow you need
- sensitive reads can require explicit scopes in addition to role
- current sensitive payload scope: `events.payload:read`

### Origin Model

`allowed_origins` is optional during session minting.

Current behavior:

- when `allowed_origins` is provided, the launch bootstrap and runtime handshake enforce that narrower origin list
- set `allowed_origins` explicitly when you want to restrict where a session may be embedded

### postMessage Contract

Current iframe message types:

Parent -> iframe:

- `meshes:auth`

Iframe -> parent:

- `meshes:ready`
- `meshes:token-refresh`
- `meshes:token-expired`
- `meshes:navigate`
- `meshes:resize`

Host applications should:

- derive `embedOrigin` from `launch_url`
- ignore `message` events from any other origin
- send `meshes:auth` back to that same origin

### Refresh Lifecycle

Embedded sessions refresh in place:

- one logical `session_id` remains stable
- the iframe requests refresh both on schedule and after auth-related `401`s
- refresh returns a new `access_token` for the mounted iframe

### OAuth Connection Setup in Embed

OAuth-backed connection setup currently routes through the Meshes web app for the authorization and callback flow. The embed UI can initiate the flow, but the actual OAuth bootstrap is web-routed rather than fully contained inside the embed app.

### Iframe Sizing

The embed runtime can report its content height with `meshes:resize`. The host application owns iframe height policy:

- apply the reported height
- optionally clamp to a minimum height
- optionally debounce visible resizing in the host or SDK

Primary docs:

- https://meshes.io/docs/embed/embed
- https://meshes.io/docs/embed/quickstart
- https://meshes.io/docs/embed/session-api
- https://meshes.io/docs/embed/launch-bootstrap
- https://meshes.io/docs/embed/postmessage-contract
- https://meshes.io/docs/embed/workspace-pages
- https://meshes.io/docs/embed/session-refresh
- https://meshes.io/docs/embed/oauth-connections
- https://meshes.io/docs/embed/iframe-sizing
- https://meshes.io/docs/embed/security
- https://meshes.io/docs/embed/troubleshooting

---

## 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 15 integration types. Each has specific authentication requirements, available actions, and field mappings.

Public integrations directory: https://meshes.io/integrations

| Integration    | Type            | Auth Type         | Key Actions                                              | Docs URL                          |
| -------------- | --------------- | ----------------- | -------------------------------------------------------- | --------------------------------- |
| ActiveCampaign | Email Marketing | API key           | add_to_list, remove_from_list, add_tag, remove_tag       | /docs/integrations/activecampaign |
| AWeber         | Email Marketing | OAuth             | add_to_list, remove_from_list                            | /docs/integrations/aweber         |
| Customer.io    | Email Marketing | API key           | track_event                                              | /docs/integrations/customer_io    |
| Discord        | Messaging       | OAuth             | send_message                                             | /docs/integrations/discord        |
| HubSpot        | CRM             | OAuth             | add_to_list, remove_from_list, update_property           | /docs/integrations/hubspot        |
| Intercom       | Messaging       | OAuth             | add_tag, remove_tag                                      | /docs/integrations/intercom       |
| Mailchimp      | Email Marketing | OAuth             | add_to_list, remove_from_list                            | /docs/integrations/mailchimp      |
| MailerLite     | Email Marketing | API key           | add_to_group, remove_from_group                          | /docs/integrations/mailerlite     |
| Pipedrive      | CRM             | OAuth             | sync_person, update_person_field, add_label_to_person, remove_label_from_person | /docs/integrations/pipedrive      |
| Resend         | Email           | API key           | add_to_segment, remove_from_segment, send_email_template | /docs/integrations/resend         |
| Salesforce     | CRM             | OAuth             | add_to_campaign, remove_from_campaign, update_property   | /docs/integrations/salesforce     |
| SendGrid       | Email           | API key           | send_email_template, send_email                          | /docs/integrations/sendgrid       |
| Slack          | Messaging       | OAuth             | send_message                                             | /docs/integrations/slack          |
| Webhook        | Developer Tools | Config-only (URL) | send_webhook                                             | /docs/integrations/webhooks       |
| Zoom           | Video           | OAuth             | add_meeting_registrant, add_webinar_registrant           | /docs/integrations/zoom           |

### 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

### Sessions (Embedded Workspace)

- `POST /sessions` — Mint a workspace-scoped embed session and launch URL
- `POST /sessions/{session_id}/refresh` — Refresh the current logical session with a new JWT
- `GET /sessions` — List sessions for a workspace (cursor-paginated)
- `DELETE /sessions/{session_id}` — Revoke a logical session

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` — Force the next attempt for a rule in a retry loop (returns `425` if a scheduled retry is imminent or in flight)
- `POST /events/{event_id}/rules/{rule_id}/cancel` — Stop further delivery for one rule on one event
- `POST /events/{event_id}/cancel` — Stop further delivery for every non-terminal rule on one event
- `GET /events/{event_id}/rules/{rule_id}/attempts` — Paginated list of delivery attempts for one rule on one event
- `GET /events/{event_id}/rules/{rule_id}/attempts/{attempt_id}` — Metadata for a single delivery attempt
- `GET /events/{event_id}/rules/{rule_id}/attempts/{attempt_id}/response-details` — Captured response data for a failed delivery attempt

### 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
- Auth.md agent registration status: https://meshes.io/auth.md
- OAuth Protected Resource Metadata: https://meshes.io/.well-known/oauth-protected-resource
- OAuth Authorization Server Metadata: https://meshes.io/.well-known/oauth-authorization-server
- Embed docs: https://meshes.io/docs/embed/embed
- Embed quickstart: https://meshes.io/docs/embed/quickstart
- Cursor rules repository: https://github.com/mesheshq/meshes-ai-tools
- MCP server repository: https://github.com/mesheshq/meshes-mcp-server

Auth.md status: Meshes does not currently support automated agent registration through Auth.md. Agents cannot create accounts, claim accounts, or obtain Meshes credentials through `/agent/auth`; that endpoint returns a structured unsupported response. Use the documented sign-up and API authentication flow instead.

---

## 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
- Integrations Docs Hub: https://meshes.io/docs/integrations/integrations
- ActiveCampaign Integration Docs: https://meshes.io/docs/integrations/activecampaign
- AWeber Integration Docs: https://meshes.io/docs/integrations/aweber
- Customer.io Integration Docs: https://meshes.io/docs/integrations/customer_io
- Discord Integration Docs: https://meshes.io/docs/integrations/discord
- HubSpot Integration Docs: https://meshes.io/docs/integrations/hubspot
- Intercom Integration Docs: https://meshes.io/docs/integrations/intercom
- Mailchimp Integration Docs: https://meshes.io/docs/integrations/mailchimp
- MailerLite Integration Docs: https://meshes.io/docs/integrations/mailerlite
- Pipedrive Integration Docs: https://meshes.io/docs/integrations/pipedrive
- Resend Integration Docs: https://meshes.io/docs/integrations/resend
- Salesforce Integration Docs: https://meshes.io/docs/integrations/salesforce
- SendGrid Integration Docs: https://meshes.io/docs/integrations/sendgrid
- Slack Integration Docs: https://meshes.io/docs/integrations/slack
- Webhooks Integration Docs: https://meshes.io/docs/integrations/webhooks
- Zoom Integration Docs: https://meshes.io/docs/integrations/zoom
- 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
- Integrations Catalog: https://meshes.io/integrations
- Use Cases: https://meshes.io/use-cases
- Guides: https://meshes.io/guides
- Use Case: Payment Failed Notifications: https://meshes.io/use-cases/payment-failed-notifications
- Use Case: User Signup Fan-Out: https://meshes.io/use-cases/user-signup-fan-out
- Use Case: Churn Prevention: https://meshes.io/use-cases/churn-prevention-event-routing
- Use Case: Trial Expiry Notifications: https://meshes.io/use-cases/trial-expiry-notifications
- Use Case: Lesson Completion Flows: https://meshes.io/use-cases/lesson-completion-flows
- Use Case: Page Completion Triggers: https://meshes.io/use-cases/page-completion-onboarding-sequences
- Use Case: Page Visit Intercom Tutorial Flows: https://meshes.io/use-cases/page-visit-intercom-tutorial-flows
- Use Case: Page Visit SMS Purchase Targeting: https://meshes.io/use-cases/page-visit-sms-purchase-targeting
- Guide: Send Payment Failure Alerts to Slack: https://meshes.io/guides/send-payment-failures-to-slack
- Guide: Update HubSpot on User Signup: https://meshes.io/guides/add-hubspot-properties-on-signup
- Guide: Send Signup Events to Mailchimp Welcome Flows: https://meshes.io/guides/send-signup-events-to-mailchimp
- Guide: Update Salesforce When Users Change Plans: https://meshes.io/guides/update-salesforce-on-plan-change
- Guide: Tag Intercom Users When Trials Are About to Expire: https://meshes.io/guides/tag-intercom-users-on-trial-expiry
- Guide: Update HubSpot on Lesson Completion: https://meshes.io/guides/lesson-completed-hubspot-progress
- Guide: Send Lesson Completion Events to Mailchimp Sequences: https://meshes.io/guides/lesson-completed-mailchimp-sequence
- Guide: Tag Intercom Users from High-Intent Page Visits: https://meshes.io/guides/page-visit-intercom-high-intent
- Guide: Trigger ActiveCampaign Onboarding Sequences from Page Completion: https://meshes.io/guides/page-completion-activecampaign-sequence
- Guide: Route High-Intent Page Visits into HubSpot SMS Workflows: https://meshes.io/guides/page-visit-hubspot-sms-intent
- Compare pages: https://meshes.io/compare
- Compare: Meshes vs. Zapier: https://meshes.io/compare/zapier
- Compare: Meshes vs. Make: https://meshes.io/compare/make
- Compare: Meshes vs. n8n: https://meshes.io/compare/n8n
- Compare: Meshes vs. Paragon: https://meshes.io/compare/paragon
- Compare: Meshes vs. Merge: https://meshes.io/compare/merge
- GitHub: https://github.com/mesheshq
- Cursor Rules: https://github.com/mesheshq/meshes-ai-tools
- MCP Server: https://github.com/mesheshq/meshes-mcp-server
- 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