How to connect OneSignal MCP with Python

Attach a staged warmup schedule to an email campaign that is still a draft. This writes to the campaign, so do not call it unless the user has asked for the ramp to be applied or has agreed to it. Email only, drafts only, and only for a draft that already exists. This is the edit path: use it when the user wants to add or change the ramp on a draft they already have, and pass that draft's notification id. When you are creating the campaign yourself, do not use this tool at all: pass kind and email_warm_up to the email draft action instead, so the draft and its ramp land in one call. Do not call this for a campaign that has already been sent or whose warmup is already running. Always pass is_draft true, so the campaign stays a draft and the ramp is stored against it. Pass the items from recommended_warm_up_schedule through unchanged as stages, since the two use the same start, end, and quota shape. Only set strategy to custom when the user has changed the recommended stages; otherwise leave it unset. The email_warmup skill owns the wider flow: when to check volume, how to explain the risk, and what to say after applying. Nothing is queued or sent. The stages are stored against the draft and the ramp only begins once the user sends the campaign from the dashboard, so do not tell the user the warmup has started or that their first stage is under way.

Check whether an email send needs IP or domain warmup, given the sender domain and an estimated recipient count. Nothing is saved. Mainly a step in the email drafting flow rather than something users ask for directly: call it whenever the draft is email, before recommending a send or a schedule. It also answers the same question after the fact, when diagnosing a send that went badly. Pass the recipient count that send actually reached and the domain it went out on, and the advice tells you whether it was large enough relative to the domain's history to have needed a ramp. It takes a recipient count and a domain, no draft required. The email_deliverability skill owns that flow. Returns advice (none, recommended, required, or unspecified), factors explaining the verdict (exceeds_volume_threshold, exceeds_peak_30_day_recommendation), and baseline sending history for the domain (peak_daily_volume_30d, peak_date, contributing_app_count, where the app count covers every app sending on that domain). For a small enough send the check short-circuits to advice: none with a zeroed baseline, without consulting sending history. The threshold is decided by the API, so do not guess at it or quote a number. In that case say the send is too small to need warmup, and do not present the zeroed baseline as the domain's real sending history.

Create or update identity aliases for the user who owns a given subscription. The `onesignal_id` alias is read-only and must not be included.

Record custom events for OneSignal users, such as purchases, content views, or milestones. Use these to enter users into Journeys or trigger Wait Until nodes. Each event must set at least one of `external_id` or `onesignal_id`.

Create or update identity aliases for a user identified by alias. The `onesignal_id` alias is read-only and must not be included.

Create a new audience segment with filter conditions. Maximum 200 filter entries.

Create a new subscription and attach it to a user. Set `type` to the channel ("Email", "SMS", "iOSPush", "AndroidPush", etc.) and `token` to the email address, E.164 phone number, or push token.

Create a new notification template for a OneSignal app.

Create a new user in a OneSignal app. Provide an `identity` (e.g. {"external_id": "user-123"}) so the user can be referenced later by alias. Optionally attach `properties` (tags, language, country) and `subscriptions` (email, SMS, or push channels). The `identity` field is required to prevent orphaned users.

Estimate how many recipients an unsaved, in-progress email campaign would reach, from its segments and filters. Nothing is saved. Use before recommending a warmup or a schedule, or when the user asks how large the audience is for a draft they are composing. Email only. is_email must be sent as true, otherwise the count comes back as 0 regardless of the audience. Returns count (the estimate), uncapped_count, and cap_applied. cap_applied concerns the web-push free-tier subscriber cap and so is normally false for email. Feed count into check_send_volume to decide whether the send needs warmup.

Export audience activity for a notification to CSV. WARNING: Only 1 concurrent export is allowed per account — if a 409 or 429 is returned, a previous export is still running.

Export all subscriptions for a OneSignal app to CSV. WARNING: Only 1 concurrent export is allowed per account — if a 409 or 429 is returned, a previous export is still running.

List the email warmup ramps that are in flight for this app right now: which campaigns are ramping, and the app's combined day-by-day schedule with the planned quota and how much has actually gone out. Nothing is saved. Returns notifications, one entry per running warmup campaign with its id and title, and total_schedule, an ordered list of days with start, quota (recipients planned for that day across every running ramp) and acked (how many actually went out). An empty notifications list means no ramp is running. Two uses. Before proposing a new ramp, call this to see whether one is already running, because recommended_warm_up_schedule pushes a new schedule out past any warmup already in flight and the user should be told why their ramp starts later than they asked for. When diagnosing deliverability, call this to find out whether the window being judged overlaps a live ramp: a ramp holds sending volume down deliberately, so low send counts and thin per-provider samples during one are expected and are not evidence of a delivery problem. App-scoped and live-only. It covers every running warmup on this app and says nothing about ramps that have finished, been canceled, or are still sitting on a draft. Neither notifications nor total_schedule carries a sending domain, and the quota and acked totals are summed across every running ramp, so on an app that sends from more than one domain a live ramp here may belong to a different domain than the one being asked about. Do not attribute one domain's numbers to a ramp without saying the ramp is app-wide. For those, read kind and email_warm_up on get_notification for the specific campaign. Within a day that is still under way acked lags quota, so acked below quota is not on its own a sign the ramp is failing.

List the custom event definitions indexed for a OneSignal app, including each event's properties, sources, most recent occurrence, usage locations (segment/journey), storage and total counts, and retention duration. Requires OAuth authentication.

Get email domain DNS verification status for the current app. Returns all registered email domains, each with a state and with its DNS records (SPF, DKIM, DMARC, MX, tracking CNAME). DNS records. Every record carries a status: 3 means verified/passing. Use these to check whether a domain's DNS is set up correctly before suggesting DNS setup steps. Domain state. Separate from the records, each domain has a state field: 1 unverified, 2 active, 3 deactivated, 4 manually verified. Never mention or suggest a domain whose state is 3, even if all of its DNS records pass.

Retrieve the app's overall (app-wide) email reputation summary: aggregate bounce rate and spam complaint rate across all sending, returned for the last 24 hours, 7 days, and 30 days. These are the same app-wide rates OneSignal's abuse-prevention system tracks to automatically warn or disable an app that has a high bounce or spam-complaint rate, so this is the right tool when the user asks about their sending or account health, whether they are at risk of being flagged, blocked, or disabled, or their standing with OneSignal. This is app-wide (all sending domains combined), not per-domain or per-provider. For per-domain or per-provider deliverability and reputation (e.g. how a domain is doing at Gmail, Apple, or Outlook), use get_provider_metrics instead, and do not combine the two; their numbers will not reconcile. If it is unclear whether the user wants this app-wide reputation summary or metrics for a specific sending domain, ask which they mean, or clearly label these figures as the app-wide reputation summary. This is a summary, not a diagnosis: it tells you the rates are bad, never why. When the user wants the cause — mail going to spam, blocks, throttling, bounces, complaints, a drop in delivery — load the email_deliverability skill before going further. It owns choosing the scope, and the domain warmup check that decides whether suppressed volume is a ramp working or a real delivery problem.

Get per-inbox-provider email deliverability metrics for a sender domain over a time window, broken down by provider (Gmail, Apple, Outlook, Yahoo, etc.). Returns raw counts per provider: sent, delivered, opened, clicked, unique_opened, unique_clicked, failed, bounced, complained. This is the source of truth for per-domain deliverability. It is scoped to a single sender domain (the required domain param): one app may send from several domains, and one domain may be shared across apps, so these numbers cover only the requested domain, not the whole app. Prefer it over get_email_reputation and get_email_stats (both app-wide) and do not blend them; their numbers will not reconcile — in particular, these are TOTAL counts while get_email_stats reports app-wide UNIQUE counts. If the user asks about email delivery or deliverability without naming a domain, ask which sending domain they mean (get_email_domains lists the app's domains) or make clear your answer covers one specific domain; do not present per-domain data as if it were app-wide. Compute rates from the counts and state the numerator and denominator. Denominators are irregular: open rate = opened / delivered; complaint rate = complained / delivered; bounce rate = bounced / sent; failed rate = failed / sent. Use total opened, not unique_opened. Before assigning any band, check the provider's sent volume. If it is below 1,000, do not compute bands or give a reputation judgment for that provider. Say the sample is too small (only N sent) to assess reliably. This takes precedence over the bands below. Also check whether a domain warmup ramp was running over the requested window before you band anything. A ramp holds sending volume down deliberately, so it both starves providers of the sample the rule above needs and makes the window unrepresentative of how the domain normally sends. Call get_active_warm_up_schedules to find out; do not infer a ramp from the shape of the volume, and do not conclude there is none because the counts look ordinary. When one overlaps the window, report the counts, say the volume is suppressed by an active warmup rather than by an inbox provider, and do not band the affected providers. When the user is asking why deliverability is bad rather than what the numbers are, load the email_deliverability skill, which owns the full warmup check and the order to work the causes in. Judge each rate with these reputation bands. Open rate: Good >= 30%, Okay 20% to <30%, At risk 15% to <20%, Poor < 15%. Complaint rate: Good 0%, Okay >0% to <=0.1%, At risk >0.1% to <=0.3%, Poor > 0.3%. Bounce rate: Good < 1%, Okay 1% to <=5%, At risk >5% to <=10%, Poor > 10%. Failed rate: Good < 5%, Okay 5% to <=10%, At risk >10% to <=15%, Poor > 15%. Caveats. Apple never reports complaint data, so treat Apple's complaint rate as unavailable, not 0%, and never flag Apple on complaints. Gmail complaint counts here are Mailgun-sourced and unreliable (real Gmail complaint data lives in Gmail Postmaster Tools), so do not present a Gmail complaint rate from this data. Report the band as plain text (Good, Okay, At risk, Poor). Do not add emojis or icons. Use when the user asks how a domain is performing at inbox providers, wants to compare providers, or asks about sender reputation, bounces, or spam complaints.

Get a time series of email deliverability metrics for a sender domain, totaled across the requested inbox providers (all providers when none are given). Returns raw counts per time bucket: sent, delivered, opened, clicked, unique_opened, unique_clicked, failed, bounced, complained. Use when the user asks how a domain's deliverability is trending over time, or wants a chart. For a rate line, divide each bucket's numerator by its denominator using the same rules as get_provider_metrics (open and complaint over delivered; bounce and failed over sent). Render the series as a :::chart block. For a single reputation judgment over a whole window (for example 'how is my Apple failure rate' or 'has it improved since last week'), prefer get_provider_metrics over one or two windows rather than banding individual buckets; per-bucket rates are too noisy to band. A rising or stepped volume line is the expected shape of a domain warmup ramp, not a recovery or a problem. Before reading a trend as either, check whether a ramp covers the window: get_active_warm_up_schedules for one in flight, or kind and email_warm_up on get_notification for a specific campaign. Say when a ramp explains the shape rather than attributing it to inbox providers. Report any bands as plain text (Good, Okay, At risk, Poor). Do not add emojis or icons. This is the source of truth for per-domain deliverability trends. It is scoped to a single sender domain (the required domain param); one app may use several domains and one domain may be shared across apps, so it covers only the requested domain, not the whole app. These are TOTAL counts, whereas the app-wide get_email_stats reports UNIQUE counts — prefer this tool for per-domain trends, do not blend the two, and their numbers will not reconcile. If the user asks about email delivery trends without naming a domain, ask which sending domain they mean (get_email_domains lists the app's domains) or make clear the chart covers one specific domain, not the whole app.

Retrieve a single audience segment by ID. By default, includes full segment metadata and filters (`payload` object with `id`, `name`, `created_at`, `source`, and `filters`). Set `include_segment_detail` to `false` to return only the subscriber count. Note: the API returns 400 for user-based segments (those using custom_event or message_event filters).

Retrieve a single notification template by ID.

Retrieve all identity aliases associated with a user. Identify the user by `alias_label` (typically "external_id") and `alias_id`.

Retrieve the identity aliases for the user who owns a given subscription.

List OneSignal apps accessible to the authenticated user. Returns app names, IDs, and organization info. Supports pagination via limit and offset parameters.

List push notifications for a OneSignal app. Use `limit` (default 50, max ~250) and `offset` for pagination. Avoid large offsets — this endpoint has known performance degradation at high page numbers.

List audience segments for a OneSignal app. Maximum 300 segments per page.

List notification templates for a OneSignal app. Maximum 50 per page.

Return the current OneSignal MCP server configuration and connected app details.

Check the health status of the OneSignal MCP server.

Return an overview of the OneSignal REST API reference, including available endpoints and rate limits.

Turn on push delivery for a platform during OneSignal SDK setup by uploading its credentials — an APNs `.p8` auth key, a Firebase FCM v1 service-account JSON, or a web push site origin. This is a first-time onboarding step aimed at getting a developer's app sending: credentials write once per platform, and a platform that already has them returns 409 (replacing existing credentials stays in the dashboard). For APNs and FCM, read the credential file locally and pass its base64-encoded contents — this server is remote and cannot read local paths. Provide the complete field set for exactly one platform per call: APNs requires `apns_p8` (base64 of the `.p8`) plus `apns_key_id`, `apns_team_id`, and `apns_bundle_id`; FCM requires `fcm_v1_service_account_json` (base64 of the JSON); web push requires `chrome_web_origin` (the site's `https://` origin) with `chrome_web_default_notification_icon` (an icon URL) optional. Only `.p8` is accepted for APNs (not `.p12`). The raw API response is passed through unchanged so its status and body can be acted on.

Load OneSignal workflow guidance by name. Call this when a tool description or the user's request refers to a skill, before attempting the workflow. Available skills: - brand_kit: Apply the app's saved Brand Kit (colors, fonts, logos, tone) when generating or editing branded email or in-app message HTML. - brand_kit_profile: Apply the app's saved Brand Kit voice profile (tone, audience, language to avoid) when writing push or SMS copy. Plain-text channels only — no colors, fonts, or logos. - email_deliverability: Load before diagnosing an email deliverability problem the user is already having — mail landing in spam, blocked or throttled by an inbox provider, bounces, spam complaints, failed or suppressed recipients, a drop in delivery or opens, or poor sender reputation at Gmail, Apple, Outlook or Yahoo. Covers choosing the right scope, judging the rates, and working out whether domain warmup explains what they are seeing. - email_html: Brand-agnostic rules every generated or edited HTML email must follow — the unsubscribe-link token and mobile responsiveness — regardless of Brand Kit status, editor (create vs. edit), or prompt type. - email_warmup: Load before creating or sending an email campaign, to size the audience and decide whether the send needs domain or IP warmup. Covers large or first sends on a new or cold sending domain, the deliverability and sender-reputation risk of sending one un-ramped, ISP throttling and blocking, staged ramp schedules, and creating a draft with a warmup ramp on it or adding one to an existing draft. For a delivery problem that has already happened, load email_deliverability instead.

Get a recommended staged warmup schedule for an email send: when each stage starts and ends, and how many recipients it covers. Nothing is saved. Email only. This is a step in the email drafting flow rather than something users ask for directly. Call it after check_send_volume returns advice of recommended or required, to answer what the warmup actually looks like. Returns items, an ordered list of stages with start, end, and quota (the number of recipients that stage sends to). Summarize the ramp and the date the full audience is reached rather than reciting every stage. The schedule starts at 9:00 AM in the time zone of user_time, tomorrow if it is already past 9:00 AM there, and is pushed later if an existing warmup campaign is already running, so the stages can begin after the date the user asked for. When they do, get_active_warm_up_schedules names the campaign holding that slot. Pass a later user_time only when the user has asked to start on a specific date. The baseline here is the app's own maximum daily delivered volume over the last three weeks, which is not the domain-wide 30-day peak that check_send_volume reports, so the two can differ. Do not present this schedule as domain-scoped.

Send a push notification, email, or SMS via the OneSignal API. TIER 3 — HIGH IMPACT: confirmation is required before sending. Rate limited to 10 requests per minute. The `filters` array is limited to 200 entries; max 20,000 users per call. For push: set `contents`. For email: set `email_subject` + `email_body` (or use `template_id`). For SMS: set `contents` + `target_channel = "sms"`.

Start an iOS Live Activity and deliver it to a specific device subscription.

Transfer a subscription to a different user within the same app. Cross-app transfers are not supported. Rate limited to 1 request per second per subscription.

Unsubscribe an email address using the token from an email unsubscribe link. This endpoint uses token-based auth (no REST API key required).

Update or end an active iOS Live Activity.

Update an existing audience segment's name and/or filter conditions. `name` is always required even if not changing it (max 128 characters). When `filters` is provided it replaces all existing filters; omit to keep existing filters intact. Maximum 200 filter entries.

Update an existing subscription (token, enabled status, or test type).

Update a subscription identified by its channel type and token. Provide `subscription_type` and `token` to identify the subscription, then pass the fields to update in `subscription`.

Update an existing notification template. The `name` field is required even if you are not changing it.

Update an existing user identified by alias. Use `properties` to set tags, language, or country. Use `deltas` to increment session counts or append purchase records (these add to existing values rather than overwriting). Returns 202 — the update is processed asynchronously.

Retrieve a single notification by ID.

Retrieve outcome statistics for a OneSignal app (e.g. click counts, session duration). Note: data retention is approximately 30 days.

Retrieve a user and their properties by alias. Use `alias_label` "external_id" with the user's external ID, or another alias label you have configured.