# SMTP

Use Bento's SMTP endpoint when your app, framework, or plugin can send email through SMTP but does not support Bento's HTTP Emails API directly.

SMTP submissions are accepted on port `587`, upgraded with STARTTLS, parsed, and queued through Bento's transactional email pipeline.


> For new server-side integrations, prefer the [Emails API](/docs/emails_api). SMTP is best for existing tools that expect a mail server.


---

## Connection Settings

Configure your SMTP client with:


  - **Host** (`string`): 
    `yubin.sentbybento.com`
  
  - **Port** (`integer`): 
    `587`
  
  - **Encryption** (`string`): 
    `STARTTLS`
  
  - **Authentication** (`string`): 
    `PLAIN`
  


> ⚠️ **Warning**
> Do not use unencrypted SMTP. Bento requires STARTTLS before authentication, so clients configured without encryption will not be able to sign in.


---

## Credentials

Use your Bento site UUID as the SMTP username. Use your Bento publishable key and secret key joined with a colon as the SMTP password.

```text
Username: your-site-uuid
Password: your_publishable_key:your_secret_key
```

Example:

```text
Username: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Password: bento_publishable_key:bento_secret_key
```

The SMTP gateway uses:

- `Username` as the Bento `site_uuid`
- `Password` as HTTP Basic auth credentials for Bento, split as `publishable_key:secret_key`


> 🚨 **Important**
> Treat SMTP credentials like API credentials. Do not paste them into client-side code, public repositories, logs, support screenshots, or browser-exposed configuration.


---

## Message Mapping

Bento converts the SMTP message into a transactional email request.


  - **MAIL FROM** (`SMTP envelope`): 
    Used as the sender when provided. The sender must be an author in your Bento account.
  
  - **RCPT TO** (`SMTP envelope`): 
    Each recipient becomes one queued Bento email.
  
  - **Subject** (`email header`): 
    Sent as the Bento email `subject`.
  
  - **HTML body** (`MIME part`): 
    Sent as `html_body` when the SMTP message includes HTML.
  
  - **Text body** (`MIME part`): 
    Used as a fallback when no HTML part exists. Bento escapes the text and preserves line breaks in an HTML wrapper.
  
  - **Reply-To** (`email header`): 
    Sent as the Bento email `reply_to` value.
  


If a message contains both `text/plain` and `text/html`, Bento uses the HTML part.

---

## Optional Headers

Add these headers to control Bento-specific behavior:


  - **X-Bento-Transactional** (`boolean`): 
    Set to `true`, `1`, or `yes` to mark the email as transactional. Transactional emails may be sent even if the recipient has unsubscribed. Use with care.
  
  - **X-Bento-Layout-Id** (`string`): 
    Applies a Bento layout to the email.
  


---

## Limitations

- Attachments are not supported. Link to files instead.
- The maximum message size is `10 MB`.
- A single SMTP message can include up to `50` recipients.
- The downstream transactional email queue is still subject to Bento's email API rate limits.
- The `From` address must be an author in your Bento account.


> ⚠️ **Warning**
> Avoid emojis, URL shorteners, and user-controlled personalization in transactional email content. These can hurt deliverability or let users inject unsafe content.


---

## Testing

You can verify STARTTLS from a terminal:

```bash
openssl s_client -starttls smtp \
  -connect yubin.sentbybento.com:587 \
  -servername yubin.sentbybento.com
```

A valid setup should show a certificate for `yubin.sentbybento.com` and a successful verification result.

To test a real send, configure your SMTP client with the connection settings above and send a message to an address you control.