# MCP tools for personalized emails

Generate and manage personalized email records through MCP without sending mail or publishing website changes.

Available on the Grow, Scale, and Pro plans.

These tools generate and store personalized email content. They do not send a message, schedule a campaign, or copy content into your email platform. Review and test the output in that platform before sending it.

## MCP email access and saved records

Every operation accepts an optional string `project_id` and follows the [shared MCP authorization and project-selection rules](https://rightmessage.com/help/mcp-authorization-reference). Invalid, missing, or inaccessible projects produce errors before an email is read or changed.

Email records live separately from website configuration. Creating, updating, and deleting them takes effect immediately in the account. There is no website draft/publication boundary, and configuration undo does not restore a deleted email.

Examples are illustrative and were not executed. Requests are `tools/call` parameters; responses are decoded content. `email_pid` is the public record ID returned by the tools, not the email's name or an address.

## `get-email-personalization-context`

Returns plain-text guidance for drafting personalized email content using the connected platform, business context, and synced audience dimensions.

**Arguments:** optional `project_id` string; no other arguments.

```json
{"name":"get-email-personalization-context","arguments":{"project_id":"123456789"}}
```

Illustrative response when no platform is connected:

```text
No email platform connected.

The team needs to connect an email platform (Kit, ActiveCampaign, HubSpot, etc.) before personalized Liquid templates can be generated.
```

With a platform connected, the response describes its templating conventions, available custom-field names, synced published dimensions, segment distribution over the last 30 days, and writing constraints. These include fallback content, avoiding nested conditions, and avoiding unsupported field references. It can read the provider's custom-field catalog. A failed field-catalog lookup can leave that part of the context empty.

The response is not a generated email and does not change provider data. It uses published audience information, not unpublished dimension changes. Do not assume every connected provider supports the same Liquid syntax.

## `list-personalized-emails`

Lists the project's email records, newest first.

**Arguments:** optional `project_id` string. There is no pagination or search argument.

```json
{"name":"list-personalized-emails","arguments":{"project_id":"123456789"}}
```

```json
[{"pid":"987654321","name":"WorkForge welcome","completed_at":"2026-10-13T12:00:00Z","created_at":"2026-10-13T11:59:00Z","updated_at":"2026-10-13T12:00:00Z"}]
```

Each item contains only `pid`, `name`, `completed_at`, `created_at`, and `updated_at`. Despite the tool's broad description, the list response does not include email bodies. An empty account returns `[]`. Read a record to retrieve its content.

## `get-personalized-email`

Reads a single stored email without regenerating it.

| Argument     | Type   | Required | Meaning                 |
| ------------ | ------ | -------- | ----------------------- |
| `project_id` | string | No       | Public project ID.      |
| `email_pid`  | string | Yes      | Public email record ID. |

```json
{"name":"get-personalized-email","arguments":{"project_id":"123456789","email_pid":"987654321"}}
```

Illustrative response, with generated content abbreviated:

```json
{"pid":"987654321","name":"WorkForge welcome","original_email":"Welcome to WorkForge.","personalized_email":"Welcome to WorkForge.","rationale":"Use a general greeting when no segment matches.","affected_segments":[],"segmentation_dimensions":"[]","instructions":"Keep the welcome concise.","completed_at":"2026-10-13T12:00:00Z","created_at":"2026-10-13T11:59:00Z","updated_at":"2026-10-13T12:00:00Z"}
```

The record returns stored `original_email`, `personalized_email`, `rationale`, `affected_segments`, `segmentation_dimensions`, and `instructions`, plus metadata and timestamps. Stored generation fields can be empty or null on an incomplete record; consumers should not assume a completed template from the record's existence alone. The current create path initializes `segmentation_dimensions` to the string `"[]"`.

Missing `email_pid` or a record outside the selected project returns an error.

## `create-personalized-email`

Creates an email record and runs AI enrichment before returning.

| Argument         | Type   | Required | Default and behavior                                          |
| ---------------- | ------ | -------- | ------------------------------------------------------------- |
| `project_id`     | string | No       | Active or eligible project.                                   |
| `name`           | string | Yes      | Initial name; generation can replace it.                      |
| `original_email` | string | Yes      | Source email text.                                            |
| `instructions`   | string | No       | Additional writing instructions; defaults to an empty string. |

```json
{"name":"create-personalized-email","arguments":{"project_id":"123456789","name":"WorkForge welcome","original_email":"Welcome to WorkForge. Plan your next project today.","instructions":"Keep the welcome concise."}}
```

Illustrative response, not a guarantee of model output:

```json
{"pid":"987654321","name":"WorkForge welcome","original_email":"Welcome to WorkForge. Plan your next project today.","personalized_email":"Welcome to WorkForge. Plan your next project today.","rationale":"Keep a clear fallback for every reader.","affected_segments":[],"instructions":"Keep the welcome concise.","completed_at":"2026-10-13T12:00:00Z","created_at":"2026-10-13T11:59:00Z"}
```

The response includes the fields shown above, not `segmentation_dimensions` or `updated_at`. Generation finishes before the call returns. There is no background generation job to poll.

This operation sends email text and context to the configured AI service and saves an email record. It does not require publication or send email. Missing required text produces an input error. Generation or storage failures return `Failed to create personalized email: ...`. A failed generation can leave a record behind. Inspect the list before repeating a failed creation.

New records use `segmentation_dimensions: "[]"` during generation. Calling `get-email-personalization-context` first does not automatically attach its dimension mappings to this record. Generation also uses business context, your instructions, and the connected provider's templating guidance. Review any generated segment references rather than assuming the tool supplied the project's complete audience catalog.

## `update-personalized-email`

Updates stored source content or the record's name. It does **not** regenerate `personalized_email`.

| Argument         | Type   | Required | Meaning                   |
| ---------------- | ------ | -------- | ------------------------- |
| `project_id`     | string | No       | Public project ID.        |
| `email_pid`      | string | Yes      | Existing email record.    |
| `name`           | string | No       | Replacement name.         |
| `original_email` | string | No       | Replacement source email. |

At least one editable non-null field is required. There are no `instructions`, `personalized_email`, or regeneration arguments.

```json
{"name":"update-personalized-email","arguments":{"project_id":"123456789","email_pid":"987654321","name":"WorkForge onboarding email"}}
```

```json
{"pid":"987654321","name":"WorkForge onboarding email","original_email":"Welcome to WorkForge.","personalized_email":"Welcome to WorkForge.","updated_at":"2026-10-13T12:30:00Z"}
```

The response includes exactly `pid`, `name`, `original_email`, `personalized_email`, and `updated_at`. This immediately overwrites the supplied fields. Missing IDs, missing editable fields, and unknown records return errors; storage failures use `Failed to update personalized email: ...`. After changing the source, the existing generated version can be out of date.

## `delete-personalized-email`

Permanently deletes one stored email record from the selected project.

**Arguments:** optional `project_id` string and required `email_pid` string.

```json
{"name":"delete-personalized-email","arguments":{"project_id":"123456789","email_pid":"987654321"}}
```

```json
{"deleted":true,"email_pid":"987654321"}
```

Deletion is immediate and destructive. It does not delete a campaign previously copied into an email platform, retract sent mail, or create a recoverable configuration draft. Missing IDs and unknown records return errors; storage failures use `Failed to delete personalized email: ...`.

For review and export steps in the dashboard, see [Create and export a personalized email](https://rightmessage.com/help/personalizing-your-emails-with-rightmessage).