# RevCent MCP Overview: SMTP Messages

AI/MCP-focused overview of SMTP Messages in RevCent.

---

## What Are SMTP Messages?

An **SMTP Message** is an email sent by RevCent using an existing Email Template and the SMTP Profile attached to that template.

Simple model:

```text
SMTP Profile = how RevCent sends email
Email Template = what RevCent sends
SMTP Message = a specific email sent from an Email Template
```

SMTP Messages are not raw one-off emails. They are generated from Email Templates.

---

## Core Concept

RevCent email sending depends on three connected pieces:

| Piece | Purpose |
|---|---|
| SMTP Profile | Defines the SMTP server, port, SSL/TLS behavior, and secure credentials used to send email. |
| Email Template | Defines subject, sender, recipients, HTML body, trigger, shortcodes, filters, timing, custom data, and custom arguments. |
| SMTP Message | The actual sent message generated from an Email Template using `SendSMTPMessage` or by an event-triggered Email Template. |

For API/MCP-driven direct sending:

```text
Email Template trigger must be api_direct
```

Only Email Templates with `template_trigger = api_direct` can be sent directly with `SendSMTPMessage`.

---

## Related Documentation

| Guide | Link |
|---|---|
| SMTP Profile Overview | `https://revcent.com/documentation/markdown/operation/OverviewSMTPProfile.md` |
| CreateSMTPProfile | `https://revcent.com/documentation/markdown/operation/CreateSMTPProfile.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` |
| SendSMTPMessage | `https://revcent.com/documentation/markdown/operation/SendSMTPMessage.md` |

---

## Related Operations

| Operation | Purpose |
|---|---|
| `CreateSMTPProfile` | Create the SMTP Profile used by Email Templates. |
| `GetSMTPProfiles` | List available SMTP Profiles. |
| `GetSMTPProfile` | Retrieve one SMTP Profile. |
| `CreateEmailTemplate` | Create a branded, responsive Email Template. |
| `EditEmailTemplate` | Edit an existing Email Template. |
| `GetEmailTemplates` | List Email Templates and find the correct Email Template ID. |
| `GetEmailTemplate` | Retrieve full Email Template details, including HTML and custom arguments. |
| `SendSMTPMessage` | Send a direct SMTP Message using an `api_direct` Email Template. |

---

## Two Ways SMTP Messages Are Sent

### 1. Event-Triggered Email Templates

Most Email Templates are triggered automatically by RevCent events.

Examples:

```text
sale_create_success
shipping_item_shipped
shipping_item_delivered
subscription_renew_success
subscription_renew_decline
trial_expire_success
trial_expire_decline
```

For event-triggered templates, RevCent sends the SMTP Message when the event occurs and filters/timing allow it.

AI/MCP does not usually call `SendSMTPMessage` for event-triggered templates.

### 2. API/MCP Direct Email Templates

An Email Template with:

```text
template_trigger = api_direct
```

can be sent directly through:

```text
SendSMTPMessage
```

Use this for user-directed, support, operational, or AI-generated email workflows where the user explicitly wants a message sent through an existing direct-send template.

---

## Important Safety Rule

Do not send an SMTP Message unless the user explicitly told AI/MCP to send it or the external no-human workflow has explicit authorization to send it.

Important:

```text
Do not use SendSMTPMessage just because a message could be useful.
```

Sending an email is an external communication. AI/MCP should treat it as an action, not a lookup.

---

## Email Template Requirements for Direct Sending

Before calling `SendSMTPMessage`, AI/MCP should verify:

```text
Email Template exists
Email Template is enabled
Email Template trigger is api_direct
Email Template has the correct SMTP Profile
Recipients are correct or can be supplied safely
Custom arguments are reviewed and provided if required
```

Use:

```text
GetEmailTemplate
```

before sending.

If the Email Template ID is unknown or invalid, use:

```text
GetEmailTemplates
```

to find the appropriate template.

---

## Recipients

`SendSMTPMessage` supports optional `to`, `cc`, and `bcc` arrays.

An Email Template may already contain predefined recipients.

Important behavior:

```text
Recipients already defined on the Email Template are not overwritten.
Additional recipients supplied to SendSMTPMessage are added and de-duplicated.
```

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

---

## Item Context

`SendSMTPMessage` can optionally include:

```text
item_type
item_id
```

Supported `item_type` values:

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

When an SMTP Message is sent with `item_type` and `item_id`, the Email Template can use context from the related item.

---

## Custom Arguments

Email Templates can define `custom_arguments`, especially for `api_direct` templates.

Each custom argument has:

| Field | Purpose |
|---|---|
| `name` | The argument name that must be provided to `SendSMTPMessage`. |
| `description` | Instructions describing what value AI/MCP should infer or provide. |

Before sending with a template that has custom arguments, AI/MCP must:

```text
1. Retrieve the Email Template using GetEmailTemplate.
2. Review the custom_arguments array.
3. Read each custom argument description.
4. Infer or obtain the correct value.
5. Provide each required value in SendSMTPMessage.custom_arguments.
```

If `item_type` and `item_id` are provided and the template has custom arguments:

```text
Get the item details first.
Use the item details plus custom argument descriptions to infer the values.
```

Do not send a template with incomplete or guessed custom arguments.

---

## Typical Send Flow

```text
User explicitly asks to send an email
    ↓
Identify the correct Email Template
    ↓
GetEmailTemplate
    ↓
Confirm template is enabled and api_direct
    ↓
Review recipients and custom arguments
    ↓
Retrieve related item details if item_type/item_id are used
    ↓
Prepare custom_arguments values
    ↓
SendSMTPMessage
    ↓
Return smtp_message_id and result
```

---

## Customer-Facing Email Guidance

For customer-facing emails, AI/MCP should be careful with:

- recipient identity,
- customer/order/subscription/shipment relationship,
- sensitive payment/refund/chargeback details,
- internal notes or metadata,
- tone and branding,
- unsubscribe/compliance requirements where applicable,
- whether the user explicitly approved sending.

If the message references a customer item, such as a Sale, Shipment, Subscription, Transaction, or Chargeback, AI/MCP should verify the recipient is appropriate for that item before sending.

---

## Branding and Template Quality

SMTP Messages inherit the quality of the Email Template.

When creating or editing templates used for SMTP Messages, AI/MCP should create well-styled, branded, responsive HTML templates.

Templates should follow the business's branding guidance, including:

- logo URL,
- colors,
- tone,
- support email,
- support phone,
- website URL,
- footer/compliance text,
- mobile-friendly layout.

Do not create simplistic or generic HTML when the business expects customer-facing branded email.

---

## Best Practices

1. Always use an existing `api_direct` Email Template for direct sends.
2. Use `GetEmailTemplate` before sending.
3. Confirm the template is enabled.
4. Review template recipients before adding recipients.
5. Review custom arguments before sending.
6. Retrieve related item details before inferring item-based custom arguments.
7. Do not send unless explicitly authorized.
8. Do not paste or expose SMTP credentials in messages.
9. Use branded responsive HTML for customer-facing templates.
10. Return the `smtp_message_id` after successful sending.

---

## Final AI/MCP Instruction

Use SMTP Messages to send template-backed emails from RevCent.

For direct sending, use `SendSMTPMessage` only with an enabled `api_direct` Email Template, after reviewing the Email Template, recipients, and custom arguments.

Do not send an SMTP Message unless the user explicitly requested it or the external automated workflow has explicit permission to send it.


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