Connect IRONSCALES

IRONSCALES is an email security platform built for MSPs. It sits on top of your customers' Microsoft 365 or Google Workspace mail, catches phishing that got past the native filters, lets employees…

Written By Christopher Scaminaci

Last updated 6 days ago

IRONSCALES is an email security platform built for MSPs. It sits on top of your customers' Microsoft 365 or Google Workspace mail, catches phishing that got past the native filters, lets employees report suspicious messages, and removes a confirmed threat from every inbox that received it. It also runs the other half of the problem: phishing-simulation campaigns and security awareness training, so you can measure whether people actually spot a fake. StackJack talks to IRONSCALES through its partner API.

Connecting IRONSCALES to StackJack gives your AI assistant a family of ironscales_ MCP tools — MCP (Model Context Protocol) tools are the standardized commands an AI assistant can call through StackJack. With them, your AI can:

Work the phishing queue — list incidents and the ones still unclassified, read the full evidence behind each, and see which messages a retro-scan re-flagged after delivery
Report on protection — mitigation statistics, email volume and verdicts, impersonation incidents, and the departments and individual people being targeted most
Watch for account takeover — the suspicious sign-in activity IRONSCALES flagged, with the events behind each verdict
Track training — campaign results, per-person performance over time, and the compliance report showing who has finished their assigned training
Audit coverage — protected mailboxes, licensed domains, licence consumption per company, and whether each company's mail integration is actually connected
Triage and remediate (on Pro plans) — classify an incident so IRONSCALES removes the threat fleet-wide, split or re-group clustered incidents, and run account-takeover remediation
Build and run training (on Pro plans) — compose a campaign as a draft, launch it, stop one that is going badly, and manage allow-lists, alert recipients and detection sensitivity
Manage companies and licensing (on Pro plans) — provision companies, add mailboxes and licensed domains, and adjust licences

How StackJack authenticates to IRONSCALES

IRONSCALES uses a single long-lived API key. You generate it once in the IRONSCALES console and paste it into StackJack — there is no client ID, no second secret, and nothing to renew on a schedule.

Behind the scenes IRONSCALES does not accept that key directly on each request: it exchanges it for a short-lived access token first. StackJack handles that exchange for you, keeps the token fresh, and gets a new one automatically when it expires. You never see it.

Choose the right kind of key first

This is the one decision worth making carefully, because it determines what works:

A partner key sees every company you manage. It can list, create, license and configure them, and it is what you want if you are managing customers through IRONSCALES.
A company key sees one company only. Everything scoped to that company works normally, but the partner-wide tools — listing companies, provisioning, licensing — are refused.

If you use a company key, tools like "list companies" will report that IRONSCALES refused the request. That is expected and does not mean the connection is broken; the connection test will still show as connected.

Steps

Decide partner or company scope, as above. If you want partner-wide reach, generate the key from your partner account rather than from inside a single company.
Generate the API key in the IRONSCALES console, signed in as an administrator, from the API settings area.
Copy the key straight away and store it securely. Treat it as a password — anyone holding it can read and act on your IRONSCALES account.
Paste it into StackJack. Open Connectors, choose IRONSCALES, and paste the key. There is no URL to enter: IRONSCALES is a single global service with no regional endpoints, so the address is fixed.
Run a Test Connection to confirm StackJack can reach IRONSCALES with the key.

What to know before your AI uses this connector

Some tools send real email to real people

This is the most important thing about the IRONSCALES connector, and it is easy to miss because the vendor's own naming understates it:

Approving a campaign launches it. IRONSCALES calls the step "approve a draft campaign", which sounds like a paperwork state change. It is not — approving sends the simulated phishing or training messages to your employees, and there is no way to unsend them.
A "test send" is a small live send. The three test-send tools deliver to up to ten real mailboxes. They are for checking how a message renders with willing colleagues, not for rehearsing without sending anything.

All of these require the Pro tier and are marked destructive. Whether your AI application asks you to confirm before running one depends on that application's own settings — see Destructive tools and confirmation. Review those settings before you grant a launch or a test send.

Building a campaign sends nothing. Creating one leaves it as a draft that sends nothing at all. Launching is a separate, clearly-marked step. That split is deliberate: your AI can assemble an entire campaign — templates, training, audience, schedule — and leave the decision to actually send it to a person. You can also ask it to calculate how many people an audience filter would reach before anything is launched.

Some tools change protection itself

Disconnecting a mail integration ends protection for that whole company. Mail keeps flowing, so nothing looks broken to the customer — it simply stops being inspected. Reconnecting is not something StackJack can do on its own: the customer's own administrator has to go through the consent flow again.
Classifying an incident triggers remediation. Marking a cluster malicious removes those messages from every inbox that received them; marking a real threat safe leaves it in place.
Account-takeover remediation acts on a real person's account, and can disable it or force a password reset.
Cancelling licences and removing licensed domains affect both billing and coverage. Mailboxes on a removed domain stop being protected.
Turning off directory sync breaks nothing immediately, but the mailbox list stops tracking the customer's directory, so coverage drifts as staff join and leave.

Every one of these is marked as destructive and requires the Pro tier. Whether your AI application asks you to confirm first depends on that application's own settings.

Plans and limits

Read tools are available on the Free tier. Everything that writes, remediates, launches a campaign or changes licensing is Pro. Business reaches the same tools as Pro and differs by monthly call quota.

See the generated IRONSCALES tool reference for the current inventory, plan assignment, input schemas, and destructive-action labels.

IRONSCALES allows 120 API calls a minute per company, and a few individual operations are throttled harder than that. StackJack paces requests and backs off automatically if you are throttled, which usually turns a large report into a slower one rather than a failed one. Pacing is not a guarantee: retries are bounded, so a wide enough report can still come back throttled or time out. Narrow the window or the audience, and check whether a write landed before repeating it — see Retrying a failed or timed-out write.

Several customers

Some MSPs need one IRONSCALES connection per customer, console or region. StackJack can hold several named connections of one connector, and your AI names the one it wants on each call. See Several connections of one connector.

Troubleshooting

"IRONSCALES rejected the access token" — the API key is no longer valid. StackJack gets a fresh token and retries automatically, so a failure that reaches you generally means the key itself was revoked or replaced. Generate a new key in the IRONSCALES console, paste it into StackJack and run a Test Connection.

One thing worth knowing if you are comparing notes with IRONSCALES support: this API reports an authentication failure with the same status code most services use for a malformed request. An error that mentions authentication really is about the key, even if it looks like a request problem.

"IRONSCALES accepted the key but refused this operation" — almost always the key's reach rather than a fault. A company-scoped key cannot use the partner-wide company, provisioning and licensing tools. If you need those, generate the key from your partner account and re-enter it.

A company shows no incidents at all — check the integration status before assuming it has been a quiet week. A mail integration that was never completed, or has since been disconnected, looks exactly the same as no threats.

Some of a customer's mail is not being inspected — check the licensed domains for that company. A mailbox on a domain that is not licensed is not covered, and nothing about it looks like an error.

IRONSCALES tools

ironscales_ · 100 tools · Free 56 · Pro 44

Companies

Tool	What it does
`ironscales_activate_auto_sync` Pro · Write	Turn on directory Auto-Sync for this company, so the protected mailbox list tracks the customer's Microsoft 365 or Google Workspace directory.
`ironscales_create_company` Pro · Write	Provision a new company under this partner.
`ironscales_delete_911_email_settings` Pro · Destructive	DESTRUCTIVE: remove the company's 911 (emergency report) email configuration.
`ironscales_disable_auto_sync` Pro · Destructive	DESTRUCTIVE: stop directory Auto-Sync for this company.
`ironscales_disable_company` Pro · Destructive	DESTRUCTIVE: deactivate an entire company in IRONSCALES.
`ironscales_generate_owa_manifest` Pro · Write	Generate the Outlook on the web (OWA) add-in manifest for this company — the XML/JSON descriptor an administrator uploads to Microsoft 365 to deploy the IRONSCALES report button.
`ironscales_get_911_email_settings` Free · Read-only	Get the company's 911 (emergency report) email configuration — the mailbox employees forward suspicious mail to, and how IRONSCALES handles what arrives there.
`ironscales_get_auto_sync_status` Free · Read-only	Get whether directory Auto-Sync is active for this company, and how it is configured.
`ironscales_get_company` Free · Read-only	Get one company's profile by its numeric id, from ironscales_list_companies.
`ironscales_get_company_features` Free · Read-only	Get which IRONSCALES product features are switched on for this company, and their access state.
`ironscales_get_company_stats` Free · Read-only	Get one company's statistics and licence position — protected mailbox counts against entitlement, and the activity totals IRONSCALES reports for the company.
`ironscales_list_auto_sync_groups` Free · Read-only	List the directory groups available to Auto-Sync for this company — the groups whose members can be brought under protection automatically.
`ironscales_list_auto_sync_mailboxes` Free · Read-only	List the mailboxes Auto-Sync has brought into this company from the customer's directory.
`ironscales_list_companies` Free · Read-only	List the companies this partner manages — the ENTRY POINT for this connector.
`ironscales_list_companies_v2` Free · Read-only	List the partner's companies using the NEWER V2 endpoint, which adds paging to the same data.
`ironscales_update_911_email_settings` Pro · Write	Set the company's 911 (emergency report) email configuration — the mailbox employees forward suspicious messages to, and how IRONSCALES treats what arrives.
`ironscales_update_company` Pro · Write	Update a company's profile — its name, domains, contact and configuration attributes.
`ironscales_update_company_features` Pro · Destructive	DESTRUCTIVE: change which IRONSCALES features are enabled for a whole company.

Incidents

Tool	What it does
`ironscales_classify_incident` Pro · Destructive	DESTRUCTIVE: classify an incident.
`ironscales_create_account_takeover_remediation` Pro · Destructive	DESTRUCTIVE: execute account-takeover remediation for an ATO incident.
`ironscales_get_account_takeover_incident` Free · Read-only	Get the detail of an account-takeover (ATO) incident — the suspicious sign-in activity IRONSCALES observed for a mailbox, with the events behind the verdict.
`ironscales_get_incident` Free · Read-only	Get the full detail of one incident — the reported message, its sender and recipients, IRONSCALES' verdict and confidence, the affected mailboxes, and the remediation state.
`ironscales_get_remediation_status_stats` Free · Read-only	Get counts of incidents by remediation outcome over a time window — how much was removed, quarantined or left in place.
`ironscales_list_incident_ids_by_status` Free · Read-only	Get just the incident IDs in one status — the cheapest way to answer 'what is waiting for me', IRONSCALES documents exactly one status value for this call, 'open' (its own operation title calls these the unclassified incidents; passing 'unclassified' as the status returns 404).
`ironscales_list_incidents` Free · Read-only	List a company's phishing incidents — the main triage queue.
`ironscales_list_scanback_incidents` Free · Read-only	List incidents raised by a retro-scan (scanback) — mail already delivered that a later verdict re-flagged, rather than mail caught or reported when it arrived.
`ironscales_recluster_incident` Pro · Write	Recluster an incident — ask IRONSCALES to re-group the messages it considers part of the same campaign.
`ironscales_uncluster_incident` Pro · Write	Uncluster an incident — split messages IRONSCALES grouped as one campaign back into separate incidents, so they can be judged individually.

Mitigation

Tool	What it does
`ironscales_get_company_mitigation_details` Free · Read-only	Get company-wide mitigation detail — the incidents IRONSCALES acted on and what it did, rolled up for the company rather than per mailbox.
`ironscales_get_email_stats` Free · Read-only	Get email volume and verdict statistics for a company over a time window — how much mail was scanned and how it was judged.
`ironscales_get_latest_impersonation_incidents` Free · Read-only	Get the company's most recent impersonation incidents — mail where the sender was posing as a colleague, executive or trusted brand.
`ironscales_get_mailbox_mitigation_details` Free · Read-only	Report what IRONSCALES mitigated per mailbox for one company — which mailboxes received flagged mail and what happened to it.
`ironscales_get_mitigation_stats` Free · Read-only	Get the company's mitigation statistics for a period — the headline counts of what IRONSCALES caught and removed.
`ironscales_get_mitigation_stats_v2` Free · Read-only	Get the company's mitigation statistics using the NEWER V2 report.
`ironscales_get_most_targeted_departments` Free · Read-only	Rank the company's departments by how much malicious mail was aimed at them over a time window — useful for deciding where to point training.
`ironscales_get_most_targeted_employees` Free · Read-only	Rank the company's individual employees by how much malicious mail was aimed at them over a time window — the people worth prioritising for training or tighter controls.
`ironscales_search_impersonation_incidents` Free · Read-only	Search the company's impersonation incidents with filtering and paging.

Security Awareness Training

Tool	What it does
`ironscales_approve_sat_campaign` Pro · Destructive	DESTRUCTIVE — SENDS REAL EMAIL TO REAL PEOPLE.
`ironscales_calculate_sat_participants` Free · Read-only	Work out how many people a given audience filter would reach, without enrolling or sending anything.
`ironscales_create_sat_campaign` Pro · Write	Create a security-awareness campaign as a DRAFT.
`ironscales_delete_sat_campaign` Pro · Destructive	DESTRUCTIVE: delete a SAT campaign.
`ironscales_get_sat_campaign` Free · Read-only	Get one SAT campaign's full definition — its templates, trainings, schedule, audience and current status.
`ironscales_get_sat_campaign_setup` Free · Read-only	Get the campaign setup options for this company — the choices available when building a campaign (flows, schedules, locales and the like).
`ironscales_get_sat_campaign_stats` Free · Read-only	Get one SAT campaign's results — delivery, open, click and report rates, and training completion.
`ironscales_get_sat_training_preview` Free · Read-only	Get a preview URL for one training module in a given language, so a human can review the content before it is assigned to staff.
`ironscales_list_sat_campaigns` Free · Read-only	List the company's security-awareness campaigns with their full detail — status, schedule, flow type and locale.
`ironscales_list_sat_cta_pages` Free · Read-only	List the call-for-action pages available to this company — the follow-up pages shown after an employee interacts with a simulation, typically the teaching moment.
`ironscales_list_sat_landing_pages` Free · Read-only	List the landing pages available to this company — the pages a simulated phishing link takes an employee to when they click.
`ironscales_list_sat_participants` Free · Read-only	List the company's training participants grouped by category — who is eligible to receive campaigns, organised the way IRONSCALES groups them.
`ironscales_list_sat_template_categories` Free · Read-only	List the template categories available to this company.
`ironscales_list_sat_templates` Free · Read-only	List the phishing-simulation and training templates available to this company.
`ironscales_list_sat_training_providers` Free · Read-only	List the training providers available to this company.
`ironscales_list_sat_trainings` Free · Read-only	List the training modules available from one provider.
`ironscales_lookup_sat_campaigns` Free · Read-only	Get a lightweight id-and-name list of the company's SAT campaigns — the cheap way to resolve a campaign name to the id the other tools need, without pulling full campaign records.
`ironscales_search_sat_participants` Free · Read-only	Search the company's training participants.
`ironscales_send_sat_campaign_simulation_test` Pro · Destructive	DESTRUCTIVE — SENDS REAL EMAIL TO REAL PEOPLE.
`ironscales_send_sat_campaign_training_test` Pro · Destructive	DESTRUCTIVE — SENDS REAL EMAIL TO REAL PEOPLE.
`ironscales_send_sat_template_test` Pro · Destructive	DESTRUCTIVE — SENDS REAL EMAIL TO REAL PEOPLE.
`ironscales_stop_sat_campaign` Pro · Write	Stop an active SAT campaign, halting any sends that have not gone out yet.

Phishing Campaigns

Tool	What it does
`ironscales_get_campaign_details` Free · Read-only	Get the company's phishing-simulation campaigns and their delivery detail over a period.
`ironscales_get_campaign_participants` Free · Read-only	Get the per-participant detail for one phishing-simulation campaign — who received it and what each person did (opened, clicked, reported, or nothing).
`ironscales_perform_campaign_participant_action` Pro · Destructive	DESTRUCTIVE — REACHES REAL PEOPLE.

Settings

Tool	What it does
`ironscales_append_challenged_alert_settings` Pro · Write	Append to the company's challenged-alert notification settings — add recipients or options without disturbing the existing configuration.
`ironscales_append_incident_alert_settings` Pro · Write	Append to the company's incident notification settings — add recipients or options without disturbing what is already configured.
`ironscales_create_allow_list_entry` Pro · Write	Add entries to the company's allow-list, telling IRONSCALES to treat those senders, domains or addresses as safe.
`ironscales_create_challenged_alert_settings` Pro · Write	Create the company's challenged-alert notification settings — establish who is told when IRONSCALES challenges a message.
`ironscales_create_incident_alert_settings` Pro · Write	Create the company's incident notification settings — establish who is alerted when IRONSCALES raises an incident.
`ironscales_delete_allow_list_entries` Pro · Destructive	DESTRUCTIVE: remove entries from the company's allow-list.
`ironscales_delete_challenged_alert_settings` Pro · Destructive	DESTRUCTIVE: remove the company's challenged-alert notification settings.
`ironscales_delete_incident_alert_settings` Pro · Destructive	DESTRUCTIVE: remove the company's incident notification settings.
`ironscales_get_account_takeover_settings` Free · Read-only	Get the company's account-takeover (ATO) detection sensitivity — how aggressively IRONSCALES flags suspicious sign-in behaviour.
`ironscales_get_challenged_alert_settings` Free · Read-only	Get the company's challenged-alert notification settings — who is told when IRONSCALES challenges a message and how.
`ironscales_get_incident_alert_settings` Free · Read-only	Get the company's incident notification settings — who is told when IRONSCALES raises an incident, and how.
`ironscales_list_allow_list_entries` Free · Read-only	List the company's allow-list entries — the senders, domains and addresses IRONSCALES is told to treat as safe.
`ironscales_update_account_takeover_settings` Pro · Write	Set the company's account-takeover detection sensitivity.
`ironscales_update_allow_list_entry` Pro · Write	Update an existing allow-list entry.

Mailboxes

Tool	What it does
`ironscales_add_mailboxes` Pro · Write	Add mailboxes to a company so IRONSCALES protects them.
`ironscales_bulk_edit_mailboxes` Pro · Destructive	DESTRUCTIVE: change many mailboxes in one call.
`ironscales_get_mailbox_compliance_report` Free · Read-only	Get the company's training compliance report — who has completed their assigned security-awareness training and who has not, over a period.
`ironscales_get_user_campaign_performance` Free · Read-only	Get per-user phishing-simulation performance across campaigns — how each person has been doing over time, rather than the result of a single campaign.
`ironscales_list_mailboxes` Free · Read-only	List a company's mailboxes with rich filtering — by enabled and protected state, tags, awareness level, department, title, language, name or email, or by explicit id sets.

Licensing

Tool	What it does
`ironscales_add_licensed_domains` Pro · Write	Add licensed domains to a company, so IRONSCALES will protect mailboxes on them.
`ironscales_add_licensed_domains_pd` Pro · Write	Add licensed domains through the PLANS DETAILS family — the vendor's parallel path to the same outcome as ironscales_add_licensed_domains.
`ironscales_cancel_company_licenses` Pro · Destructive	DESTRUCTIVE — MONEY AND PROTECTION.
`ironscales_delete_licensed_domains` Pro · Destructive	DESTRUCTIVE: remove licensed domains from a company.
`ironscales_delete_licensed_domains_pd` Pro · Destructive	DESTRUCTIVE: remove licensed domains through the PLANS DETAILS family — same outcome as ironscales_delete_licensed_domains, via the vendor's parallel path.
`ironscales_get_company_license_pd` Free · Read-only	Get a company's licence through the PLANS DETAILS family — IRONSCALES' second, parallel view of the same concept, which the vendor's own summaries mark 'PD'.
`ironscales_get_company_license_plan` Free · Read-only	Get a company's licence plan — the entitlement it is on and what that covers.
`ironscales_get_domain_mailbox_stats` Free · Read-only	Get mailbox counts broken down by licensed domain for a company — how many mailboxes sit on each domain, and therefore where the licence consumption actually is.
`ironscales_list_licensed_domains` Free · Read-only	List the email domains licensed for a company — the domains IRONSCALES will protect mailboxes on.
`ironscales_list_licensed_domains_pd` Free · Read-only	List a company's licensed domains through the PLANS DETAILS family — the vendor's parallel view of the same data, marked 'PD' in its own summaries.
`ironscales_update_company_license` Pro · Write	Change a company's licence — move it to a different plan or adjust its entitlement.

Integrations

Tool	What it does
`ironscales_authorize_gws_integration` Pro · Write	Complete the Google Workspace authorization handshake after a Super Admin has consented, connecting IRONSCALES to the customer's mail tenant.
`ironscales_authorize_o365_integration` Pro · Write	Complete the Microsoft 365 authorization handshake after an administrator has consented, connecting IRONSCALES to the customer's mail tenant.
`ironscales_disable_integration` Pro · Destructive	DESTRUCTIVE — ENDS MAIL PROTECTION.
`ironscales_generate_gws_consent_url` Pro · Write	Generate the Google Workspace admin-consent URL for a company — the link a customer's Super Admin visits to grant IRONSCALES access to their mail tenant.
`ironscales_generate_o365_consent_url` Pro · Write	Generate the Microsoft 365 admin-consent URL for a company — the link a customer's Global Administrator visits to grant IRONSCALES access to their mail tenant.
`ironscales_get_integration_status` Free · Read-only	Get the health of a company's mail-platform integration — whether IRONSCALES is currently connected to their Microsoft 365 or Google Workspace tenant, and in what state.

Threat Feeds

Tool	What it does
`ironscales_list_deepfake_events` Free · Read-only	List a company's deepfake SIEM events — IRONSCALES' detections of synthetic voice or video impersonation, in the shape a SIEM forwarder wants.
`ironscales_list_escalated_emails` Free · Read-only	List a company's escalated emails — individual messages raised for attention, at message granularity rather than the incident granularity of ironscales_list_incidents.

Still need help? Ask the team