Tools Reference - MailGreet

Overview

The MailGreet MCP server exposes 44 tools across 7 categories. Your API key controls which tools are available — tools/list only returns tools the key has permission to call.

Subscribers

9 tools

Campaigns

8 tools

Groups

8 tools

Webhooks

5 tools

Automations

5 tools

Forms

5 tools

Segments

4 tools

Response format

Every tool call returns a JSON-RPC result with a content array:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"success\": true, \"data\": {...}, \"meta\": {...}}"
      }
    ]
  }
}

The text field contains a JSON-encoded string with the actual data. On error, isError: true is added to the result and text contains {"error": "...", "message": "..."}.

Pagination

All list_* tools support these parameters:

Parameter	Type	Default	Max
`page`	integer	1	—
`per_page`	integer	25	100

Paginated responses include a meta block:

{
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "total": 87
  }
}

Subscribers

9 tools · Required permission: subscribers:read or subscribers:write

add_subscriber

Permission: subscribers:writeAdd a new subscriber or update an existing one by email (upsert). If the email already exists, the record is updated with the provided fields — existing custom fields not mentioned are kept.

Parameter	Type	Required	Description
`email`	string	✅	Subscriber email address
`first_name`	string	—	First name
`last_name`	string	—	Last name
`status`	string	—	`active`, `unsubscribed`, or `unconfirmed`
`groups`	string[]	—	Array of group UUIDs to add subscriber to
`custom_fields`	object	—	Key-value pairs for custom fields

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_subscriber",
    "arguments": {
      "email": "alice@example.com",
      "first_name": "Alice",
      "last_name": "Smith",
      "status": "active",
      "groups": ["a753d1f1-2cae-44b6-9ca1-7ce4380bc43f"],
      "custom_fields": { "company": "Acme Corp", "plan": "pro" }
    }
  }
}

Success response:

{
  "success": true,
  "data": {
    "id": "b812e3a4-...",
    "email": "alice@example.com",
    "first_name": "Alice",
    "last_name": "Smith",
    "status": "active",
    "created_at": "2026-03-21T10:00:00Z"
  }
}

get_subscriber

Permission: subscribers:readGet full details about a subscriber by their UUID or email.

Parameter	Type	Required	Description
`subscriber_id`	string	—	Subscriber UUID
`email`	string	—	Subscriber email

One of subscriber_id or email must be provided.

update_subscriber

Permission: subscribers:writeUpdate an existing subscriber’s fields. Only provided fields are changed — others are untouched.

Parameter	Type	Required	Description
`subscriber_id`	string	✅	Subscriber UUID
`email`	string	—	New email address
`first_name`	string	—	First name
`last_name`	string	—	Last name
`status`	string	—	`active`, `unsubscribed`, or `unconfirmed`
`custom_fields`	object	—	Fields to update (merged, not replaced)

list_subscribers

Permission: subscribers:readList subscribers with optional filtering. Returns paginated results.

Parameter	Type	Required	Description
`status`	string	—	`active`, `unsubscribed`, `bounced`, `junk`, `unconfirmed`
`search`	string	—	Search by email or name
`group_id`	string	—	Filter by group UUID
`page`	integer	—	Page number (default: 1)
`per_page`	integer	—	Per page (default: 25, max: 100)

get_subscriber_activity

Permission: subscribers:readGet the activity history for a subscriber: email opens, clicks, sends, unsubscribes, and more.

Parameter	Type	Required	Description
`subscriber_id`	string	✅	Subscriber UUID
`page`	integer	—	Page number
`per_page`	integer	—	Per page

get_subscriber_count

Permission: subscribers:readGet the total count of subscribers, optionally filtered by status.

Parameter	Type	Required	Description
`status`	string	—	`active`, `unsubscribed`, `bounced`, `junk`, `unconfirmed`

Success response:

{
  "success": true,
  "data": {
    "total": 22,
    "status": "all"
  }
}

delete_subscriber

Permission: subscribers:writeDelete a subscriber. Historical activity data (opens, clicks) is retained. The subscriber can re-subscribe later.

Parameter	Type	Required	Description
`subscriber_id`	string	✅	Subscriber UUID

forget_subscriber

Permission: subscribers:write

GDPR right-to-erasure tool. Completely removes a subscriber and all associated data including activity history, custom fields, and group memberships. This action is irreversible.

Parameter	Type	Required	Description
`subscriber_id`	string	✅	Subscriber UUID

get_single_import

Permission: subscribers:readGet the status and details of a subscriber import job created via import_subscribers_to_group.

Parameter	Type	Required	Description
`import_id`	string	✅	Import job ID

Campaigns

8 tools · Required permission: campaigns:read or campaigns:write

create_campaign

Permission: campaigns:writeCreate a new email campaign in draft status.

Parameter	Type	Required	Description
`name`	string	✅	Campaign name (internal)
`subject`	string	✅	Email subject line
`from_name`	string	—	Sender display name
`from_email`	string	—	Sender email address
`type`	string	—	`regular` (default), `ab`, or `resend`
`content_html`	string	—	Full HTML body
`groups`	string[]	—	Group UUIDs to send to
`segments`	string[]	—	Segment UUIDs to send to

get_campaign

Permission: campaigns:readGet full details about a campaign including delivery stats.

Parameter	Type	Required	Description
`campaign_id`	string	✅	Campaign UUID

list_campaigns

Permission: campaigns:readList campaigns with optional filtering.

Parameter	Type	Required	Description
`status`	string	—	`draft`, `scheduled`, `sending`, `sent`, `cancelled`
`type`	string	—	`regular`, `ab`, `resend`
`page`	integer	—	Page number
`per_page`	integer	—	Per page

update_campaign

Permission: campaigns:writeUpdate a campaign’s details. Only draft campaigns can be updated.

Parameter	Type	Required	Description
`campaign_id`	string	✅	Campaign UUID
`name`	string	—	Campaign name
`subject`	string	—	Subject line
`from_name`	string	—	Sender name
`from_email`	string	—	Sender email
`content_html`	string	—	HTML content

delete_campaign

Permission: campaigns:writeDelete a campaign. Only draft or cancelled campaigns can be deleted.

Parameter	Type	Required	Description
`campaign_id`	string	✅	Campaign UUID

schedule_campaign

Permission: campaigns:writeSchedule a draft campaign to send at a specific future time.

Parameter	Type	Required	Description
`campaign_id`	string	✅	Campaign UUID
`scheduled_at`	string	✅	ISO 8601 datetime — e.g. `2026-12-25T09:00:00Z`

cancel_campaign

Permission: campaigns:writeCancel a scheduled campaign, returning it to draft status.

Parameter	Type	Required	Description
`campaign_id`	string	✅	Campaign UUID

get_campaign_subscribers

Permission: campaigns:readGet the list of subscribers who received a specific campaign.

Parameter	Type	Required	Description
`campaign_id`	string	✅	Campaign UUID
`page`	integer	—	Page number
`per_page`	integer	—	Per page

Groups

8 tools · Required permission: groups:read or groups:write

list_groups

Permission: groups:readList all subscriber groups.

Parameter	Type	Required	Description
`page`	integer	—	Page number
`per_page`	integer	—	Per page

create_group

Permission: groups:writeCreate a new subscriber group.

Parameter	Type	Required	Description
`name`	string	✅	Group name

Success response:

{
  "success": true,
  "data": {
    "id": "a753d1f1-2cae-44b6-9ca1-7ce4380bc43f",
    "name": "VIP Customers",
    "subscribers_count": 0,
    "created_at": "2026-03-21T10:00:00Z"
  }
}

update_group

Permission: groups:writeRename a subscriber group.

Parameter	Type	Required	Description
`group_id`	string	✅	Group UUID
`name`	string	✅	New name

delete_group

Permission: groups:writeDelete a group. Subscribers in the group are not deleted — only their group membership is removed.

Parameter	Type	Required	Description
`group_id`	string	✅	Group UUID

get_group_subscribers

Permission: groups:readGet all subscribers in a group.

Parameter	Type	Required	Description
`group_id`	string	✅	Group UUID
`page`	integer	—	Page number
`per_page`	integer	—	Per page

assign_subscriber_to_group

Permission: subscribers:writeAdd a subscriber to a group.

Parameter	Type	Required	Description
`subscriber_id`	string	✅	Subscriber UUID
`group_id`	string	✅	Group UUID

unassign_subscriber_from_group

Permission: subscribers:writeRemove a subscriber from a group. The subscriber record is not deleted.

Parameter	Type	Required	Description
`subscriber_id`	string	✅	Subscriber UUID
`group_id`	string	✅	Group UUID

import_subscribers_to_group

Permission: subscribers:writeBulk upsert up to 1,000 subscribers into a group per call. Creates new subscribers if the email doesn’t exist, or updates existing ones.

Parameter	Type	Required	Description
`group_id`	string	✅	Group UUID
`subscribers`	array	✅	Array of subscriber objects (see below)

Each subscriber object in the array:

{
  "email": "bob@example.com",
  "first_name": "Bob",
  "last_name": "Jones",
  "custom_fields": { "plan": "starter" }
}

Webhooks

5 tools · Required permission: webhooks:read or webhooks:write

list_webhooks

Permission: webhooks:readList all configured webhook endpoints.

Parameter	Type	Required	Description
`page`	integer	—	Page number
`per_page`	integer	—	Per page

get_webhook

Permission: webhooks:readGet details of a specific webhook.

Parameter	Type	Required	Description
`webhook_id`	string	✅	Webhook UUID

create_webhook

Permission: webhooks:writeCreate a new webhook endpoint. MailGreet will POST to the provided URL when selected events occur.

Parameter	Type	Required	Description
`url`	string	✅	Endpoint URL to receive POST requests
`name`	string	—	Friendly name
`events`	string[]	—	Array of event types to subscribe to
`all_events`	boolean	—	Subscribe to all events (overrides `events` array)

Available event types:

email.delivery.sent · email.delivery.opened · email.delivery.clicked
email.delivery.bounced · email.delivery.complained · email.delivery.unsubscribed
api_email.sent · api_email.delivered · api_email.opened · api_email.clicked
api_email.bounced · api_email.failed

update_webhook

Permission: webhooks:writeUpdate a webhook’s URL, events, or enabled status.

Parameter	Type	Required	Description
`webhook_id`	string	✅	Webhook UUID
`name`	string	—	Webhook name
`url`	string	—	New URL
`events`	string[]	—	New events list
`is_active`	boolean	—	`true` to enable, `false` to disable

delete_webhook

Permission: webhooks:writeDelete a webhook endpoint permanently.

Parameter	Type	Required	Description
`webhook_id`	string	✅	Webhook UUID

Automations

5 tools · Required permission: automations:read or automations:write

list_automations

Permission: automations:readList all automations.

Parameter	Type	Required	Description
`status`	string	—	`active`, `draft`, `disabled`
`enabled`	boolean	—	Filter by enabled state
`search`	string	—	Search by name
`page`	integer	—	Page number
`per_page`	integer	—	Per page

get_automation

Permission: automations:readGet details about an automation including its trigger configuration and workflow steps.

Parameter	Type	Required	Description
`automation_id`	string	✅	Automation UUID

get_automation_activity

Permission: automations:readGet subscriber activity within an automation — who entered, who completed, who is currently active.

Parameter	Type	Required	Description
`automation_id`	string	✅	Automation UUID
`status`	string	—	`active`, `completed`, `cancelled`, `failed`
`page`	integer	—	Page number
`per_page`	integer	—	Per page

create_automation

Permission: automations:writeCreate a new automation in draft status.

Parameter	Type	Required	Description
`name`	string	✅	Automation name
`trigger_type`	string	—	Trigger type (see below)
`trigger_config`	object	—	Trigger configuration object
`description`	string	—	Optional description

Available trigger types: subscriber_joins_group · completes_form · joins_segment · clicks_link · updates_field · event_anniversary · exact_date · api_called

delete_automation

Permission: automations:writeDelete an automation and all related steps, triggers, and subscriber history.

Parameter	Type	Required	Description
`automation_id`	string	✅	Automation UUID

Forms

5 tools · Required permission: forms:read or forms:write

list_forms

Permission: forms:readList all signup forms.

Parameter	Type	Required	Description
`type`	string	—	`popup`, `embedded`, or `promotion`
`page`	integer	—	Page number
`per_page`	integer	—	Per page

get_form

Permission: forms:readGet detailed information about a specific form.

Parameter	Type	Required	Description
`form_id`	string	✅	Form UUID

update_form

Permission: forms:writeUpdate a form’s name.

Parameter	Type	Required	Description
`form_id`	string	✅	Form UUID
`name`	string	✅	New form name

delete_form

Permission: forms:writeDelete a form permanently.

Parameter	Type	Required	Description
`form_id`	string	✅	Form UUID

get_form_subscribers

Permission: forms:readGet the list of subscribers who signed up through a specific form.

Parameter	Type	Required	Description
`form_id`	string	✅	Form UUID
`page`	integer	—	Page number
`per_page`	integer	—	Per page

Segments

4 tools · Required permission: subscribers:read or subscribers:write

Segments use subscriber scopes (not a dedicated segments:* scope) because segments are a filtered view over subscriber data.

list_segments

Permission: subscribers:readList all subscriber segments with their subscriber counts.

Parameter	Type	Required	Description
`page`	integer	—	Page number
`per_page`	integer	—	Per page

get_subscribers_in_segment

Permission: subscribers:readGet subscribers matching a segment’s filter criteria.

Parameter	Type	Required	Description
`segment_id`	string	✅	Segment UUID
`status`	string	—	`active`, `unsubscribed`, `bounced`, `junk`
`page`	integer	—	Page number
`per_page`	integer	—	Per page

update_segment

Permission: subscribers:writeRename a segment.

Parameter	Type	Required	Description
`segment_id`	string	✅	Segment UUID
`name`	string	✅	New segment name

delete_segment

Permission: subscribers:writeDelete a segment. Subscribers are not affected.

Parameter	Type	Required	Description
`segment_id`	string	✅	Segment UUID

All tools at a glance

Tool	Category	Required Permission
`add_subscriber`	Subscribers	`subscribers:write`
`get_subscriber`	Subscribers	`subscribers:read`
`update_subscriber`	Subscribers	`subscribers:write`
`list_subscribers`	Subscribers	`subscribers:read`
`get_subscriber_activity`	Subscribers	`subscribers:read`
`get_subscriber_count`	Subscribers	`subscribers:read`
`delete_subscriber`	Subscribers	`subscribers:write`
`forget_subscriber`	Subscribers	`subscribers:write`
`get_single_import`	Subscribers	`subscribers:read`
`create_campaign`	Campaigns	`campaigns:write`
`get_campaign`	Campaigns	`campaigns:read`
`list_campaigns`	Campaigns	`campaigns:read`
`update_campaign`	Campaigns	`campaigns:write`
`delete_campaign`	Campaigns	`campaigns:write`
`schedule_campaign`	Campaigns	`campaigns:write`
`cancel_campaign`	Campaigns	`campaigns:write`
`get_campaign_subscribers`	Campaigns	`campaigns:read`
`list_groups`	Groups	`groups:read`
`create_group`	Groups	`groups:write`
`update_group`	Groups	`groups:write`
`delete_group`	Groups	`groups:write`
`get_group_subscribers`	Groups	`groups:read`
`assign_subscriber_to_group`	Groups	`subscribers:write`
`unassign_subscriber_from_group`	Groups	`subscribers:write`
`import_subscribers_to_group`	Groups	`subscribers:write`
`list_webhooks`	Webhooks	`webhooks:read`
`get_webhook`	Webhooks	`webhooks:read`
`create_webhook`	Webhooks	`webhooks:write`
`update_webhook`	Webhooks	`webhooks:write`
`delete_webhook`	Webhooks	`webhooks:write`
`list_automations`	Automations	`automations:read`
`get_automation`	Automations	`automations:read`
`get_automation_activity`	Automations	`automations:read`
`create_automation`	Automations	`automations:write`
`delete_automation`	Automations	`automations:write`
`list_forms`	Forms	`forms:read`
`get_form`	Forms	`forms:read`
`update_form`	Forms	`forms:write`
`delete_form`	Forms	`forms:write`
`get_form_subscribers`	Forms	`forms:read`
`list_segments`	Segments	`subscribers:read`
`get_subscribers_in_segment`	Segments	`subscribers:read`
`update_segment`	Segments	`subscribers:write`
`delete_segment`	Segments	`subscribers:write`

​Overview

Subscribers

Campaigns

Groups

Webhooks

Automations

Forms

Segments

​Response format

​Pagination

​Subscribers

​Campaigns

​Groups

​Webhooks

​Automations

​Forms

​Segments

​All tools at a glance

Overview

Response format

Pagination

Subscribers

Campaigns

Groups

Webhooks

Automations

Forms

Segments

All tools at a glance