# RevCent SMTP Profiles Overview for AI/MCP

AI/MCP-focused overview for SMTP Profiles in RevCent.

This document explains what SMTP Profiles are, why they matter, how they are created and edited, how they relate to Email Templates, and how AI/MCP clients should safely guide users through SMTP setup.

---

## Reference Links

AI/MCP clients should read these related files when working with SMTP Profiles and Email Templates:

| Document | Link | Why It Matters |
|---|---|---|
| Email Template Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewEmailTemplate.md` | Explains how RevCent Email Templates send dynamic ecommerce emails using SMTP Profiles, triggers, filters, Handlebars, custom data, timing, and event data. |
| CreateEmailTemplate Guide | `https://revcent.com/documentation/markdown/mcp/operation/CreateEmailTemplate.md` | Explains the full `CreateEmailTemplate` schema, including the required `smtp_profile` field and how SMTP Profiles are used when sending emails. |

---

## Source Operations

This overview is based on the following RevCent MCP operations:

| Operation | Purpose |
|---|---|
| `CreateSMTPProfile` | Create a new SMTP Profile in RevCent. |
| `EditSMTPProfile` | Edit an existing SMTP Profile. |
| `CreateEmailTemplate` | Create an Email Template that uses an SMTP Profile to send email. |
| `EditEmailTemplate` | Edit an existing Email Template, including the SMTP Profile it uses where supported. |
| `GetEmailTemplates` | Retrieve Email Templates for review/selection. |
| `GetEmailTemplate` | Retrieve one Email Template for detailed review. |

Related operation:

| Operation | Purpose |
|---|---|
| `CreateSecureForm` | Securely collect SMTP credentials without exposing secrets in AI/chat. |

---

## What Is an SMTP Profile?

An SMTP Profile is a RevCent configuration that lets a merchant send emails through their own SMTP provider.

In RevCent, SMTP Profiles are used by Email Templates.

Conceptually:

```text
SMTP Profile = how RevCent sends the email
Email Template = what RevCent sends, to whom, and when
```

An SMTP Profile contains connection settings such as:

- SMTP host,
- SMTP port,
- SSL usage,
- TLS requirement,
- enabled/disabled state,
- secure credentials provided through Secure Form.

Email Templates then reference the SMTP Profile by ID:

```text
smtp_profile = 20-character SMTP Profile ID
```

---

## Why SMTP Profiles Matter

RevCent Email Templates require an active SMTP Profile.

RevCent does not send merchant emails through RevCent's own SMTP server. The merchant configures and uses their own SMTP Profile.

This is important because:

- the merchant controls the sending domain,
- the merchant controls the SMTP provider,
- sender authentication remains under the merchant's domain/provider,
- deliverability setup remains the merchant's responsibility,
- emails can come from brand-specific addresses,
- different shops/brands/campaigns can use different SMTP Profiles.

Common sender identities:

```text
support@example.com
orders@example.com
billing@example.com
shipping@example.com
no-reply@example.com
brand-a@example.com
brand-b@example.com
```

For ecommerce businesses, SMTP Profiles allow RevCent to send purchase, billing, shipping, fraud, support, subscription, trial, AI, and operational emails using the merchant's own email infrastructure.

---

## Relationship to Email Templates

Email Templates require an SMTP Profile.

The `CreateEmailTemplate` schema requires:

```text
smtp_profile
```

as a 20-character SMTP Profile ID.

Email Templates define:

- sender address,
- sender display name,
- recipients,
- subject,
- HTML body,
- trigger,
- timing,
- filters,
- Handlebars data,
- custom data,
- API/AI direct behavior.

The SMTP Profile defines:

- where the email is sent from at the SMTP transport level,
- SMTP host/port/security settings,
- credentials used by RevCent to authenticate with the SMTP provider.

Recommended mental model:

```text
SMTP Profile:
    host, port, SSL/TLS, credentials, enabled

Email Template:
    trigger, from/to/subject/body, filters, timing, Handlebars
```

The Email Template overview explains that the `template_from` address should generally match the sender address/domain configured for the SMTP Profile to reduce delivery issues.

---

## Ecommerce Use Cases

SMTP Profiles power RevCent's automated and direct emails.

Common email workflows include:

| Workflow | Email Template Trigger / Context |
|---|---|
| Customer purchase receipt | Sale success |
| Failed payment notice | Sale decline / subscription renewal decline / trial expiration decline |
| Abandoned checkout email | Pending Sale no payment |
| Shipment created notification | Shipping item created |
| Shipment shipped tracking email | Shipping item shipped |
| Shipment delivered email | Shipping item delivered |
| Subscription renewal reminder | Subscription renewal upcoming |
| Subscription renewal success | Subscription renewal success |
| Trial ending reminder | Trial expire upcoming |
| Trial conversion success | Trial expire success |
| Refund/internal accounting alerts | Pending refund created |
| Fraud/risk alerts | Sentinel / Fraud Detection / Sale Fraud Alert |
| AI-generated custom email | API/AI direct |
| Internal operations emails | Any applicable trigger/filter combination |

SMTP Profiles make these emails possible by providing the sending infrastructure.

---

## Multiple SMTP Profiles

Merchants may need more than one SMTP Profile.

Examples:

| Scenario | SMTP Profile Strategy |
|---|---|
| One brand/store | One SMTP Profile may be enough. |
| Multiple brands | Use one SMTP Profile per brand/domain. |
| Multiple WooCommerce shops | Use shop-specific SMTP Profiles if each shop has a different sending domain. |
| Separate support and billing senders | Use separate SMTP Profiles if the SMTP provider/credentials differ. |
| Production vs test | Use separate SMTP Profiles to prevent test emails from using production sender settings. |
| High-volume operational emails | Use a provider/account designed for transactional email volume. |

Best practice:

```text
Use SMTP Profiles that match the brand, shop, and sender domain used in Email Templates.
```

---

## Deliverability Responsibility

Because RevCent sends through the merchant's SMTP provider, the merchant is responsible for email deliverability setup.

This includes:

- SMTP provider configuration,
- sender verification,
- SPF,
- DKIM,
- DMARC,
- bounce handling,
- domain reputation,
- provider limits,
- rate limits,
- suppression/bounce management where applicable,
- ensuring sender addresses are permitted by the SMTP provider.

AI/MCP clients should not claim that creating an SMTP Profile guarantees email inbox placement.

Correct framing:

```text
RevCent uses the configured SMTP Profile to send the email.
Deliverability depends on the merchant's SMTP provider, domain authentication, sender reputation, and template quality.
```

---

## Credential Security

SMTP credentials are sensitive.

AI/MCP clients must not ask the user to paste SMTP passwords, usernames, tokens, API keys, or secrets into chat.

The `CreateSMTPProfile` schema requires credentials to be provided securely through `CreateSecureForm`.

Correct credential workflow:

```text
AI/MCP collects non-sensitive SMTP settings:
    name
    description
    enabled
    host
    port
    use_ssl
    require_tls
    ↓
AI/MCP creates Secure Form for SMTP authentication values
    ↓
User opens Secure Form link
    ↓
User enters SMTP credentials securely
    ↓
User confirms the form is completed
    ↓
AI/MCP uses secure_form_id in CreateSMTPProfile or EditSMTPProfile
```

Never ask for SMTP credentials directly in chat.

---

## CreateSMTPProfile

`CreateSMTPProfile` creates a new SMTP Profile.

Operation title:

```text
Create A SMTP Profile
```

The operation description states that a Secure Form must be created through `CreateSecureForm` so authentication values can be saved securely.

After the user completes the Secure Form, include:

```text
secure_form_id
```

in the `CreateSMTPProfile` request.

### Required Fields

| Field | Type | Required | Description |
|---|---:|---:|---|
| `name` | string | Yes | SMTP Profile name. |
| `host` | string | Yes | SMTP server host. |
| `port` | integer | Yes | SMTP server port. |

### Optional Fields

| Field | Type | Description |
|---|---:|---|
| `description` | string | Description of the SMTP Profile. |
| `enabled` | boolean | Whether the SMTP Profile is enabled. |
| `use_ssl` | boolean | Whether the SMTP Profile uses SSL. |
| `require_tls` | boolean | Whether the SMTP Profile requires TLS. |
| `secure_form_id` | string | 20-character Secure Form ID for credentials. |

### Example Request Shape

```json
{
  "name": "Main Store SMTP",
  "description": "SMTP Profile for transactional emails from orders@example.com.",
  "enabled": false,
  "host": "smtp.example.com",
  "port": 587,
  "use_ssl": false,
  "require_tls": true,
  "secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

Do not guess SMTP host, port, SSL, or TLS settings.

Use the values from the merchant's SMTP provider.

Best practice:

```text
Create the SMTP Profile disabled until credentials, host, port, SSL/TLS behavior, sender domain authentication, and at least one test Email Template are verified.
```

---

## CreateSMTPProfile Output

Successful output can include:

| 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 | API response code. `1` indicates success. |
| `smtp_profile_id` | string | 20-character SMTP Profile ID. |
| `result` | string | Result message. |

The returned:

```text
smtp_profile_id
```

is used by Email Templates.

---

## EditSMTPProfile

`EditSMTPProfile` edits an existing SMTP Profile.

Operation title:

```text
Edit A SMTP Profile
```

This is a consequential operation and should only be performed after explicit user confirmation.

Important behavior:

```text
Only provide fields that should be edited.
```

For example, if only editing the SMTP Profile name, send only:

```json
{
  "smtp_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "name": "Main Store Transactional SMTP"
}
```

Do not include credentials or other fields unless they are being intentionally changed.

### Required Field

| Field | Type | Required | Description |
|---|---:|---:|---|
| `smtp_profile_id` | string | Yes | 20-character SMTP Profile ID. |

### Optional Editable Fields

| Field | Type | Description |
|---|---:|---|
| `name` | string | SMTP Profile name. |
| `description` | string | SMTP Profile description. |
| `enabled` | boolean | Whether the SMTP Profile is enabled. |
| `host` | string | SMTP server host. |
| `port` | integer | SMTP server port. |
| `use_ssl` | boolean | Whether SSL is used. |
| `require_tls` | boolean | Whether TLS is required. |
| `secure_form_id` | string | Only provide if changing SMTP credentials. |

### Credential Edits

If changing SMTP credentials:

```text
Create a new Secure Form.
Have the user complete the form.
Pass secure_form_id to EditSMTPProfile.
```

Do not ask the user to paste credentials into chat.

Example credential update shape:

```json
{
  "smtp_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

Only include `secure_form_id` if credentials are being changed.

---

## EditSMTPProfile Output

Successful output can include:

| 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 | API response code. `1` indicates success. |
| `smtp_profile_id` | string | 20-character SMTP Profile ID. |
| `result` | string | Result message. |

---

## SMTP Profile Fields Explained

### `name`

Use a clear name that identifies the sender/provider/purpose.

Good examples:

```text
Main Store SMTP
Brand A Orders SMTP
Billing Emails SMTP
Support Emails SMTP
WooCommerce Store SMTP
Production Transactional SMTP
```

Poor examples:

```text
SMTP
Email
Test
Profile
```

### `description`

Use the description to explain:

- sender domain,
- SMTP provider,
- intended Email Templates,
- brand/shop/campaign,
- production vs test usage,
- whether it is safe to enable.

Example:

```text
Transactional SMTP profile for Brand A order receipts, shipment emails, and subscription renewal notices. Uses the brand's verified transactional email provider.
```

### `enabled`

Controls whether the SMTP Profile is active.

Best practice:

```text
Keep disabled until setup is verified.
Enable only after explicit user confirmation.
```

If an SMTP Profile is disabled, Email Templates that depend on it should not be expected to send successfully.

### `host`

SMTP server host. Use the SMTP provider's documented value. Do not guess.

### `port`

SMTP server port. Common values include `587`, `465`, `25`, and `2525`, but the correct value must come from the SMTP provider.

### `use_ssl`

Whether the SMTP connection uses SSL. This must match provider settings.

### `require_tls`

Whether TLS is required. This must match provider settings.

### `secure_form_id`

20-character Secure Form ID containing SMTP authentication values. Use only after the user completes the Secure Form.

---

## SMTP Profiles and Sender Addresses

Email Templates contain:

```text
template_from
template_from_name
```

The SMTP Profile contains the sending configuration.

Best practice:

```text
template_from should generally match the SMTP Profile's authorized sender address or sender domain.
```

Avoid sending from domains that the SMTP provider is not authorized to send.

Mismatch can cause:

- rejected email,
- spam placement,
- authentication failure,
- DMARC alignment failure,
- poor deliverability,
- user confusion.

---

## SMTP Profiles and Email Template Triggers

Email Templates use SMTP Profiles across many triggers.

Examples:

| Trigger / Workflow | Common Sender |
|---|---|
| Sale success receipt | `orders@example.com` |
| Sale decline / failed payment | `billing@example.com` |
| Pending Sale no payment | `support@example.com` or `sales@example.com` |
| Shipping item shipped | `shipping@example.com` |
| Subscription renewal upcoming | `billing@example.com` |
| Subscription renewal decline | `billing@example.com` |
| Trial expire upcoming | `support@example.com` |
| Pending refund created | internal accounting sender |
| Fraud Detection created | internal risk sender |
| API/AI direct | depends on message purpose |

The same SMTP Profile can be reused across many templates if sender/domain/provider settings are appropriate.

---

## Recommended SMTP Profile Setup Workflow

```text
1. Identify the email provider and sending domain.
2. Confirm the sender address/domain is verified with the SMTP provider.
3. Confirm SPF, DKIM, and DMARC are configured.
4. Confirm SMTP host.
5. Confirm SMTP port.
6. Confirm SSL/TLS requirements.
7. Create a Secure Form for SMTP credentials.
8. User completes Secure Form.
9. CreateSMTPProfile with name, host, port, security settings, enabled false, and secure_form_id.
10. Create or edit a test Email Template using the new SMTP Profile.
11. Verify a controlled send through the Email Template flow.
12. Enable the SMTP Profile only after successful verification.
13. Create production Email Templates using the SMTP Profile.
```

---

## Recommended SMTP Profile Edit Workflow

```text
1. Retrieve or confirm the SMTP Profile ID.
2. Identify exactly which fields need to change.
3. If credentials are changing, create a new Secure Form.
4. User completes Secure Form.
5. Call EditSMTPProfile with only intended fields.
6. If host/port/SSL/TLS changed, test with a controlled Email Template send.
7. Confirm Email Templates still use the correct SMTP Profile.
8. Re-enable only after verification if the profile was disabled.
```

---

## Testing and Verification

The SMTP Profile itself defines the transport, but emails are typically verified through Email Template usage.

Recommended verification:

```text
SMTP Profile configured
    ↓
Create or use test Email Template
    ↓
Use controlled recipient
    ↓
Verify email sends
    ↓
Verify from address and from name
    ↓
Verify SPF/DKIM/DMARC alignment through provider tools
    ↓
Review provider logs if delivery fails
```

If a send fails, check:

- SMTP credentials,
- host,
- port,
- SSL setting,
- TLS requirement,
- sender verification,
- provider account status,
- provider rate limits,
- firewall/network restrictions,
- Email Template `template_from`,
- Email Template recipient syntax,
- disabled SMTP Profile,
- disabled Email Template.

---

## Best Practices

1. Use Secure Form for all SMTP credentials.
2. Never ask users to paste SMTP credentials into chat.
3. Create profiles disabled until verified.
4. Use clear profile names.
5. Match Email Template `template_from` to the SMTP Profile's authorized sender/domain.
6. Use a dedicated transactional email provider for ecommerce lifecycle emails.
7. Configure SPF, DKIM, and DMARC before production use.
8. Use separate profiles for separate brands/domains when needed.
9. Use separate test and production SMTP Profiles when possible.
10. Confirm provider rate limits before high-volume templates.
11. Review Email Templates after disabling or editing an SMTP Profile.
12. Use explicit user confirmation before `EditSMTPProfile`.
13. Only include `secure_form_id` when creating the profile or changing credentials.
14. Do not guess host/port/SSL/TLS values.

---

## Common Mistakes to Avoid

Do not:

- ask for SMTP passwords or API keys in chat,
- send unsupported fields to `CreateSMTPProfile` or `EditSMTPProfile`,
- guess SMTP host,
- guess SMTP port,
- guess SSL/TLS settings,
- enable an SMTP Profile before testing,
- use a sender address not authorized by the SMTP provider,
- use a `template_from` address that conflicts with the SMTP Profile/domain,
- forget that Email Templates require an SMTP Profile,
- disable a shared SMTP Profile without checking dependent Email Templates,
- change credentials without using Secure Form,
- include `secure_form_id` in `EditSMTPProfile` unless changing credentials,
- claim that SMTP Profile creation guarantees inbox placement,
- ignore SPF/DKIM/DMARC,
- use one SMTP Profile for multiple unrelated brands when separate sender identities are needed.

---

## AI/MCP Decision Guide

| User Intent | Correct Action |
|---|---|
| Configure email sending for RevCent | Create an SMTP Profile. |
| Create lifecycle emails | Create Email Templates using an SMTP Profile. |
| Need SMTP credentials saved | Use `CreateSecureForm`; do not collect secrets in chat. |
| Create new SMTP transport | Use `CreateSMTPProfile`. |
| Rename or enable/disable profile | Use `EditSMTPProfile` with only the intended fields. |
| Change SMTP credentials | Create Secure Form, then `EditSMTPProfile` with `secure_form_id`. |
| Change host/port/security | Use `EditSMTPProfile`; test dependent Email Templates afterward. |
| Determine which profile a template uses | Use `GetEmailTemplate`. |
| Review all templates before disabling a profile | Use `GetEmailTemplates`. |
| Create a triggered email | Use `CreateEmailTemplate` with a valid `smtp_profile`. |

---

## Validation Checklist Before Creating an SMTP Profile

Before calling `CreateSMTPProfile`, verify:

- User explicitly wants to create an SMTP Profile.
- SMTP provider is known.
- Sending domain/address is known.
- SMTP host is known.
- SMTP port is known.
- SSL/TLS settings are known.
- Credentials are ready to enter into Secure Form.
- Secure Form has been created and completed.
- Sender domain authentication is configured or planned.
- `enabled` value is intentional.
- User understands this profile will be used by Email Templates.

---

## Validation Checklist Before Editing an SMTP Profile

Before calling `EditSMTPProfile`, verify:

- User explicitly confirmed the edit.
- SMTP Profile ID is correct.
- Only fields being changed are included.
- Existing Email Templates that use the profile are considered.
- If credentials are changing, Secure Form has been completed.
- If host/port/SSL/TLS changes, testing is planned.
- If disabling, dependent Email Templates are reviewed.
- User understands possible email delivery impact.

---

## Final AI/MCP Instruction

SMTP Profiles are the sending infrastructure for RevCent Email Templates.

RevCent Email Templates require an SMTP Profile, and the merchant is responsible for configuring their own SMTP provider, credentials, sender domain, and deliverability settings.

Use `CreateSMTPProfile` to create a profile with host, port, SSL/TLS settings, and credentials supplied through Secure Form. Use `EditSMTPProfile` to modify only the fields that should change. Use `secure_form_id` when creating the SMTP Profile or when changing credentials; never ask the user to paste SMTP secrets into chat.

Email Templates reference SMTP Profiles through the required `smtp_profile` field. The Email Template controls trigger, timing, sender, recipients, subject, HTML, Handlebars, filters, and custom data. The SMTP Profile controls the SMTP transport used to send the email.


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