# SMTP connections

A **connection** is the SMTP login for one sending address. Every email MarleyFetch sends goes
out through one of your connections, so it is delivered by your provider, from your domain,
with your reputation.

Add connections on the [Connections](https://app.marleyfetch.com/connections) page. The login
is tested before it is saved, and the password is encrypted at rest.

## Provider settings

Pick a preset and most fields fill themselves in. For reference:

| Provider | Host | Port | Username | Password |
| --- | --- | --- | --- | --- |
| Gmail | `smtp.gmail.com` | 587 | your address | [App Password](https://myaccount.google.com/apppasswords) (needs 2-Step Verification) |
| Google Workspace | `smtp.gmail.com` | 587 | your address | App Password; your admin must allow SMTP |
| Outlook / Hotmail | `smtp-mail.outlook.com` | 587 | your address | account password |
| Microsoft 365 | `smtp.office365.com` | 587 | your address | account password; SMTP AUTH must be enabled for the mailbox |
| Yahoo Mail | `smtp.mail.yahoo.com` | 465 | your address | App Password |
| iCloud Mail | `smtp.mail.me.com` | 587 | your address | app-specific password from appleid.apple.com |
| Zoho Mail | `smtp.zoho.com` | 465 | your address | account or app password |
| SendGrid | `smtp.sendgrid.net` | 587 | the literal word `apikey` | your SendGrid API key |
| Brevo | `smtp-relay.brevo.com` | 587 | your address | SMTP key from Brevo → SMTP & API |
| Amazon SES | `email-smtp.<region>.amazonaws.com` | 587 | SES SMTP username | SES SMTP password (not your AWS access key) |
| Any other host | your host | 587, 465 or 2525 | usually your address | your password |

Only the standard submission ports are accepted: **587** and **2525** use STARTTLS, **465**
uses TLS. Encryption follows from the port, so you never set it separately.

::: tip Most failed connections are the password
Gmail, Workspace, Yahoo and iCloud reject your normal password over SMTP. Create an app password
and use that. Microsoft 365 tenants often have SMTP AUTH switched off until an admin enables it.
:::

## Choosing the sender: `from`

Every send request can include `from`. It must be the address of one of your connections, and it
decides which connection sends:

```json
{ "from": "billing@yourcompany.com", "to": "customer@example.com", "subject": "Invoice", "text_body": "..." }
```

- **With `from`** — MarleyFetch sends through the connection with that address, or returns
  `403 CONNECTION_NOT_FOUND` if you have none.
- **Without `from`** — it uses your **default connection**. Your first connection becomes the
  default automatically; pick another on the Connections page (**⋮ → Make Default**). If you
  delete the default, your oldest remaining connection takes over.

An [API key](https://docs.marleyfetch.com/guides/api-keys.md) can also be locked to one connection, which overrides both.

## Quotas and pacing

Each connection has a **quota**: how many emails it may send per day or per hour. Presets start
at the provider's published limit (for example 500/day for Gmail, 2,000/day for Workspace), and
you can change the number and the window when you add or edit the connection. The Connections
page shows how much of it is used.

Keep the quota at or below what your provider allows. Going over their limit gets your account
throttled or suspended by the provider, not by MarleyFetch.

What happens when a limit is hit:

| Situation | `/send` | `/enqueue` and batches |
| --- | --- | --- |
| Connection quota used up | `429 QUOTA_EXCEEDED` with `details.resetsAt` | Wait for the next window, then send |
| Sending too fast, or the provider pushed back | `429 RATE_LIMITED` with `details.retryAfter` (seconds) | Back off and retry automatically |
| Provider kept rejecting sends, so the connection was paused | `403 CONNECTION_NOT_FOUND` or `CONNECTION_PAUSED` | Wait until it resumes |
| You disabled the connection | `403 CONNECTION_NOT_FOUND` | Not sent |

The Free plan also caps sending at 100 emails a day (`429 DAILY_LIMIT_REACHED`); see
[Plans & limits](https://docs.marleyfetch.com/reference/limits.md).

## Disabling and deleting

Disable a connection on the Connections page to stop all sending through it without losing its
settings, and enable it again later. API keys locked to a deleted connection stop working.

## Plan limits

The Free plan allows **1** connection; Pro is unlimited.