> ## Documentation Index
> Fetch the complete documentation index at: https://developers.aimtell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Reference for every tool the Aimtell MCP server exposes

The server exposes 21 tools. Read tools run straight away. Tools marked **Write** run in two steps: call once without `confirm` to get a preview and token, then call again with the same arguments plus `confirm`. See [Confirming Writes](/mcp-server/overview#confirming-writes).

Every write tool also takes the optional `confirm` string, which is left out of the tables below.

## Sites and Account

### list\_sites

Lists every site on the account with its id, uid, url, name, subscriber count and active status. The numeric `id` is the `idSite` the other tools take.

Takes no parameters.

### get\_site

Gets the details for one site.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `idSite` | integer | Yes | Numeric site id (from list\_sites). |

### get\_user

Gets the authenticated account, including timezone, plan type and trial status. The auth token and billing fields are removed.

Takes no parameters.

## Manual Campaigns

### list\_campaigns

Lists a site's manual campaigns, newest first. Each row includes that campaign's `sentcount`, `clickcount`, `conversions`, `conversions_value` and `bounced`, so one call is enough to compare or rank campaigns. Pass `startDate` and `endDate` to total each campaign over that window instead of its lifetime.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `idSite` | integer | Yes | Numeric site id. |
| `startDate` | string | No | Start date 'YYYY-MM-DD'. With endDate, each campaign's totals cover only this window instead of its lifetime. |
| `endDate` | string | No | End date 'YYYY-MM-DD'. Use together with startDate. |
| `limit` | integer | No | Max campaigns to return, newest first. Defaults to 1000, max 10000. |
| `skip` | integer | No | Pagination offset. Defaults to 0. |
| `status` | string | No | Restrict to these campaign statuses, comma-separated (e.g. '5,6'). Omit for all of them. |

### get\_campaign

Gets one manual campaign by id.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | integer | Yes | Campaign id. |

### get\_campaign\_results

Gets day-by-day results for one manual campaign. To compare campaigns, use `list_campaigns` instead, which returns per-campaign totals in a single call.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | integer | Yes | Campaign id. |
| `date_start` | string | No | Start date 'YYYY-MM-DD'. |
| `date_end` | string | No | End date 'YYYY-MM-DD'. |

### create\_campaign

**Write**

Creates a manual campaign, either saved as a draft (`status` 1) or scheduled (`status` 2 with a future `schedule_date`). Supports multiple segments and recurring sends. This is the only tool that can send a push.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Campaign name (internal). |
| `idSite` | integer | Yes | Numeric site id. |
| `title` | string | No | Push title. |
| `body` | string | No | Push body. |
| `link` | string | No | Click-through URL. |
| `schedule_date` | string | No | Send time 'YYYY-MM-DD HH:MM:SS' in the account timezone. Must be in the future when status=2. Required to schedule. |
| `segments` | string | No | Segment id(s) to target. Comma-separate for multiple, e.g. '12,34' (targets subscribers in any of them). Omit to target all subscribers. |
| `automation` | string | No | Recurrence. Presets: n=none (one-time), h=hourly, d=daily, w=weekly, m=monthly, y=yearly. Custom interval: `c{N}{unit}` where unit is h/d/w/m/y, e.g. `c3d` = every 3 days. Default n. |
| `tz_delivery` | `0` or `1` | No | 1 delivers at each subscriber's local time of day; 0 sends at one absolute time. |
| `status` | `1` or `2` | No | 1 saves a draft; 2 schedules it, which requires a future schedule\_date. Defaults to 1. |
| `customIcon` | string | No | URL of a custom icon (recommended size 250x250). |
| `customImage` | string | No | URL of a custom large image (recommended size 300x500). |
| `push_ttl` | integer | No | Seconds until the push expires if it cannot be delivered. Defaults to 1 week. |
| `auto_hide` | integer | No | Seconds (255 max) until the notification hides itself. 0 keeps it on screen until the subscriber interacts with it. |

## Drafts

### create\_draft\_campaign

**Write**

Saves a manual campaign as a draft. It appears under Drafts on the site's manual campaigns page and sends nothing.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Campaign name (internal). |
| `idSite` | integer | Yes | Numeric site id. |
| `title` | string | No | Push title. |
| `body` | string | No | Push body. |
| `link` | string | No | Click-through URL. |
| `customIcon` | string | No | URL of a custom icon (recommended size 250x250). |
| `customImage` | string | No | URL of a custom large image (recommended size 300x500). |
| `segments` | string | No | Segment id(s) to target once it is scheduled. Comma-separate for multiple, e.g. '12,34'. Omit to target all subscribers. |

### create\_draft\_triggered\_campaign

**Write**

Saves a triggered campaign as a draft, set to fire on the given tracked event once activated. The delay, follow ups and conversion tracking are set in the dashboard, where it is activated.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Campaign name. |
| `idSite` | integer | Yes | Numeric site id. |
| `title` | string | No | Push title. |
| `body` | string | No | Push body. |
| `link` | string | No | Click-through URL. |
| `customIcon` | string | No | URL of a custom icon (recommended size 250x250). |
| `customImage` | string | No | URL of a custom large image (recommended size 300x500). |
| `eventCategory` | string | No | Category of the tracked event that will trigger it, exactly as the site tracks it. |
| `eventAction` | string | No | Action of the tracked event that will trigger it, exactly as the site tracks it. |
| `eventLabel` | string | No | Optional event label to narrow the trigger. |

### create\_draft\_rss\_campaign

**Write**

Saves an RSS campaign as a draft. The title, body and link may use `{rss_title}`, `{rss_body}` and `{rss_link}` to insert values from each feed item. It is activated in the dashboard.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Campaign name. |
| `idSite` | integer | Yes | Numeric site id. |
| `feed_url` | string | No | URL of the RSS feed to watch. |
| `title` | string | No | Push title. |
| `body` | string | No | Push body. |
| `link` | string | No | Click-through URL, or `{rss_link}` for the feed item's own link. |
| `customIcon` | string | No | URL of a custom icon (recommended size 250x250). |
| `customImage` | string | No | URL of a custom large image (recommended size 300x500). |
| `segments` | string | No | Segment id(s) to target once active. Comma-separate for multiple, e.g. '12,34'. Omit to target all subscribers. |

### update\_draft

**Write**

Changes a saved manual, triggered or RSS draft. Pass only the fields that change; everything else is kept. Campaigns that are scheduled or active, and A/B test drafts, are refused. It never schedules or activates the campaign.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `type` | `manual` or `triggered` or `rss` | Yes | Which kind of campaign the draft is. |
| `id` | integer | Yes | Campaign id of the draft. |
| `name` | string | No | Campaign name (internal). |
| `title` | string | No | Push title. |
| `body` | string | No | Push body. |
| `link` | string | No | Click-through URL. On an RSS draft, `{rss_link}` for the feed item's own link. |
| `customIcon` | string | No | URL of a custom icon (recommended size 250x250). |
| `customImage` | string | No | URL of a custom large image (recommended size 300x500). |
| `segments` | string | No | Manual and RSS only. Segment id(s) to target, comma-separated, e.g. '12,34'. An empty string targets all subscribers. |
| `eventCategory` | string | No | Triggered only. Category of the tracked event that triggers it. |
| `eventAction` | string | No | Triggered only. Action of the tracked event that triggers it. |
| `eventLabel` | string | No | Triggered only. Event label to narrow the trigger. |
| `feed_url` | string | No | RSS only. URL of the RSS feed to watch. |

## Welcome Notification

### upsert\_welcome\_campaign

**Write**

Creates or updates the welcome notification sent to a site's new subscribers right after they opt in.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `idSite` | integer | Yes | Numeric site id. |
| `title` | string | Yes | Push title. |
| `body` | string | Yes | Push body. |
| `link` | string | Yes | Click-through URL. |
| `status` | `0` or `1` | Yes | 0 = draft, 1 = active. |
| `customIcon` | string | No | URL of a custom icon (recommended size 250x250). |
| `customImage` | string | No | URL of a custom large image (recommended size 300x500). |

## Segments

### list\_segments

Lists all segments for a site with their id (`idsegment`), name and definition.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `idSite` | integer | Yes | Numeric site id. |

### get\_segment

Gets one segment by id.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | integer | Yes | Segment id (idsegment). |

### list\_segment\_fields

Returns the segment definition format, every available field with its allowed operators and value format, and the operator legend. Useful before calling `create_segment`.

Takes no parameters.

### create\_segment

**Write**

Creates a segment from a definition string. See [Segment definitions](#segment-definitions).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `idSite` | integer | Yes | Numeric site id. |
| `name` | string | Yes | Segment name. |
| `definition` | string | No | Segment definition, e.g. '(region==California)'. See [Segment definitions](#segment-definitions). Empty matches all subscribers. |

### get\_segment\_counts

Gets a segment's subscriber counts over time.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | integer | Yes | Segment id (idsegment). |
| `date_start` | string | No | Start date 'YYYY-MM-DD'. |
| `date_end` | string | No | End date 'YYYY-MM-DD'. |

## Subscribers

### get\_subscribers

Gets subscribers for a site, with pagination.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `idSite` | integer | Yes | Numeric site id. |
| `limit` | integer | No | Max rows to return. |
| `offset` | integer | No | Pagination offset. |

### track\_subscriber\_attribute

**Write**

Sets custom attributes, or the `user` and `email` aliases, on a subscriber. Identify the subscriber by `subscriber_uid`, or by an existing email or user alias.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `idSite` | integer | Yes | Numeric site id. |
| `subscriber_uid` | string | No | Aimtell subscriber uid. |
| `user` | string | No | Set the subscriber's 'user' alias. |
| `email` | string | No | Set the subscriber's 'email' alias. |
| `attributes` | string | No | JSON string of custom attributes, e.g. `{"plan":"pro","ltv":120}`. |

## Reporting

### get\_analytics

Gets one metric as a time series over a date range. Pass `idSite` for one site, or omit it for an all-sites rollup (set `breakdown` to true for per-site numbers instead of a summed total). Returns an object keyed by date, or by site id when `breakdown` is true. See [Analytics metrics](#analytics-metrics).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `type` | string | Yes | Metric to fetch. See [Analytics metrics](#analytics-metrics). |
| `startDate` | string | Yes | Start date 'YYYY-MM-DD' (inclusive). |
| `endDate` | string | Yes | End date 'YYYY-MM-DD' (inclusive). |
| `idSite` | integer | No | Numeric site id for a single-site report. Omit for an all-sites rollup. |
| `breakdown` | boolean | No | All-sites report only: true returns a per-site breakdown keyed by site id; false/omitted returns one summed total time series. |
| `country` | string | No | Filter to one country: 'us', 'international', or a 2-letter ISO code such as 'CA'. Not supported for conversions, conversionsvalue, optin, purged, newsubscribersutm or any numbered variant. |
| `segmentId` | integer or string | No | Filter to one segment id. Requires idSite. |

### get\_notification\_logs

Gets a site's notification delivery log, optionally filtered to one subscriber.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `idSite` | integer | Yes | Numeric site id. |
| `subscriber_uid` | string | No | Filter to one subscriber. |
| `limit` | integer | No | Max rows. |
| `skip` | integer | No | Pagination offset. |

## Segment Definitions

`create_segment` takes a definition string made of one or more condition groups in parentheses.

* Groups are joined by `,` and all must match (AND).
* Inside a group, conditions are joined by `,` (AND) or `|` (OR).
* Each condition is `field` + `operator` + `value` with no spaces, and values are unquoted full names, such as `region==California` or `country==United States`.
* Custom attributes are referenced by their own name as the field, such as `plan==pro` or `ltv>100`.
* An empty definition matches all subscribers.

| Operator | Meaning |
| - | - |
| `==` | is |
| `!=` | is not |
| `=@` | contains |
| `!@` | does not contain |
| `<` `>` `<=` `>=` | numeric or date comparison |
| `@@` | exists (no value) |
| `!!` | does not exist (no value) |

| Definition | Matches |
| - | - |
| `(region==California)` | Subscribers in California |
| `(country==United States,deviceType==mobile)` | US subscribers on mobile |
| `(browserName==Chrome\|browserName==Firefox)` | Chrome or Firefox users |
| `(region==California),(daysSinceLastVisit>30)` | Californians who haven't visited in over 30 days |
| `(welcomeCampaignClick@@)` | Subscribers who clicked the welcome notification |

Call `list_segment_fields` for the full catalog of fields and the operators each one accepts.

## Analytics Metrics

`get_analytics` takes one of these values for `type`:

| Type | Metric |
| - | - |
| `subscribers` | Total active subscribers over time |
| `newsubscribers` | New subscribers (opt-ins) per day |
| `newsubscribersutm` | New subscribers broken down by UTM attribution |
| `optin` | Opt-in rate, as a percentage |
| `notifications` | Notifications sent |
| `notificationclicks` | Notifications clicked |
| `conversions` | Conversions attributed to notifications |
| `conversionsvalue` | Total value of attributed conversions |
| `revenue` | Revenue attributed to notifications |
| `impressions` | Opt-in prompt impressions |
| `extensionclicks` | Browser extension clicks |
| `unsubscribes` | Subscribers lost to a manual unsubscribe |
| `inactive` | Subscribers removed for inactivity, per day |
| `purged` | Subscribers removed by purging, per day |
| `events` | Tracked custom events (all-sites rollup only) |
| `attributes` | Custom attribute counts (all-sites rollup only) |

Append a digit to `notifications`, `notificationclicks`, `conversions` or `conversionsvalue` to limit it to one campaign type: `1` Manual, `2` API, `3` Triggered, `4` RSS, `5` Welcome. For example, `notificationclicks3` is clicks on triggered campaigns.

<Note>
  Total subscribers lost is `unsubscribes` + `inactive` + `purged`. Using `unsubscribes` alone under-reports churn.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.