Integrations & Rules

Meshes integrations are self-describing. The API tells you everything you need to create connections and rules for each integration type — what credentials are required, what actions are available, and what data each action needs.

This page explains the pattern. Once you understand it, the same workflow applies to all of the integrations.

The three pieces

1. Connection — a configured destination holding credentials (API keys, OAuth tokens, webhook URLs)
2. Action data — the live lists, tags, campaigns, properties, etc. available in the connected account
3. Rule — binds an event type to a connection + action, with metadata referencing items from the action data

Step 1: Discover integration metadata

GET /api/v1/integrations

This returns metadata for every supported integration. Each one defines:

• authentication — what type of credentials are needed and what fields to provide
• actions — what the integration can do, what data it needs, and what fields go into rule metadata

Step 2: Create a connection

How you create a connection depends on the authentication.type:

API key integrations

The authentication.fields array tells you exactly what goes in the connection's metadata object. Each field has a key, type (text or password), and helpText explaining where to find the value.

POST /api/v1/connections
{
  "workspace": "workspace-uuid",
  "type": "activecampaign",
  "name": "My ActiveCampaign",
  "metadata": {
    "api_url": "https://myaccount.api-us1.com",
    "api_key": "your-api-key"
  }
}

Integrations using API key auth: ActiveCampaign, Mailchimp, MailerLite, Resend

OAuth integrations

OAuth connections are created through the Meshes dashboard, which handles the OAuth flow. No metadata credentials are needed — the connection will already exist when you query the API.

Integrations using OAuth: AWeber, HubSpot, Intercom, Salesforce, Zoom

No-auth integrations

Some integrations don't require authentication but still need configuration fields (like a URL).

POST /api/v1/connections
{
  "workspace": "workspace-uuid",
  "type": "webhook",
  "name": "My Webhook",
  "metadata": {
    "url": "https://example.com/webhook"
  }
}

Integrations using no auth: Webhook

Step 3: Discover available actions

Each integration's actions object describes what rules can do. To get the live data for a specific connection (the actual lists, tags, campaigns, etc. from the connected account), call:

GET /api/v1/connections/{connection_id}/actions

This returns the selectable items for each action. For example, a HubSpot connection might return:

{
  "lists": [
    {
      "id": "5",
      "name": "Newsletter Subscribers",
      "createdAt": "2026-02-20T05:17:49.969Z"
    },
    {
      "id": "8",
      "name": "Active Subscriptions",
      "createdAt": "2026-02-20T20:28:24.829Z"
    }
  ],
  "properties": [
    {
      "id": "lifecycle_stage",
      "key": "lifecycle_stage",
      "name": "Lifecycle Stage",
      "options": [
        { "key": "lead", "value": "lead", "label": "Lead" },
        { "key": "customer", "value": "customer", "label": "Customer" }
      ]
    }
  ]
}

Step 4: Create rules

Rules bind an event type to a connection with action metadata. The metadata object always requires action (the action key), plus additional fields depending on the action type.

Simple actions

Most actions are simple — they require action and id, where id is the ID of an item from the action data (a list, tag, group, campaign, segment, meeting, or webinar).

POST /api/v1/rules
{
  "workspace": "workspace-uuid",
  "connection": "connection-uuid",
  "event": "user.signup",
  "metadata": {
    "action": "add_to_list",
    "id": "8"
  }
}

The id value comes from the action data returned in Step 3.

Advanced actions

Some actions require an id and a value. These are typically property-update actions where you select both a property and one of its allowed values.

POST /api/v1/rules
{
  "workspace": "workspace-uuid",
  "connection": "connection-uuid",
  "event": "payment.succeeded",
  "metadata": {
    "action": "update_property",
    "id": "lifecycle_stage",
    "value": "customer"
  }
}

The id is the property ID and value is one of the property's options values, both from the action data.

Actions with extra fields

A few actions accept additional optional fields beyond id. These are described in the integration metadata as "kind": "field" data items, which specify a label, type, and validation.

For example, Resend's send_email_template action requires a template id and optionally accepts subject and from overrides:

POST /api/v1/rules
{
  "workspace": "workspace-uuid",
  "connection": "connection-uuid",
  "event": "user.signup",
  "metadata": {
    "action": "send_email_template",
    "id": "tmpl_abc123",
    "subject": "Welcome aboard!",
    "from": "Team <team@example.com>"
  }
}

Webhook actions

Webhooks are the simplest — no action data is needed. The event payload is forwarded to the webhook URL as-is.

POST /api/v1/rules
{
  "workspace": "workspace-uuid",
  "connection": "webhook-connection-uuid",
  "event": "user.signup",
  "metadata": {
    "action": "send_webhook"
  }
}

Action reference

Here's a summary of every integration's actions and what metadata they require:

Putting it all together

Here's the full workflow to route user.signup events to a HubSpot list:

1. Check integrations — GET /api/v1/integrations confirms HubSpot uses OAuth and supports add_to_list
2. Find the connection — GET /api/v1/workspaces/{id}/connections to find your HubSpot connection (created via the dashboard OAuth flow)
3. Get action data — GET /api/v1/connections/{connection_id}/actions returns the available lists
4. Create the rule — POST /api/v1/rules with metadata: { action: "add_to_list", id: "8" }
5. Test — POST /api/v1/events with a test payload and verify with GET /api/v1/events/{id}

The same pattern works for every integration. The metadata is always self-describing — let the API guide you.