Tools

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

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

Parameter	Type	Required	Description
`type`	string	Yes	Metric to fetch. See 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.

Total subscribers lost is unsubscribes + inactive + purged. Using unsubscribes alone under-reports churn.

Javascript API

MCP Server

REST API

REST API - Push Notifications

REST API - Sites

REST API - Segmentation

REST API - Other

Sites and Account

list_sites

get_site

get_user

Manual Campaigns

list_campaigns

get_campaign

get_campaign_results

create_campaign

Drafts

create_draft_campaign

create_draft_triggered_campaign

create_draft_rss_campaign

update_draft

Welcome Notification

upsert_welcome_campaign

Segments

list_segments

get_segment

list_segment_fields

create_segment

get_segment_counts

Subscribers

get_subscribers

track_subscriber_attribute

Reporting

get_analytics

get_notification_logs

Segment Definitions

Analytics Metrics

​Sites and Account

​list_sites

​get_site

​get_user

​Manual Campaigns

​list_campaigns

​get_campaign

​get_campaign_results

​create_campaign

​Drafts

​create_draft_campaign

​create_draft_triggered_campaign

​create_draft_rss_campaign

​update_draft

​Welcome Notification

​upsert_welcome_campaign

​Segments

​list_segments

​get_segment

​list_segment_fields

​create_segment

​get_segment_counts

​Subscribers

​get_subscribers

​track_subscriber_attribute

​Reporting

​get_analytics

​get_notification_logs

​Segment Definitions

​Analytics Metrics

Sites and Account

list_sites

get_site

get_user

Manual Campaigns

list_campaigns

get_campaign

get_campaign_results

create_campaign

Drafts

create_draft_campaign

create_draft_triggered_campaign

create_draft_rss_campaign

update_draft

Welcome Notification

upsert_welcome_campaign

Segments

list_segments

get_segment

list_segment_fields

create_segment

get_segment_counts

Subscribers

get_subscribers

track_subscriber_attribute

Reporting

get_analytics

get_notification_logs

Segment Definitions

Analytics Metrics