Docs MCP Server Tools Reference

Tools Reference

Complete input/output reference for all 16 Brixus MCP tools — sending, tracking, templates, and campaigns.

brixus_send_email

Send a transactional email using a starter template. Delivery is asynchronous — the tool returns immediately with a messageId and status "queued".

This tool has side effects. Each call dispatches a real email. Without an idempotency key, calling it twice sends two emails.

Inputs

Parameter		Type	Description
`to`	required	string	Recipient email address. One recipient per call.
`starter_template`	required	string	Snake_case template slug (e.g. `welcome`, `password_reset`, `otp`). Use `brixus_list_starter_templates` to find valid values.
`variables`	optional	object	Key-value pairs injected into the template. Each template documents its expected variables.
`from_name`	optional	string	Sender display name (max 1024 chars). Defaults to the configured account sender name.

Output

{
  "messageId": "fd92bd3f-969a-4ff6-87dc-a8b0a16e0297",
  "status": "queued",
  "from": "noreply@brixus365.dev"
}

On free keys, from is always noreply@brixus365.dev. Paid plans use your verified sending domain.

More than templates. brixus_send_email supports three content modes — starter_template, template_id (a custom saved template), or raw html (with a required subject). It also accepts cc, bcc, reply_to, file attachments (up to 10 files, 10 MB total), scheduled_at (ISO 8601, up to 30 days out), and an idempotency_key for safe retries.

Recommended agent flow

Call brixus_list_starter_templates to find a template whose variables match the data you have.
Optionally call brixus_preview_starter_template to confirm the rendered content looks right.
Call brixus_send_email with to, starter_template, and variables.

brixus_list_starter_templates

Returns all starter templates available to your account. Read-only — no side effects.

Inputs

None.

Output

{
  "templates": [
    {
      "slug": "welcome",
      "name": "Welcome email",
      "description": "Post-signup welcome with a three-step starter checklist.",
      "variables": ["name", "app_name"]
    },
    {
      "slug": "password_reset",
      "name": "Password reset link",
      "description": "Time-limited link for the user to choose a new password after a reset request.",
      "variables": ["reset_url", "expiry_minutes"]
    }
  ]
}

Use slug as the starter_template value in brixus_send_email and brixus_preview_starter_template. The variables array lists the keys each template expects. See Available templates for the full list.

brixus_preview_starter_template

Renders a starter template against a set of variables and returns the subject line and HTML. Read-only — no email is sent.

Variables you supply are merged on top of the template’s built-in sample values, so you only need to pass the ones you want to override.

The rendered HTML can be large. When it exceeds ~25 kB the tool returns a truncated version with a truncated: true marker and a note pointing to the Brixus dashboard for the full render.

Inputs

Parameter		Type	Description
`slug`	required	string	Starter template slug from `brixus_list_starter_templates`.
`variables`	optional	object	Variable overrides. Omit to render with the template’s default sample values.

Output

{
  "slug": "welcome",
  "subject": "Welcome to Acme",
  "html": "<!DOCTYPE html>...",
  "sampleVariables": {
    "name": "Alice",
    "app_name": "Acme"
  }
}

sampleVariables reflects the effective merged values used during rendering.

brixus_send_email_batch

Send up to 100 transactional emails in a single call. Each message in messages follows the same shape as brixus_send_email — one content mode plus recipients and optional fields.

This tool has side effects. Every message dispatches a real email. Supply an idempotency_key per message to retry a batch safely.

Inputs

Parameter		Type	Description
`messages`	required	array	1–100 message objects. Each needs `to` and exactly one content mode (`starter_template`, `template_id`, or `html`), and accepts the same optional fields as `brixus_send_email` (`cc`, `bcc`, `reply_to`, `variables`, `attachments`, `scheduled_at`, `idempotency_key`).

Limits: max 100 messages per batch; max 1,000 recipients total across all messages.

Output

Returns a summary with queued and failed counts plus a per-message result list, so you can see exactly which messages were accepted.

brixus_cancel_email

Cancel a scheduled email before it is dispatched. Only emails in scheduled status can be cancelled — attempting to cancel an already-sent message returns an error.

Inputs

Parameter		Type	Description
`message_id`	required	string	ID of the scheduled email to cancel (e.g. `msg_live_01J…`).

brixus_get_email

Retrieve the current status and metadata for one transactional email. Read-only.

Inputs

Parameter		Type	Description
`message_id`	required	string	Message ID returned by `brixus_send_email` or `brixus_send_email_batch`.

Output

Delivery status (queued → sent → delivered / bounced / failed), timestamps, recipient, subject, and a failure reason when applicable.

brixus_list_emails

List sent and queued emails with optional filters. Read-only and paginated.

Inputs

Parameter		Type	Description
`status`	optional	string	Filter by delivery status: `queued`, `scheduled`, `sent`, `delivered`, `bounced`, `failed`, `cancelled`.
`from` / `to`	optional	string	ISO 8601 datetimes bounding when messages were created.
`skip` / `limit`	optional	integer	Pagination. `limit` is 1–100 (default 50); `skip` defaults to 0.
`sort_by`	optional	string	One of `created_at` (default), `sent_at`, `status`.

brixus_get_email_analytics

Aggregated sending analytics for a time window: sent, delivered, opened, clicked, bounced, and failed. Read-only.

Inputs

Parameter		Type	Description
`from`	required	string	ISO 8601 start of the analytics window.
`to`	required	string	ISO 8601 end of the analytics window.
`bucket`	optional	string	`hour` for an intraday breakdown or `day` for daily rollups (default).

Output

Per-bucket data plus overall totals for the window.

brixus_get_api_key_info

Return your key’s tier, usage counters, rate limits, and allowed content modes. No scope required — useful for checking remaining quota before a send.

Inputs

None.

Output

{
  "tier": "free",
  "usageToday": 12,
  "usageMonth": 340,
  "limits": { "daily": 300, "monthly": 9000, "ratePerMinute": 10 },
  "allowedModes": ["starter_template", "template_id", "html"]
}

Template builder tools

Beyond the read-only starter-template tools above, four tools let an agent build and manage your own saved templates. These require the templates:write scope, which is included on every plan — including Free. Call brixus_get_email_component_schema first to learn the template structure (root, content, zones) and the available email components.

brixus_create_email_template — create a new template from structured template data. Returns the created template ID and an editor URL for visual refinement.
brixus_update_email_template — update an existing saved template.
brixus_get_email_template — fetch a saved template by ID.
brixus_get_email_component_schema — inspect the editor component schema — the building blocks a template can use.

Campaign tools

Tools for marketing campaigns. These require the marketing:read or marketing:write scope and are available on paid plans (Standard and Enterprise).

brixus_list_campaigns — browse and filter campaigns by status, channel, or name; paginated and sortable. Requires marketing:read or marketing:write.
brixus_get_campaign — full details for one campaign by ID (status, channel, subject, recipient and sent counts, schedule). Requires marketing:read or marketing:write.
brixus_send_campaign_test — send a test of a campaign to 1–3 addresses. Renders with smart variable defaults and does not affect campaign statistics. Requires marketing:write.