Action Plugins

Let the Atlas agent send emails and create JIRA tickets with approval-gated actions.

Action plugins give the agent the ability to perform write operations. All actions go through the approval framework -- the agent proposes an action, and the user must approve it before execution.

Email

The email action plugin lets the Atlas agent send email reports to stakeholders via the Resend API. It supports HTML-formatted emails, multiple recipients, and optional domain allowlisting to restrict who can receive reports.

Prerequisites

@atlas/plugin-email-action -- the plugin package (workspace dependency)
A Resend API key
A verified sending domain in Resend (or use the default notifications.useatlas.dev)

Configuration

Option	Type	Default	Description
`resendApiKey`	`string`	--	Resend API key. Required.
`allowedDomains`	`string[]`	--	Optional domain allowlist. When set, only recipients with email addresses matching these domains are permitted.
`fromAddress`	`string`	`"Atlas <atlas@notifications.useatlas.dev>"`	Sender address for outgoing emails.
`approvalMode`	`"auto" \| "manual" \| "admin-only"`	`"admin-only"`	Who can approve email sends.

Usage

import { defineConfig } from "@atlas/api/lib/config";
import { emailPlugin } from "@atlas/plugin-email-action";

export default defineConfig({
  plugins: [
    emailPlugin({
      resendApiKey: process.env.RESEND_API_KEY!,
      allowedDomains: ["myco.com"],
      fromAddress: "Atlas <atlas@myco.com>",
    }),
  ],
});

Action details

Property	Value
Action name	`sendEmailReport`
Action type	`email:send`
Reversible	No
Default approval	`admin-only` (configurable via `approvalMode`)
Required credentials	`resendApiKey`

The agent tool accepts the following parameters:

Parameter	Type	Description
`to`	`string \| string[]`	Recipient email address(es).
`subject`	`string`	Email subject line.
`body`	`string`	Email body in HTML format.

Domain allowlisting

When allowedDomains is configured, the plugin validates every recipient's email domain before sending. Recipients with domains not in the allowlist are blocked, and the tool returns an error listing the blocked addresses and the allowed domains.

The domain check handles display-name format addresses (e.g., "User <user@company.com>") by extracting the domain from inside angle brackets.

The health check verifies that the Resend API key is valid by calling the Resend domains endpoint. If the API returns a non-200 status, the plugin reports as unhealthy.

JIRA

The JIRA action plugin lets the Atlas agent create JIRA issues based on analysis findings. When the agent identifies something actionable -- an anomaly, a data quality issue, a trend worth tracking -- it can propose creating a ticket. The user reviews the proposed ticket in the chat UI and approves or rejects it before anything is created.

Prerequisites

@atlas/plugin-jira-action -- the plugin package (workspace dependency)
A JIRA Cloud instance (Atlassian)
A JIRA API token (generate one here)
The email address associated with the API token

Configuration

Option	Type	Default	Description
`host`	`string`	--	JIRA instance URL (e.g., `"https://myco.atlassian.net"`). Must start with `https://` or `http://`. Required.
`email`	`string`	--	Email address for JIRA API authentication (Basic auth). Required.
`apiToken`	`string`	--	JIRA API token. Required.
`projectKey`	`string`	--	Default JIRA project key (e.g., `"ENG"`). Must be uppercase alphanumeric. Required.
`labels`	`string[]`	--	Optional labels applied to every created issue.

Usage

import { defineConfig } from "@atlas/api/lib/config";
import { jiraPlugin } from "@atlas/plugin-jira-action";

export default defineConfig({
  plugins: [
    jiraPlugin({
      host: "https://myco.atlassian.net",
      email: process.env.JIRA_EMAIL!,
      apiToken: process.env.JIRA_API_TOKEN!,
      projectKey: "ENG",
      labels: ["atlas-generated"],
    }),
  ],
});

Action details

Property	Value
Action name	`createJiraTicket`
Action type	`jira:create`
Reversible	Yes
Default approval	`manual`
Required credentials	`host`, `email`, `apiToken`

The agent tool accepts the following parameters:

Parameter	Type	Description
`summary`	`string`	Issue summary / title (max 255 characters).
`description`	`string`	Detailed issue description. Converted to Atlassian Document Format (ADF) automatically.
`project`	`string` (optional)	JIRA project key override. Defaults to the `projectKey` from plugin config.
`labels`	`string[]` (optional)	Labels for this specific issue. Falls back to the plugin-level `labels` config if not specified.

How it works

The agent calls createJiraTicket with a summary and description
The user sees an approval card in the chat UI
On approval, the plugin calls the JIRA REST API v3 to create a Task-type issue
Plain text descriptions are automatically converted to Atlassian Document Format (ADF), which JIRA v3 requires
The tool returns the issue key (e.g., ENG-123) and a browse URL

The health check verifies JIRA connectivity by calling the /rest/api/3/myself endpoint with the configured credentials. If authentication fails or the instance is unreachable, the plugin reports as unhealthy.

Never commit JIRA credentials to version control. Use environment variables in atlas.config.ts and add .env to .gitignore.

On this page