# RevCent MCP Guide: `SendSMTPMessage`

AI/MCP-focused guide for sending an SMTP Message in RevCent.

---

## Operation Summary

Operation:

```text
SendSMTPMessage
```

Title:

```text
Send A SMTP Message
```

Purpose:

```text
Send an SMTP Message using an Email Template ID.
```

`SendSMTPMessage` sends an email from an existing Email Template. The Email Template determines the subject, sender, HTML body, SMTP Profile, predefined recipients, shortcodes, and any custom arguments.

---

## Critical Safety Rule

Do not call `SendSMTPMessage` unless the user explicitly told AI/MCP to send an email, or an external no-human workflow has explicit authorization to send the email.

Important:

```text
Do not send a SMTP message unless explicitly told to do so by the user.
```

Sending email is an external communication. Treat it as an action that can affect customers, staff, vendors, and support workflows.

---

## Related Documentation

| Guide | Link |
|---|---|
| SMTP Messages Overview | `https://revcent.com/documentation/markdown/operation/OverviewSMTPMessage.md` |
| SMTP Profile Overview | `https://revcent.com/documentation/markdown/operation/OverviewSMTPProfile.md` |
| Email Template Overview | `https://revcent.com/documentation/markdown/operation/OverviewEmailTemplate.md` |
| CreateEmailTemplate | `https://revcent.com/documentation/markdown/operation/CreateEmailTemplate.md` |
| EditEmailTemplate | `https://revcent.com/documentation/markdown/operation/EditEmailTemplate.md` |
| GetEmailTemplate | `https://revcent.com/documentation/markdown/operation/GetEmailTemplate.md` |
| GetEmailTemplates | `https://revcent.com/documentation/markdown/operation/GetEmailTemplates.md` |

---

## Required Field

| Field | Type | Required | Description |
|---|---:|---:|---|
| `email_template_id` | string | Yes | 20-character Email Template ID used to send the SMTP Message. |

If the Email Template ID is unknown or invalid:

```text
Use GetEmailTemplates to find the appropriate Email Template.
```

Then use:

```text
GetEmailTemplate
```

to retrieve and review the full template before sending.

---

## Optional Fields

| Field | Type | Description |
|---|---:|---|
| `to` | array<string> | Additional TO recipients. Template-defined recipients are not overwritten and are de-duplicated. |
| `cc` | array<string> | Additional CC recipients. Template-defined CC recipients are not overwritten and are de-duplicated. |
| `bcc` | array<string> | Additional BCC recipients. Template-defined BCC recipients are not overwritten and are de-duplicated. |
| `item_type` | string | Related RevCent item type. |
| `item_id` | string | 20-character ID of the related item. |
| `custom_arguments` | array<object> | Values required by the selected Email Template's `custom_arguments` array. |

---

## Supported `item_type` Values

Allowed `item_type` values:

```text
sale
customer
product_sale
shipping
subscription
subscription_renewal
salvage_transaction
transaction
chargeback
fraud_detection
```

Example:

```json
{
  "email_template_id": "EEEEEEEEEEEEEEEEEEEE",
  "item_type": "shipping",
  "item_id": "SSSSSSSSSSSSSSSSSSSS"
}
```

---

## Email Template Requirement

Only Email Templates with:

```text
template_trigger = api_direct
```

can be sent directly using `SendSMTPMessage`.

Before sending, AI/MCP should verify:

```text
template exists
template is enabled
template_trigger is api_direct
SMTP Profile is attached
recipients are correct
custom arguments are complete
```

Use:

```text
GetEmailTemplate
```

before sending.

---

## Recipient Behavior

`to`, `cc`, and `bcc` are optional.

The Email Template may already define recipients.

Important behavior:

```text
Template-defined recipients are not overwritten by SendSMTPMessage recipients.
Recipients are de-duplicated.
```

AI/MCP should not assume that providing `to` replaces template recipients.

---

## Custom Arguments

Some `api_direct` Email Templates define `custom_arguments`.

Each custom argument has:

| Field | Meaning |
|---|---|
| `name` | Name that must be provided in `SendSMTPMessage.custom_arguments`. |
| `description` | Instruction for what value AI/MCP should infer or provide. |

Before sending with custom arguments:

```text
1. GetEmailTemplate.
2. Review custom_arguments.
3. Read each custom argument description.
4. Infer or obtain each value.
5. Provide name/value pairs in SendSMTPMessage.custom_arguments.
```

Schema shape:

```json
{
  "custom_arguments": [
    {
      "name": "thank_you_paragraph",
      "value": "Thank you for your order, Sarah. We appreciate your business."
    }
  ]
}
```

Important:

```text
The custom argument name should match the name from the Email Template's custom_arguments array.
```

---

## Item-Based Custom Argument Workflow

If sending with `item_type` and `item_id`, and the Email Template has custom arguments:

```text
1. Get the details of the related item if not already available.
2. Review the Email Template custom_arguments array.
3. Read each custom argument description.
4. Infer the value using the item details and the argument description.
5. Send the SMTP Message with the inferred custom_arguments.
```

Example:

```text
Template custom argument:
name = shipment_summary
description = Generate a short customer-friendly summary of the shipment status and tracking number.

item_type = shipping
item_id = SSSSSSSSSSSSSSSSSSSS

AI/MCP should retrieve the shipping item, then infer shipment_summary from the shipping details.
```

Do not guess values if the required item details are missing.

---

## Input Examples

### Minimal Send

Use only when the Email Template already defines all recipients and requires no custom arguments.

```json
{
  "email_template_id": "EEEEEEEEEEEEEEEEEEEE"
}
```

### Send to Additional Recipient

```json
{
  "email_template_id": "EEEEEEEEEEEEEEEEEEEE",
  "to": [
    "customer@example.com"
  ]
}
```

### Send with Item Context

```json
{
  "email_template_id": "EEEEEEEEEEEEEEEEEEEE",
  "item_type": "sale",
  "item_id": "SSSSSSSSSSSSSSSSSSSS"
}
```

### Send with Custom Arguments

```json
{
  "email_template_id": "EEEEEEEEEEEEEEEEEEEE",
  "to": [
    "customer@example.com"
  ],
  "custom_arguments": [
    {
      "name": "custom_message",
      "value": "Thank you for reaching out. We reviewed your order and attached the latest shipment details."
    }
  ]
}
```

### Send with Item Context and Custom Arguments

```json
{
  "email_template_id": "EEEEEEEEEEEEEEEEEEEE",
  "item_type": "shipping",
  "item_id": "SSSSSSSSSSSSSSSSSSSS",
  "custom_arguments": [
    {
      "name": "shipment_summary",
      "value": "Your shipment has shipped and tracking is now available."
    }
  ]
}
```

---

## Output Schema

Successful output can include:

| Field | Description |
|---|---|
| `api_call_id` | 20-character API call ID. |
| `api_call_unix` | Unix timestamp when the API call was initiated. |
| `code` | API response code. `1` indicates success. |
| `smtp_message_id` | 20-character SMTP Message ID. |
| `result` | Result message. |

---

## Recommended AI/MCP Workflow

```text
User explicitly asks to send an email
    ↓
Identify the correct Email Template
    ↓
If template ID is unknown/invalid, use GetEmailTemplates
    ↓
Use GetEmailTemplate
    ↓
Verify enabled = true
    ↓
Verify template_trigger = api_direct
    ↓
Review template recipients
    ↓
Review custom_arguments
    ↓
If item_type/item_id are used, retrieve the related item
    ↓
Infer/provide required custom argument values
    ↓
Call SendSMTPMessage
    ↓
Return smtp_message_id and result
```

---

## When to Use

Use `SendSMTPMessage` when:

- the user explicitly asks to send a direct email,
- an approved external workflow needs to send a direct template-backed email,
- an Email Template has `template_trigger = api_direct`,
- the correct recipients and custom arguments are known,
- the message should be sent now.

---

## When Not to Use

Do not use `SendSMTPMessage` when:

- the user has not explicitly asked to send an email,
- the Email Template is not `api_direct`,
- the Email Template is disabled,
- required custom arguments are missing,
- recipients are ambiguous,
- the message should be triggered automatically by a RevCent event instead,
- the task is only to create or preview a template,
- the user is asking for reporting or message history.

---

## Handling Unknown or Invalid Email Template ID

If the user does not provide an Email Template ID, or the provided ID is invalid:

```text
Use GetEmailTemplates automatically.
```

Then:

```text
Find the appropriate Email Template.
Use GetEmailTemplate to review full details.
Confirm it is the intended template if a human is in the loop and ambiguity exists.
```

Do not invent an Email Template ID.

---

## Customer-Facing Verification

If sending a customer-facing email related to an item, AI/MCP should verify the recipient is appropriate for that item.

Examples:

| Item Type | Verify Before Sending |
|---|---|
| `sale` | Recipient is related to the Sale, usually customer email. |
| `shipping` | Recipient is related to the Shipment or related Sale/Customer. |
| `subscription` | Recipient is related to the Subscription. |
| `subscription_renewal` | Recipient is related to the Renewal/Subscription. |
| `transaction` | Recipient is related to the Transaction/Sale/Customer. |
| `chargeback` | Recipient is authorized to receive dispute-related communication. |
| `fraud_detection` | Avoid exposing sensitive fraud/risk details unless explicitly intended. |

Do not send sensitive payment, fraud, chargeback, or internal details to a recipient based only on user-provided text.

---

## Human-in-the-Loop Guidance

When a human is interacting directly, AI/MCP should confirm before sending if:

- recipients are not obvious,
- custom arguments include AI-generated prose,
- the message is customer-facing,
- the message relates to a sensitive item,
- multiple templates could apply,
- the template has predefined recipients the user may not know about.

For low-risk internal sends where the user explicitly provided the template and recipient, confirmation may not be necessary unless required by the client workflow.

---

## No-Human-in-the-Loop Guidance

If an external AI/agent calls this operation without a human in the loop:

```text
Only send when the task payload provides explicit authorization and all required inputs.
```

If required values are missing:

```text
Stop safely and return missing requirements.
```

Do not guess:

- template ID,
- recipient,
- custom argument value,
- item relationship,
- sensitive email content.

---

## Common Mistakes to Avoid

Do not:

- send without explicit authorization,
- use a non-`api_direct` Email Template,
- use a disabled Email Template,
- skip `GetEmailTemplate`,
- ignore `custom_arguments`,
- provide custom argument names that do not match the template,
- assume `to` overwrites template recipients,
- send to a customer without verifying relationship to the item,
- expose internal metadata, chargeback strategy, fraud/risk logic, or payment details unnecessarily,
- create raw one-off email HTML instead of using an Email Template.

---

## Final AI/MCP Instruction

Use `SendSMTPMessage` to send a direct SMTP Message from an existing enabled `api_direct` Email Template.

Before sending, retrieve and review the Email Template, check recipients, review custom arguments, retrieve related item details if needed, and only send when explicitly authorized.


---
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.