# RevCent MCP Guide: `CreateSMTPProfile`

AI/MCP-focused guide for creating SMTP Profiles in RevCent.

This document explains the `CreateSMTPProfile` operation, required fields, secure credential handling, SMTP provider settings, and the important relationship between the SMTP Profile and the `template_from` email address used by RevCent Email Templates.

---

## Related Documentation

AI/MCP clients should also read:

```text
https://revcent.com/documentation/markdown/mcp/operation/OverviewSMTPProfile.md
```

```text
https://revcent.com/documentation/markdown/mcp/operation/OverviewEmailTemplate.md
```

```text
https://revcent.com/documentation/markdown/mcp/operation/CreateEmailTemplate.md
```

Email Templates require an SMTP Profile. SMTP Profiles define the SMTP server connection RevCent uses to send email, while Email Templates define the email content, trigger, sender, recipients, and Handlebars rendering.

---

## Operation Summary

Operation:

```text
CreateSMTPProfile
```

Title:

```text
Create A SMTP Profile
```

Purpose:

```text
Create an SMTP Profile in RevCent.
```

An SMTP Profile lets RevCent send email through the merchant's own SMTP server/provider.

Common providers include:

- transactional email providers,
- business email providers,
- brand-owned SMTP servers,
- domain-specific SMTP providers,
- shop-specific SMTP providers.

SMTP Profiles are used by RevCent Email Templates.

Conceptual relationship:

```text
SMTP Profile = the SMTP connection RevCent uses to send email
Email Template = the actual email content, trigger, sender, recipients, and timing
```

---

## Critical Sender / From Email Requirement

It is important to make sure the email address used as the Email Template `template_from` matches the correct sender/from email configured or authorized in the SMTP provider/server that RevCent will connect to.

Although `CreateSMTPProfile` does not contain a `from_email` field, the SMTP Profile and Email Templates must be configured together correctly.

The SMTP Profile defines:

```text
host
port
SSL/TLS behavior
credentials
```

The Email Template defines:

```text
template_from
template_from_name
template_to
template_subject
template_html
template_trigger
```

Critical rule:

```text
The Email Template template_from address should match the sender email address or sender domain authorized by the SMTP provider/server used by the SMTP Profile.
```

Examples:

| SMTP Provider / Server Is Authorized For | Good `template_from` |
|---|---|
| `orders@example.com` | `orders@example.com` |
| `support@example.com` | `support@example.com` |
| `example.com` domain | `orders@example.com`, `support@example.com`, or another authorized `@example.com` sender |
| `billing.brand-a.com` / Brand A sending identity | `billing@brand-a.com` or approved Brand A sender |

Bad examples:

| SMTP Profile Uses | Bad `template_from` |
|---|---|
| SMTP credentials for `orders@example.com` | `support@otherdomain.com` |
| SMTP provider authorized only for `brand-a.com` | `orders@brand-b.com` |
| SMTP account that only allows one sender | Any sender other than the authorized sender |

If the sender does not match the SMTP provider/server configuration, the email may fail to send, be rejected, fail SPF/DKIM/DMARC alignment, or land in spam.

AI/MCP clients must not treat the SMTP Profile as isolated from Email Template sender settings.

---

## Why From Email Alignment Matters

Incorrect from-email alignment can cause:

- SMTP authentication failure,
- provider rejection,
- DMARC alignment failure,
- SPF/DKIM issues,
- spam folder placement,
- poor deliverability,
- customer confusion,
- brand/domain mismatch,
- inability to send from the desired sender address.

Correct setup:

```text
SMTP Profile connects to provider/server authorized for orders@example.com
    ↓
Email Template uses template_from = orders@example.com
    ↓
Email sends through the correct provider identity
```

Incorrect setup:

```text
SMTP Profile connects to provider/server authorized for orders@example.com
    ↓
Email Template uses template_from = support@different-domain.com
    ↓
Provider may reject or deliverability may suffer
```

Before creating the SMTP Profile, AI/MCP should ask the user which sender email/domain the SMTP server is authorized to send from so later Email Templates use the correct `template_from`.

---

## Secure Credential Requirement

SMTP credentials are sensitive.

Do not ask users to paste SMTP usernames, passwords, tokens, API keys, or SMTP secrets into chat.

The `CreateSMTPProfile` operation requires credentials to be supplied securely through `CreateSecureForm`.

Correct credential workflow:

```text
1. Ask for non-sensitive SMTP settings:
       name
       description
       host
       port
       use_ssl
       require_tls
       intended sender/from email or domain
2. Create a Secure Form for SMTP authentication values.
3. User opens the Secure Form link.
4. User enters SMTP credentials securely.
5. User confirms the Secure Form is completed.
6. Call CreateSMTPProfile with secure_form_id.
```

Never include raw SMTP credentials directly in the `CreateSMTPProfile` request.

---

## Input Schema

`CreateSMTPProfile` input schema:

```text
type: object
additionalProperties: false
required:
  - name
  - host
  - port
```

Only send supported fields.

Unsupported fields must not be included.

---

## 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 | Human-readable description of the SMTP Profile. |
| `enabled` | boolean | Whether the SMTP Profile is currently enabled. |
| `use_ssl` | boolean | Whether the SMTP connection uses SSL. |
| `require_tls` | boolean | Whether the SMTP connection requires TLS. |
| `secure_form_id` | string | 20-character Secure Form ID containing SMTP credentials. |

---

## Field Details

### `name`

Use a clear name that identifies the sender, brand, shop, provider, or purpose.

Good examples:

```text
Main Store SMTP
Orders SMTP - example.com
Support SMTP - Brand A
WooCommerce Store SMTP
Production Transactional SMTP
Billing Emails SMTP
```

Poor examples:

```text
SMTP
Email
Profile
Test
```

---

### `description`

Use the description to explain:

- SMTP provider,
- sender/from email or domain,
- brand/shop/campaign,
- intended Email Templates,
- production vs test usage,
- whether it is enabled for production,
- any deliverability notes.

Example:

```text
SMTP Profile for transactional customer emails from orders@example.com. Used by Sale receipt, shipment, subscription, trial, and support Email Templates.
```

---

### `enabled`

Use:

```json
"enabled": true
```

when the SMTP Profile should be active.

Use:

```json
"enabled": false
```

when the profile should be created but not used yet.

Best practice:

```text
Create SMTP Profiles disabled until host, port, SSL/TLS, credentials, sender authorization, and a controlled Email Template test have been verified.
```

---

### `host`

The SMTP server hostname.

Examples:

```text
smtp.example.com
smtp.mailgun.org
smtp.sendgrid.net
email-smtp.us-east-1.amazonaws.com
```

Do not guess.

Use the exact host from the SMTP provider/server configuration.

---

### `port`

The SMTP server port.

Common values include:

```text
587
465
25
2525
```

Do not guess.

Use the exact port from the SMTP provider/server configuration.

---

### `use_ssl`

Whether the SMTP connection uses SSL.

This must match the SMTP provider/server configuration.

Common pattern:

```text
Port 465 often uses SSL.
```

But always use the provider's actual instructions.

---

### `require_tls`

Whether TLS is required.

This must match the SMTP provider/server configuration.

Common pattern:

```text
Port 587 often uses STARTTLS/TLS.
```

But always use the provider's actual instructions.

---

### `secure_form_id`

The 20-character Secure Form ID containing SMTP authentication values.

Use this only after the user completes a Secure Form.

Example:

```json
"secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
```

The Secure Form protects sensitive credentials from being submitted directly through chat/AI.

---

## Example Request

```json
{
  "name": "Main Store SMTP",
  "description": "Transactional SMTP for orders@example.com. Used for purchase receipts, shipment updates, subscription emails, and trial emails.",
  "enabled": false,
  "host": "smtp.example.com",
  "port": 587,
  "use_ssl": false,
  "require_tls": true,
  "secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

Note:

```text
This example does not include a from email because CreateSMTPProfile does not have a from-email field.
The matching from email is configured later on Email Templates as template_from.
```

---

## Output Schema

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 `smtp_profile_id` is used by Email Templates:

```json
{
  "smtp_profile": "XXXXXXXXXXXXXXXXXXXX"
}
```

---

## Relationship to `CreateEmailTemplate`

`CreateEmailTemplate` requires:

```text
smtp_profile
template_from
template_to
template_subject
template_html
template_trigger
```

The `smtp_profile` field is the SMTP Profile ID returned by `CreateSMTPProfile`.

The `template_from` field is the sender address used when sending the email.

Important:

```text
template_from should match the sender address or sender domain authorized by the SMTP Profile's SMTP provider/server.
```

Example:

```json
{
  "smtp_profile": "XXXXXXXXXXXXXXXXXXXX",
  "template_from": "orders@example.com",
  "template_from_name": "Example Store"
}
```

This should only be used if the SMTP provider/server configured in the SMTP Profile is authorized to send as `orders@example.com`.

---

## Required Pre-Checks Before Calling `CreateSMTPProfile`

Before creating an SMTP Profile, verify:

- User explicitly wants to create an SMTP Profile.
- SMTP provider/server is known.
- SMTP host is known.
- SMTP port is known.
- SSL/TLS settings are known.
- SMTP credentials are ready to be entered into Secure Form.
- Secure Form was created.
- User completed the Secure Form.
- Intended sender/from email address is known.
- Intended sender/from email is authorized by the SMTP provider/server.
- Sender domain has SPF/DKIM/DMARC configured or planned.
- `enabled` state is intentional.
- User understands Email Templates will use this profile through the `smtp_profile` field.
- User understands Email Template `template_from` must match the SMTP provider/server authorized sender/domain.

---

## Recommended Setup Workflow

```text
1. Ask which SMTP provider/server the user wants RevCent to connect to.
2. Ask for non-sensitive SMTP settings:
       host
       port
       use_ssl
       require_tls
3. Ask what sender/from email or domain this SMTP server is authorized to send from.
4. Confirm the intended Email Template template_from address should match that sender/domain.
5. Confirm sender domain authentication:
       SPF
       DKIM
       DMARC
6. Create Secure Form for SMTP credentials.
7. User completes Secure Form.
8. Call CreateSMTPProfile, usually with enabled = false.
9. Create or edit a test Email Template using the returned smtp_profile_id.
10. Ensure the Email Template template_from matches the SMTP provider/server sender.
11. Send/test through the appropriate RevCent Email Template flow.
12. Enable the SMTP Profile only after verification.
```

---

## Testing Guidance

After creating the SMTP Profile, test through an Email Template.

Check:

- email sends successfully,
- recipient receives the email,
- `From` address is correct,
- `From Name` is correct,
- SMTP provider logs show success,
- SPF/DKIM/DMARC alignment is acceptable,
- message does not land in spam,
- provider does not reject the sender address.

If sending fails, review:

- host,
- port,
- SSL/TLS settings,
- credentials,
- provider account status,
- sender authorization,
- `template_from`,
- recipient address,
- disabled SMTP Profile,
- disabled Email Template,
- provider rate limits.

---

## Best Practices

1. Never collect SMTP credentials in chat.
2. Always use Secure Form for credentials.
3. Do not guess SMTP host, port, SSL, or TLS settings.
4. Create the profile disabled until tested.
5. Ask for the intended sender/from email before creating the profile.
6. Ensure Email Template `template_from` matches the SMTP provider/server authorized sender.
7. Use a clear profile name.
8. Use a description that states the sender/from email or domain.
9. Use separate SMTP Profiles for separate brands/domains when needed.
10. Confirm SPF, DKIM, and DMARC for production sending.
11. Test with a controlled Email Template before enabling for production.
12. Do not claim inbox placement is guaranteed.

---

## Common Mistakes to Avoid

Do not:

- ask the user to paste SMTP passwords, usernames, tokens, or API keys into chat,
- call `CreateSMTPProfile` without a Secure Form when credentials are needed,
- guess SMTP host,
- guess SMTP port,
- guess SSL/TLS behavior,
- create an enabled profile before testing,
- ignore sender/from-email alignment,
- use `template_from` from a different domain than the SMTP provider allows,
- use one SMTP Profile for multiple unrelated brands when sender domains differ,
- assume the SMTP Profile itself contains the Email Template `template_from`,
- claim that creating the SMTP Profile guarantees inbox delivery,
- ignore SPF/DKIM/DMARC,
- send unsupported fields in the request body.

---

## AI/MCP Decision Guide

| Situation | Correct Action |
|---|---|
| User wants to configure RevCent email sending | Create an SMTP Profile. |
| User has SMTP credentials | Use Secure Form; do not collect secrets in chat. |
| User does not know host/port/security settings | Ask them to retrieve these from their SMTP provider. |
| User wants emails from `orders@example.com` | Confirm the SMTP provider/server is authorized for `orders@example.com` or `example.com`. |
| User wants multiple brands/domains | Use separate SMTP Profiles where needed. |
| User wants to create Email Templates | Use returned `smtp_profile_id` in `CreateEmailTemplate.smtp_profile`. |
| User changes sender/from email later | Confirm the SMTP Profile's provider/server allows that sender. |

---

## Final AI/MCP Instruction

Use `CreateSMTPProfile` to create the SMTP transport configuration RevCent will use to send Email Templates.

The operation requires `name`, `host`, and `port`. SMTP credentials must be collected through Secure Form and passed as `secure_form_id`; never ask the user to paste credentials into chat.

Before creating the profile, identify the correct sender/from email or sender domain authorized by the SMTP provider/server. When Email Templates are created later, their `template_from` address must match that authorized sender/from email or domain. This is critical for successful sending, provider acceptance, SPF/DKIM/DMARC alignment, and deliverability.


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