> ## Documentation Index
> Fetch the complete documentation index at: https://docs.worldvisagroup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom SMTP Email Integration with WorldVisa

> Connect any SMTP server to WorldVisa. Configure host, port, authentication, Secure, Require TLS, Ignore TLS, TLS options, and DKIM so delivery matches your mail server.

Send transactional email through your own SMTP server. WorldVisa opens the connection with the same settings [Nodemailer](https://nodemailer.com/smtp/) uses, and the fields on the integration form map directly to those settings.

## Create the integration

**Step 1**

## Add the Custom SMTP provider

Open the Integrations page, select **Add a provider**, then select **Custom SMTP**.

**Step 2**

## Fill in the server and the sender

**Host**, **Port**, **From email address**, and **Sender name** are required. Set **User** and **Password** when the server requires authentication. Pick the TLS toggles for your port as described in [TLS settings](#tls-settings).

**Step 3**

## Activate the integration

Switch the integration from **Disabled** to **Active**, then select **Update**.

## Configuration fields

| Field | Required | What to enter |
| - | - | - |
| **User** | No | SMTP username. |
| **Password** | No | SMTP password or the app password your provider issued for SMTP. |
| **Host** | Yes | Hostname of the SMTP server, with no `smtp://` prefix, port, or path. |
| **Port** | Yes | TCP port, an integer from 1 to 65535. |
| **Secure** | No | Use implicit TLS. |
| **Require TLS** | No | Fail the send if the server does not offer STARTTLS. |
| **Ignore TLS** | No | Skip STARTTLS and send on a plain connection. |
| **TLS options** | No | The only JSON field. Paste one JSON object of extra [Node.js TLS settings](https://nodejs.org/api/tls.html#tlsconnectoptions-callback). Every other field on this form is plain text. |
| **DKIM: Domain name** | No | Domain placed in the DKIM signature (`d=`). |
| **DKIM: Private key** | No | PEM private key, including the `-----BEGIN` and `-----END` lines. |
| **DKIM: Key selector** | No | Selector placed in the DKIM signature (`s=`). |
| **From email address** | Yes | Address recipients see in **From**. The SMTP account must be allowed to send as this address. |
| **Sender name** | Yes | Display name shown next to the From address, such as `Acme`. |

WorldVisa authenticates only when both **User** and **Password** have a value. WorldVisa waits 10 seconds to open the TCP connection and 10 seconds on the socket after that.

## TLS settings

**Secure** selects the connection mode, and the other TLS controls depend on it.

| Port | Secure | Require TLS | Ignore TLS | TLS options |
| - | - | - | - | - |
| `465` | On | Ignored | Ignored | Applied |
| `587` or `25` | Off | Optional | Optional | Ignored |

With **Secure** on, the connection is encrypted before the first SMTP command. With **Secure** off, WorldVisa opens a plain connection and upgrades with STARTTLS when the server advertises it. **Require TLS** fails the send if that upgrade does not happen. **Ignore TLS** skips the upgrade, and it wins if both toggles are on.

**TLS options** is a text area. Paste one JSON object into it. WorldVisa rejects a string, an array, or invalid JSON, and ignores the field while **Secure** is off.

```json theme={null}
{
  "minVersion": "TLSv1.2"
}
```

To trust a private certificate authority, turn **Secure** on and set `ca` to that authority's PEM certificate. `ca` replaces the default public authorities for this connection, so the server certificate must chain to the authority you supply. Keep line breaks in the PEM as `\n` inside the JSON string.

```json theme={null}
{
  "ca": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----\n"
}
```

Keep certificate checks enabled. `{"rejectUnauthorized":false}` turns them off, so a host on the connection path can impersonate the mail server and receive the SMTP credentials.

WorldVisa checks the server certificate against **Host**. A `servername` key in **TLS options** is replaced with **Host**. If a send fails with `Host: ... is not in the cert's altnames: DNS:...`, set **Host** to one of the `DNS:` names in that error or to a name covered by a listed wildcard. An internal alias, a different domain, or an IP address fails this check even when it reaches the same server. Enter **Host** without the trailing dot Node prints in the error.

## DKIM

WorldVisa signs the message only when all three DKIM fields are set. Publish the matching public key at `{selector}._domainkey.{domain}`. For domain `example.com` and selector `WorldVisa`, that name is `WorldVisa._domainkey.example.com`.

## Troubleshooting

| Symptom | Action |
| - | - |
| Authentication failed | Set both **User** and **Password**, and confirm the account may send as **From email address**. |
| `Requests to private or reserved IP addresses are not allowed` | Set **Host** to a hostname that resolves to the private address, and add that hostname or address to `WV_SAFE_OUTBOUND_ALLOW` on the API and worker. `localhost` cannot be allow-listed. A literal private IP such as `10.0.0.1` is also rejected in **Host**. See Deploy WorldVisa with Docker. |
| TLS handshake failed on `587` or `25` | Turn **Secure** off. Those ports use STARTTLS. |
| `is not in the cert's altnames` | Set **Host** to a name on the certificate, as described in [TLS settings](#tls-settings). |

## Next steps

> [card] [Configure bcc, cc, and reply-to](https://docs.worldvisagroup.com/developers/integrations/email#sending-email-overrides)
>
> Learn how to configure bcc, cc, and reply-to for your email notifications using email overrides

> [card] [Sending email attachments](https://docs.worldvisagroup.com/developers/integrations/email#sending-email-attachments)
>
> Learn how to send attachments with email notifications

> [card] [Use different email integration](https://docs.worldvisagroup.com/developers/integrations/email#sending-email-overrides)
>
> Learn how to use different email provider integrations to be used to send emails


## Related topics

- [Outlook 365 Email Integration with WorldVisa](https://docs.worldvisagroup.com/developers/integrations/email/outlook365.md)
- [Resend Email Integration with WorldVisa](https://docs.worldvisagroup.com/developers/integrations/email/resend.md)
- [SendGrid Email Integration with WorldVisa](https://docs.worldvisagroup.com/developers/integrations/email/sendgrid.md)
- [How to Write Email Templates in WorldVisa](https://docs.worldvisagroup.com/developers/integrations/email/writing-email-template.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.