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

# Send via SMTP relay

> Send transactional email through Mailercloud's SMTP relay from any framework, CMS, or legacy system — no code changes beyond SMTP settings.

If your application already speaks SMTP (WordPress, Laravel, legacy systems, CRMs), you can send through Mailercloud without integrating the HTTP API — just point your SMTP settings at the relay.

## Connection settings

| Setting | Value |
| - | - |
| Host | `smtp-prod.mailrcld.com` |
| Port | `587` |
| Security | `STARTTLS` |
| Authentication | `AUTH PLAIN` — username + password |

## Credentials

Switch to the **Transactional Email platform** (toggle in the sidebar), then open **Settings → SMTP Configuration** to view your host, username, and password. Use **Generate new password** to create or rotate the password.

<Warning>
  Generating a new password invalidates the previous one immediately — update all systems using the old credentials.
</Warning>

## Tracking headers

Control tracking and reporting per message with custom SMTP headers:

| Header | Purpose |
| - | - |
| `mld-track-opens` | `true`/`false` — enable or disable open tracking for this message, overriding the domain-level **Open Tracking** setting |
| `mld-track-inbox` | `true`/`false` — enable inbox-placement tracking |
| `mld-track-campaign-id` | Group sends under a campaign ID for reporting. Letters, numbers and hyphens, up to 100 characters |
| `mld-track-campaign-type` | `TRANSACTIONAL` or `PROMOTIONAL` — message type (default `PROMOTIONAL`) |
| `mld-track-store-content` | `false` to skip storing this message's content, for example OTP emails. Delivery and tracking are unaffected |
| `mld-track-tag` | Comma-separated labels for filtering in the Activity list — up to 10 tags of 100 characters each |

Click tracking is not available for transactional email, over SMTP relay or the HTTP API.

## Custom headers

Any other header you set is passed through to the recipient — use one such as `X-Order-Reference`
to carry your own correlation id. The one exception is the `X-MC-Custom-*` family below, which
Mailercloud consumes and strips before delivery.

* `List-Unsubscribe` must be one or more comma-separated values in angle brackets, each starting with `https://` or `mailto:`. `List-Unsubscribe-Post` must be exactly `List-Unsubscribe=One-Click` and requires `List-Unsubscribe` on the same message. A value you set replaces the one Mailercloud adds by default.
* Headers Mailercloud owns — `From`, `Message-ID`, `Date`, `DKIM-Signature`, `Feedback-ID`, `Content-*` and similar — are removed and replaced with the platform's own. Unlike the HTTP API, which rejects the request, SMTP drops an invalid or reserved header silently and still delivers the message.

## Custom data on webhooks

To attach your own data to a message and get it back on every
[transactional webhook](/guides/webhooks) event, add one header per key, each prefixed
`X-MC-Custom-`:

```
X-MC-Custom-order_ref: 10482
X-MC-Custom-repo_id: 412f80f9-0b34-41c3-bb54-88a13acef7a9
```

Each event returns your keys inside a `custom` object, with the `X-MC-Custom-` prefix removed:

```json theme={null}
"custom": {
  "order_ref": "10482",
  "repo_id": "412f80f9-0b34-41c3-bb54-88a13acef7a9"
}
```

* These headers are consumed by Mailercloud and **stripped before delivery** — the recipient never
  sees them.
* SMTP header names are **lowercased in transit**, so a key sent over SMTP comes back lowercase.
  (The [HTTP Email API](/guides/transactional-email#custom-data-on-webhooks) preserves your original
  casing.)
* Up to **10** keys; key names **≤ 50 characters** (`A–Z a–z 0–9 - _`); values **≤ 256 characters**.
  A key that breaks a rule is listed in the event's `custom_dropped` array and the message is still
  sent.

## Message IDs and duplicates

Mailercloud assigns every message accepted over SMTP relay its own id, and builds the outgoing
`Message-ID` header from it. A `Message-ID` set by your application is replaced, so use a custom
header such as `X-Order-Reference` if you need your own reference on the message.

<Warning>
  SMTP relay has no duplicate detection: sending the same message twice delivers it twice. The
  `metadata.messageId` 24-hour duplicate check is available on the
  [HTTP Email API](/api-reference/email/send-email) only.
</Warning>

## Security & delivery extras

* **IP Allowed List** — restrict which IP addresses may send through your account (single IPs, ranges, or wildcards). If unset, all IPs are allowed.
* **Webhooks** — receive real-time events for transactional sends: Sent, Delivery, Bounce, Spam, Open. See [Set up webhooks](/guides/webhooks).

## Example (Laravel `.env`)

```ini theme={null}
MAIL_MAILER=smtp
MAIL_HOST=smtp-prod.mailrcld.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=your-smtp-username
MAIL_PASSWORD=your-smtp-password
MAIL_FROM_ADDRESS=orders@yourdomain.com
```

## SMTP vs HTTP API — which to use?

| | SMTP relay | [HTTP Email API](/api-reference/email/send-email) |
| - | - | - |
| Setup | Config change only | Small code integration |
| Per-recipient personalization (mail merge) | ❌ Not supported | ✅ [`/email-api`](/api-reference/email/send-personalized-email) |
| Per-message open-tracking control | ✅ `mld-track-opens` | ❌ Domain-level only |
| Duplicate protection on retries | ❌ Not supported | ✅ `metadata.messageId`, 24 hours |
| Best for | Existing apps, CMS plugins, quick migration | New integrations, personalization, richer control |

The sender domain must be [verified](/authentication) on your account in either case.


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