# RevCent MCP Operation: `EditEmailTemplate`

This document describes the `EditEmailTemplate` MCP operation, every input field from the operation schema, and how email template Handlebars data is sourced from the selected `template_trigger`.

Sources used:
- RevCent MCP operation schema for `EditEmailTemplate`
- RevCent trigger enum description and input-data links from the Email Template schema

> Scope: This document intentionally covers only the `EditEmailTemplate` operation.

---

## Operation Summary

`EditEmailTemplate` edits a previously created RevCent Email Template using its 20-character `email_template_id`.

Unlike `CreateEmailTemplate`, this operation supports partial updates:

- `email_template_id` is required.
- Only include fields you want to modify.
- Fields omitted from the request remain unchanged.
- If an array field is provided, it updates/replaces that field.
- If `custom_arguments` is provided, it replaces the existing custom arguments array, even if empty.
- If `timing` is provided, all timing properties must be provided.
- If `custom_data` is provided, all custom data properties must be provided.
- For `filters`, only provide filter arrays you want to modify; provide an empty array to remove a specific filter.

---

## Required Fields

The `EditEmailTemplate` schema requires only:

| Field | Type | Required | Notes |
|---|---:|---:|---|
| `email_template_id` | string | Yes | 20-character Email Template ID to edit. |

All other fields are optional and should only be included when you want to modify them.

---

## Complete Input Schema Field Reference

### `email_template_id`

**Type:** `string`  
**Required:** Yes  
**Length:** 20 characters

The ID of the existing Email Template to edit.

```json
"email_template_id": "XXXXXXXXXXXXXXXXXXXX"
```

Important behavior:

- This field identifies the template being edited.
- It is the only required field.
- Do not include unrelated fields unless you intend to modify them.

---

### `name`

**Type:** `string`  
**Required:** No

The unique display name of the Email Template.

Use this to rename a template.

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "name": "Sale Success - Updated Customer Receipt"
}
```

Important behavior:

- Must be unique from other Email Template names.
- Omit this field if the name should remain unchanged.

---

### `description`

**Type:** `string`  
**Required:** No

A human-readable description of what the template is for.

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "description": "Updated receipt template for successful sales."
}
```

Recommended content:

- Trigger purpose.
- Recipient audience.
- Any important filters.
- Any required custom data or custom arguments.

---

### `enabled`

**Type:** `boolean`  
**Required:** No

Controls whether the Email Template is active and able to send SMTP messages.

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "enabled": false
}
```

Behavior:

- `true`: the template may be used to send SMTP messages when triggered.
- `false`: the template should not be used to send SMTP messages.
- Omit this field if the enabled status should remain unchanged.

---

### `smtp_profile`

**Type:** `string`  
**Required:** No  
**Length:** exactly 20 characters

The SMTP Profile ID used to send the email.

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "smtp_profile": "YYYYYYYYYYYYYYYYYYYY"
}
```

Important behavior:

- This field is the ID, not the SMTP Profile name.
- The `template_from` address should match the sender address configured in the SMTP Profile to reduce delivery issues.
- Omit this field if the SMTP Profile should remain unchanged.

---

### `template_subject`

**Type:** `string`  
**Required:** No  
**Supports Handlebars:** Yes

The subject line used when the email is sent.

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "template_subject": "Thanks for your order, {{customer.first_name}}"
}
```

How Handlebars works here:

- The subject is rendered using the same input data as the HTML body.
- Available fields depend on `template_trigger`.
- If you change `template_trigger`, you may need to update `template_subject` so its Handlebars paths match the new trigger input data.

---

### `template_from`

**Type:** `string`  
**Required:** No  
**Supports Handlebars:** Yes

The sender email address.

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "template_from": "support@example.com"
}
```

Best practices:

- Prefer a fixed sender address that matches the SMTP Profile.
- Only use Handlebars if the rendered result will always be a valid email address.
- Omit this field if the sender email should remain unchanged.

---

### `template_from_name`

**Type:** `string`  
**Required:** No  
**Supports Handlebars:** Yes

The sender display name.

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "template_from_name": "Customer Support"
}
```

Dynamic example:

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "template_from_name": "{{custom_data.brand_name}} Support"
}
```

---

### `template_to`

**Type:** `array<string>`  
**Required:** No  
**Supports Handlebars:** Yes

The primary recipients of the email. Each array item may be either a literal email address or a Handlebars expression that renders to an email address.

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "template_to": ["{{customer.email}}"]
}
```

Important behavior:

- The schema expects an array.
- Providing this field updates/replaces the template's primary recipients.
- Each item should render to a valid email address.
- Whether `{{customer.email}}` is valid depends on the trigger input data.
- For `customer_create_success`, the customer object is the input data itself, so the correct path may be `{{email}}` rather than `{{customer.email}}`.

---

### `template_to_cc`

**Type:** `array<string>`  
**Required:** No  
**Supports Handlebars:** Yes

CC recipients.

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "template_to_cc": ["orders@example.com"]
}
```

Use an empty array to clear CC recipients if supported by the API behavior for array replacement:

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "template_to_cc": []
}
```

---

### `template_to_bcc`

**Type:** `array<string>`  
**Required:** No  
**Supports Handlebars:** Yes

BCC recipients.

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "template_to_bcc": ["audit@example.com"]
}
```

Use this for internal logging, compliance, or operational recipients who should not be visible to other recipients.

---

### `template_html`

**Type:** `string`  
**Required:** No  
**Supports Handlebars:** Yes

The HTML body of the email.

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "template_html": "<p>Hello {{customer.first_name}},</p><p>Thanks for your order.</p>"
}
```

The HTML body can include:

- Standard HTML.
- Handlebars substitutions.
- Handlebars conditionals.
- Handlebars loops.
- RevCent custom helpers.
- `custom_data` values, if configured.
- `custom_arguments` values, for API/AI direct templates.

Important editing behavior:

- If you change `template_trigger`, verify that all Handlebars paths in `template_html` still exist in the new trigger's `input_data`.
- If you change `custom_data`, verify that any `{{custom_data.*}}` paths still exist.
- If you change `custom_arguments`, verify that any `{{custom_arguments.*}}` paths still exist.

---

### `template_trigger`

**Type:** `string` enum  
**Required:** No

Determines how the template is triggered and what source input data the Handlebars compiler receives.

Schema-supported enum values:

```text
no_trigger
api_direct
sale_create_success
sale_create_decline
pending_sale_no_payment
sentinel_alert_create_success
ai_memo_create_success
fraud_alert_create_success
fraud_detection_create_success
invoice_create_success
customer_create_success
pending_refund_create_success
shipping_item_created
shipping_item_shipped
shipping_item_delivered
shipping_item_voided
subscription_renew_success
subscription_renew_decline
subscription_renewal_upcoming
trial_expire_success
trial_expire_decline
trial_expire_upcoming
```

Important editing behavior:

- Omit `template_trigger` if the trigger should remain unchanged.
- If you change the trigger, review all Handlebars fields because the source `input_data` object may change.
- For example, switching from `sale_create_success` to `customer_create_success` changes customer paths from nested `{{customer.email}}` to top-level `{{email}}`.
- Switching to `api_direct` usually means replacing event-based paths with `custom_arguments` or `custom_data`.

---

### `trigger_sources_allowed`

**Type:** `array<string>`  
**Required:** No  
**Applies only to:** `shipping_item_shipped`, `shipping_item_delivered`

Restricts shipping-triggered emails based on what caused the shipment.

Allowed values:

```text
sale_create
subscription_renew
trial_expire
```

Example:

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "trigger_sources_allowed": ["sale_create"]
}
```

Behavior:

- Only applies to `shipping_item_shipped` and `shipping_item_delivered`.
- Leave empty or omit to allow all trigger sources.
- Use this when shipment emails should only be sent for shipments originating from a sale, renewal, or trial expiration.
- Omit this field if the allowed trigger sources should remain unchanged.

---

## `timing`

**Type:** `object`  
**Required:** No

Controls when the email sends relative to the trigger event.

Important edit behavior:

- If `timing` is provided, all timing properties must be provided.
- Omit `timing` entirely if timing should remain unchanged.

Schema:

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "timing": {
    "enabled": true,
    "time_unit": "hours",
    "time_value": 3,
    "time_relative": "after"
  }
}
```

### `timing.enabled`

**Type:** `boolean`

Whether timing settings are active.

- `false`: send immediately when the trigger occurs.
- `true`: use `time_unit`, `time_value`, and `time_relative`.

### `timing.time_unit`

**Type:** `string` enum

Allowed values:

```text
hours
days
weeks
months
years
```

### `timing.time_value`

**Type:** `integer`

The numeric amount of `time_unit`.

### `timing.time_relative`

**Type:** `string` enum

Allowed values:

```text
after
before
```

Behavior:

- `after`: send after the event occurs.
- `before`: only applies to predictable upcoming triggers:
  - `subscription_renewal_upcoming`
  - `trial_expire_upcoming`

Do not use timing with `api_direct`; API-direct templates are intended to send immediately when explicitly triggered.

---

## `filters`

**Type:** `object`  
**Required:** No

Filters determine whether the template should send when the trigger occurs.

Important edit behavior:

- Only provide filter arrays you want to modify.
- Provide an empty array to remove a specific filter.
- Omit `filters` entirely if filters should remain unchanged.

Schema:

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "filters": {
    "campaign": ["XXXXXXXXXXXXXXXXXXXX"],
    "product": ["XXXXXXXXXXXXXXXXXXXX"],
    "product_group": ["XXXXXXXXXXXXXXXXXXXX"],
    "third_party_shop": ["XXXXXXXXXXXXXXXXXXXX"]
  }
}
```

### `filters.campaign`

**Type:** `array<string>`

A list of 20-character Campaign IDs.

To remove the campaign filter:

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "filters": {
    "campaign": []
  }
}
```

### `filters.product`

**Type:** `array<string>`

A list of 20-character Product IDs.

### `filters.product_group`

**Type:** `array<string>`

A list of 20-character Product Group IDs.

### `filters.third_party_shop`

**Type:** `array<string>`

A list of 20-character third-party shop IDs.

---

## `custom_data`

**Type:** `object`  
**Required:** No

Adds extra data to the Handlebars input data under the `custom_data` property.

Important edit behavior:

- If `custom_data` is provided, all properties must be provided.
- Omit `custom_data` entirely if it should remain unchanged.
- If disabling custom data, provide a complete object with `enabled: false`.

Schema:

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "custom_data": {
    "enabled": true,
    "source_type": "json",
    "source_value": "{\"brand_name\":\"Example Brand\"}"
  }
}
```

### `custom_data.enabled`

**Type:** `boolean`

Enables or disables custom data.

When enabled, `custom_data` becomes available in the Handlebars render context:

```handlebars
{{custom_data.brand_name}}
```

### `custom_data.source_type`

**Type:** `string` enum

Allowed values:

```text
json
custom_function
```

### `custom_data.source_value`

**Type:** `string`

The meaning depends on `source_type`.

#### When `source_type` is `json`

`source_value` must be a stringified JSON object.

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "custom_data": {
    "enabled": true,
    "source_type": "json",
    "source_value": "{\"support_email\":\"support@example.com\",\"brand_name\":\"Example Brand\"}"
  }
}
```

Template usage:

```handlebars
<p>Need help? Email {{custom_data.support_email}}.</p>
```

#### When `source_type` is `custom_function`

`source_value` must be a 20-character Function ID.

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "custom_data": {
    "enabled": true,
    "source_type": "custom_function",
    "source_value": "XXXXXXXXXXXXXXXXXXXX"
  }
}
```

Function requirements:

- The function must have an event source of `email_template`.
- The function receives the same item details as the template input data.
- In the function, the item details are available at:

```javascript
event.data.item_details
```

- The function must return a plain JavaScript object.
- The returned object is inserted into the Handlebars input data as `custom_data`.

---

## `custom_arguments`

**Type:** `array<object>`  
**Required:** No  
**Applies primarily to:** `api_direct`

Defines argument names and descriptions that should be supplied when sending an API/AI-triggered SMTP message using this template.

Important edit behavior:

- If provided, `custom_arguments` replaces the existing custom arguments array.
- Providing an empty array removes all existing custom arguments.
- Omit `custom_arguments` entirely if they should remain unchanged.

Schema:

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "custom_arguments": [
    {
      "name": "thank_you_paragraph",
      "description": "Generate a customized thank-you paragraph based on the customer's name and purchase."
    }
  ]
}
```

Each object has:

### `custom_arguments[].name`

**Type:** `string`

The argument name. This becomes available in Handlebars as:

```handlebars
{{custom_arguments.thank_you_paragraph}}
```

### `custom_arguments[].description`

**Type:** `string`

Instructional text describing what value should be provided when the email is sent.

---

# Handlebars Data Model

## Core Rule

The Handlebars compiler receives input data based on the selected `template_trigger`.

That means this:

```handlebars
{{customer.first_name}}
```

only works when the input data contains:

```json
{
  "customer": {
    "first_name": "George"
  }
}
```

For a Customer trigger, the input data is the Customer object itself, so the first name is top-level:

```handlebars
{{first_name}}
```

not:

```handlebars
{{customer.first_name}}
```

unless the input data actually contains a nested `customer`.

When editing a template, always re-check Handlebars paths if you edit any of these fields:

- `template_trigger`
- `template_subject`
- `template_from`
- `template_from_name`
- `template_to`
- `template_to_cc`
- `template_to_bcc`
- `template_html`
- `custom_data`
- `custom_arguments`

---

## Where Handlebars Can Be Used

The schema explicitly supports Handlebars in:

- `template_subject`
- `template_from`
- `template_from_name`
- `template_to`
- `template_to_cc`
- `template_to_bcc`
- `template_html`

---

## Basic Substitution

Input data:

```json
{
  "customer": {
    "first_name": "George"
  }
}
```

Template:

```handlebars
Hello {{customer.first_name}}
```

Output:

```text
Hello George
```

---

## Conditionals

```handlebars
{{#if customer.first_name}}
  <p>Hello {{customer.first_name}},</p>
{{else}}
  <p>Hello,</p>
{{/if}}
```

---

## Iteration

If the input data contains an array, use `each`.

```handlebars
<ul>
{{#each products_detailed}}
  <li>{{name}} — {{formatCurrency total_amount}}</li>
{{/each}}
</ul>
```

---

## Additional Shortcodes

| Shortcode | Applies To | Description |
|---|---|---|
| `{{item_date}}` | All triggers | Date of the item relative to the trigger, such as sale date or renewal date. |
| `{{date_now}}` | All triggers | Current date when the email is sent. |

---

## Custom Helpers

### `formatDate`

```handlebars
{{formatDate created_date_unix 'MM/DD/YYYY' '-0500'}}
```

### `formatCurrency`

```handlebars
{{formatCurrency amount_total}}
```

### `findWhereEquals`

```handlebars
{{findWhereEquals 'metadata' 'name' 'affiliate_id' 'value'}}
```

### `math`

```handlebars
{{math 'add' shipping_amount tax_amount 'currency'}}
```

Supported operations:

- `add`
- `subtract`
- `multiply`
- `divide`

Supported output formats:

- `integer`
- `float`
- `currency`

### Type and Case Helpers

```handlebars
{{parseInt amount}}
{{parseFloat amount}}
{{toString amount}}
{{startCase customer.first_name}}
{{upperCase customer.first_name}}
{{lowerCase customer.first_name}}
```

---

# Trigger-Specific Source `input_data`

The `template_trigger` determines the source data available to Handlebars. The trigger enum description includes direct JSON example links for each supported trigger that has event data.

Use the JSON link for the selected trigger as the source of truth for Handlebars paths. For example, a Sale trigger uses the Sale JSON object, while `subscription_renewal_upcoming` uses the Subscription JSON object, not the Subscription Renewal JSON object.

| `template_trigger` | Source `input_data` | Input data JSON | Notes |
|---|---|---|---|
| `no_trigger` | None | N/A | Draft or external-process template; no event input data. |
| `api_direct` | None by default | N/A | Triggered directly by API/MCP or AI; use custom arguments/custom data unless item context is supplied when sending. |
| `sale_create_success` | sale object | [sale object](https://revcent.com/documentation/files/email_template/input_data/sale.json) | Sale created and payment succeeded. |
| `sale_create_decline` | sale object | [sale object](https://revcent.com/documentation/files/email_template/input_data/sale.json) | Sale created but all payment attempts failed due to error or decline. |
| `pending_sale_no_payment` | sale object | [sale object](https://revcent.com/documentation/files/email_template/input_data/sale.json) | Pending sale created but no payment attempt was made; abandoned-cart style trigger. |
| `sentinel_alert_create_success` | sentinel object | [sentinel object](https://revcent.com/documentation/files/email_template/input_data/sentinel.json) | Sentinel fraud detection occurred. |
| `fraud_alert_create_success` | sentinel object | [sentinel object](https://revcent.com/documentation/files/email_template/input_data/sentinel.json) | Sale was marked with a fraud alert for manual review; payment was not prevented. |
| `fraud_detection_create_success` | fraud detection object | [fraud detection object](https://revcent.com/documentation/files/email_template/input_data/fraud_detection.json) | Fraud Detection was created and payment was prevented. |
| `invoice_create_success` | invoice object | [invoice object](https://revcent.com/documentation/files/email_template/input_data/invoice.json) | Invoice was created with a unique URL. |
| `ai_memo_create_success` | AI memo object | [AI memo object](https://revcent.com/documentation/files/email_template/input_data/ai_memo.json) | AI Assistant created an AI Memo. |
| `customer_create_success` | customer object | [customer object](https://revcent.com/documentation/files/email_template/input_data/customer.json) | Customer created by customer create method, not because of a new sale. |
| `pending_refund_create_success` | pending refund object | [pending refund object](https://revcent.com/documentation/files/email_template/input_data/pending_refund.json) | Pending refund was created. |
| `shipping_item_created` | shipping object | [shipping object](https://revcent.com/documentation/files/email_template/input_data/shipping.json) | Shipment was created; useful for warehouse notifications. |
| `shipping_item_shipped` | shipping object | [shipping object](https://revcent.com/documentation/files/email_template/input_data/shipping.json) | Shipment was shipped. |
| `shipping_item_delivered` | shipping object | [shipping object](https://revcent.com/documentation/files/email_template/input_data/shipping.json) | Shipment was delivered. |
| `shipping_item_voided` | shipping object | [shipping object](https://revcent.com/documentation/files/email_template/input_data/shipping.json) | Shipment was voided. |
| `subscription_renew_success` | subscription renewal object | [subscription renewal object](https://revcent.com/documentation/files/email_template/input_data/subscription_renewal.json) | Subscription renewal succeeded. |
| `subscription_renew_decline` | subscription renewal object | [subscription renewal object](https://revcent.com/documentation/files/email_template/input_data/subscription_renewal.json) | Subscription renewal declined. |
| `subscription_renewal_upcoming` | subscription object | [subscription object](https://revcent.com/documentation/files/email_template/input_data/subscription.json) | Upcoming subscription renewal; uses subscription object, not subscription renewal. |
| `trial_expire_success` | trial object | [trial object](https://revcent.com/documentation/files/email_template/input_data/trial.json) | Trial expired successfully. |
| `trial_expire_decline` | trial object | [trial object](https://revcent.com/documentation/files/email_template/input_data/trial.json) | Trial expiration failed due to error or decline. |
| `trial_expire_upcoming` | trial object | [trial object](https://revcent.com/documentation/files/email_template/input_data/trial.json) | Upcoming trial expiration. |

## Input Data Link Reference

| Source object | URL |
|---|---|
| Sale | https://revcent.com/documentation/files/email_template/input_data/sale.json |
| Sentinel | https://revcent.com/documentation/files/email_template/input_data/sentinel.json |
| AI Memo | https://revcent.com/documentation/files/email_template/input_data/ai_memo.json |
| Fraud Detection | https://revcent.com/documentation/files/email_template/input_data/fraud_detection.json |
| Invoice | https://revcent.com/documentation/files/email_template/input_data/invoice.json |
| Customer | https://revcent.com/documentation/files/email_template/input_data/customer.json |
| Pending Refund | https://revcent.com/documentation/files/email_template/input_data/pending_refund.json |
| Shipping | https://revcent.com/documentation/files/email_template/input_data/shipping.json |
| Subscription Renewal | https://revcent.com/documentation/files/email_template/input_data/subscription_renewal.json |
| Subscription | https://revcent.com/documentation/files/email_template/input_data/subscription.json |
| Trial | https://revcent.com/documentation/files/email_template/input_data/trial.json |

---

# Trigger Notes

## Trigger: `api_direct`

### Source input data

`api_direct` templates are triggered directly via API/AI. The template does not have a fixed event item type by default.

Use:

- `custom_arguments` for values provided at send time.
- `custom_data` for static JSON or function-generated values.
- Optional item context when the SMTP message is sent with an item type and item ID.

### Recommended Handlebars

```handlebars
<p>{{custom_arguments.personalized_message}}</p>
<p>Support: {{custom_data.support_email}}</p>
```

---

## Trigger: `customer_create_success`

**Input data JSON:** [customer object](https://revcent.com/documentation/files/email_template/input_data/customer.json)

Customer fields are top-level.

Use:

```handlebars
{{first_name}}
{{last_name}}
{{email}}
```

Do not assume `{{customer.email}}` exists for this trigger.

---

## Trigger: `sale_create_success`, `sale_create_decline`, `pending_sale_no_payment`

**Input data JSON:** [sale object](https://revcent.com/documentation/files/email_template/input_data/sale.json)

These triggers use the Sale object.

Common paths:

```handlebars
{{customer.first_name}}
{{customer.email}}
{{amount_total}}
{{formatCurrency amount_total}}
```

Example:

```handlebars
<p>Hi {{customer.first_name}},</p>
<p>Total: {{formatCurrency amount_total}}</p>
```

---

## Trigger: `shipping_item_created`, `shipping_item_shipped`, `shipping_item_delivered`, `shipping_item_voided`

**Input data JSON:** [shipping object](https://revcent.com/documentation/files/email_template/input_data/shipping.json)

These triggers use the Shipping object.

Example:

```handlebars
<p>Shipment update.</p>

{{#if customer.first_name}}
<p>Customer: {{customer.first_name}} {{customer.last_name}}</p>
{{/if}}

{{#if tracking_number}}
<p>Tracking number: {{tracking_number}}</p>
{{/if}}
```

---

## Trigger: `subscription_renew_success`, `subscription_renew_decline`

**Input data JSON:** [subscription renewal object](https://revcent.com/documentation/files/email_template/input_data/subscription_renewal.json)

These triggers use the Subscription Renewal object.

Example:

```handlebars
<p>Hi {{customer.first_name}},</p>
<p>Renewal amount: {{formatCurrency amount}}</p>
```

---

## Trigger: `subscription_renewal_upcoming`

**Input data JSON:** [subscription object](https://revcent.com/documentation/files/email_template/input_data/subscription.json)

This trigger uses the Subscription object, not the Subscription Renewal object.

This trigger supports `timing.time_relative: "before"`.

Example:

```handlebars
<p>Hi {{customer.first_name}},</p>
<p>Your subscription renewal is coming up.</p>
```

---

## Trigger: `trial_expire_success`, `trial_expire_decline`, `trial_expire_upcoming`

**Input data JSON:** [trial object](https://revcent.com/documentation/files/email_template/input_data/trial.json)

These triggers use the Trial object.

`trial_expire_upcoming` supports `timing.time_relative: "before"`.

Example:

```handlebars
<p>Hi {{customer.first_name}},</p>
<p>Your trial status has changed.</p>
```

---

# EditEmailTemplate Request Examples

## Example: Rename a Template Only

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "name": "Updated Template Name"
}
```

## Example: Disable a Template

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "enabled": false
}
```

## Example: Update Subject and HTML

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "template_subject": "Your order update, {{customer.first_name}}",
  "template_html": "<p>Hi {{customer.first_name}},</p><p>Your order has been updated.</p>"
}
```

## Example: Change Trigger and Update Handlebars Paths

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "template_trigger": "customer_create_success",
  "template_to": ["{{email}}"],
  "template_subject": "Welcome, {{first_name}}",
  "template_html": "<p>Welcome {{first_name}} {{last_name}}.</p>"
}
```

## Example: Replace Custom Arguments for API Direct

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "template_trigger": "api_direct",
  "custom_arguments": [
    {
      "name": "recipient_email",
      "description": "The recipient email address."
    },
    {
      "name": "message_body",
      "description": "The full message body to send."
    }
  ],
  "template_to": ["{{custom_arguments.recipient_email}}"],
  "template_html": "<p>{{custom_arguments.message_body}}</p>"
}
```

## Example: Remove Campaign Filter

```json
{
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "filters": {
    "campaign": []
  }
}
```

---

# Output Schema

A successful `EditEmailTemplate` response returns:

```json
{
  "api_call_id": "XXXXXXXXXXXXXXXXXXXX",
  "api_call_unix": 1740000000,
  "code": 1,
  "email_template_id": "XXXXXXXXXXXXXXXXXXXX",
  "result": "..."
}
```

Fields:

| Field | Type | Description |
|---|---:|---|
| `api_call_id` | string | 20-character API call ID. |
| `api_call_unix` | integer | Unix timestamp when the API call was initiated. |
| `code` | integer | Response code. `1` indicates success. |
| `email_template_id` | string | 20-character ID of the edited Email Template. |
| `result` | string | Human-readable result message. |

---

# Implementation Checklist

Before calling `EditEmailTemplate`:

1. Confirm the `email_template_id` is the correct 20-character Email Template ID.
2. Include only fields you intend to modify.
3. If changing `template_trigger`, check the new trigger's input-data JSON.
4. If changing `template_trigger`, update all Handlebars paths in subject, recipients, and HTML as needed.
5. If providing `timing`, include all timing properties.
6. Use `before` timing only for `subscription_renewal_upcoming` or `trial_expire_upcoming`.
7. Do not use timing with `api_direct`.
8. Use `trigger_sources_allowed` only for `shipping_item_shipped` or `shipping_item_delivered`.
9. For `filters`, provide only filter arrays you want to modify; use empty arrays to remove specific filters.
10. If providing `custom_data`, include all custom data properties.
11. If providing `custom_arguments`, remember it replaces the existing custom arguments array.
12. Verify all recipient fields render to valid email addresses.


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.