# Email providers

> List and connect the sending mailboxes of your Emelia account, change their sender name, enable their warmup and run a deliverability diagnosis by API.

Source: https://docs.emelia.io/docs/email-providers

An **email provider** is a sending mailbox connected to Emelia: a Google or Microsoft account, or any SMTP and IMAP mailbox. Campaigns send from them, through the [identities](https://docs.emelia.io/docs/campaigns.md#4-choose-the-senders) of each campaign.

## List your mailboxes

[`GET /email-providers`](https://docs.emelia.io/docs/email-providers/list-email-providers.md)

**curl**

```bash
curl https://api.emelia.io/email-providers \
  -H "Authorization: $EMELIA_API_KEY"
```

**JavaScript**

```js
const res = await fetch('https://api.emelia.io/email-providers', {
  headers: { Authorization: process.env.EMELIA_API_KEY },
});
const { providers } = await res.json();
const usable = providers.filter((p) => !p.disconnected && !p.disabled);
console.log(usable.map((p) => `${p._id} ${p.senderEmail}`));
```

**Python**

```python
import os
import requests

res = requests.get(
    "https://api.emelia.io/email-providers",
    headers={"Authorization": os.environ["EMELIA_API_KEY"]},
)
usable = [p for p in res.json()["providers"] if not p.get("disconnected") and not p.get("disabled")]
print([(p["_id"], p["senderEmail"]) for p in usable])
```

Each mailbox comes with the campaigns that use it. Passwords are always masked (`********`). There is no pagination: you get every mailbox in one response. The `_id` is what you put in `identities[].email` of a campaign.

## Connect an SMTP and IMAP mailbox

[`POST /email-providers`](https://docs.emelia.io/docs/email-providers/connect-mailbox.md)

**curl**

```bash
curl -X POST https://api.emelia.io/email-providers \
  -H "Authorization: $EMELIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "senderName": "Marie Martin",
    "senderEmail": "marie.martin@yourcompany.com",
    "emailType": "SMTP",
    "smtp": { "login": "marie.martin@yourcompany.com", "password": "app-password", "server": "smtp.yourcompany.com", "port": 465, "ssl": true },
    "imap": { "login": "marie.martin@yourcompany.com", "password": "app-password", "server": "imap.yourcompany.com", "port": 993, "ssl": true }
  }'
```

**JavaScript**

```js
await fetch('https://api.emelia.io/email-providers', {
  method: 'POST',
  headers: { Authorization: process.env.EMELIA_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    senderName: 'Marie Martin',
    senderEmail: 'marie.martin@yourcompany.com',
    emailType: 'SMTP',
    smtp: { login: 'marie.martin@yourcompany.com', password: process.env.SMTP_PASSWORD, server: 'smtp.yourcompany.com', port: 465, ssl: true },
    imap: { login: 'marie.martin@yourcompany.com', password: process.env.IMAP_PASSWORD, server: 'imap.yourcompany.com', port: 993, ssl: true },
  }),
});
```

**Python**

```python
requests.post(
    "https://api.emelia.io/email-providers",
    headers={"Authorization": os.environ["EMELIA_API_KEY"]},
    json={
        "senderName": "Marie Martin",
        "senderEmail": "marie.martin@yourcompany.com",
        "emailType": "SMTP",
        "smtp": {"login": "marie.martin@yourcompany.com", "password": os.environ["SMTP_PASSWORD"], "server": "smtp.yourcompany.com", "port": 465, "ssl": True},
        "imap": {"login": "marie.martin@yourcompany.com", "password": os.environ["IMAP_PASSWORD"], "server": "imap.yourcompany.com", "port": 993, "ssl": True},
    },
)
```

Emelia tests the SMTP and IMAP credentials before saving the mailbox. The number of mailboxes is limited by your plan. Google and Microsoft accounts are connected in the Emelia app, with their own sign in.

To fix the credentials of a disconnected mailbox, use [Update a mailbox](https://docs.emelia.io/docs/email-providers/update-mailbox.md): masked passwords (`********`) are kept as stored. [Change the sender name](https://docs.emelia.io/docs/email-providers/change-sender-name.md) works on every type of mailbox, without a new test.

## Warmup

Warmup builds the sending reputation of a mailbox before and while it prospects.

[`GET /email-providers/warmup`](https://docs.emelia.io/docs/email-providers/list-warmups.md)

[`POST /email-providers/warmup/enable`](https://docs.emelia.io/docs/email-providers/enable-warmup.md)

**curl**

```bash
curl -X POST https://api.emelia.io/email-providers/warmup/enable \
  -H "Authorization: $EMELIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"providerId": "6650f1a2b839d80011c5a0aa"}'
```

**JavaScript**

```js
await fetch('https://api.emelia.io/email-providers/warmup/enable', {
  method: 'POST',
  headers: { Authorization: process.env.EMELIA_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ providerId: '6650f1a2b839d80011c5a0aa' }),
});
```

**Python**

```python
requests.post(
    "https://api.emelia.io/email-providers/warmup/enable",
    headers={"Authorization": os.environ["EMELIA_API_KEY"]},
    json={"providerId": "6650f1a2b839d80011c5a0aa"},
)
```

* Enabling the warmup needs an active subscription. `providerId` takes the id of the mailbox or of its warmup.
* Some hosts cannot be warmed up: the call fails with `WARMUP_PROVIDER_UNSUPPORTED`.
* `GET /email-providers/warmup` returns the state of every mailbox (running or not, statistics, diagnosis), without pagination: a `page` parameter is ignored. The `_id` of an item is the warmup id.
* To turn a warmup off, use the Emelia app.

## Deliverability diagnosis

[`POST /email-providers/warmup/check-health`](https://docs.emelia.io/docs/email-providers/run-deliverability-check.md)

Asks for a new DNS, sending and blacklist diagnosis of a mailbox, from its warmup id (`{"warmupId": "..."}`). The result appears a few minutes later in `health` of `GET /email-providers/warmup`. This route answers its errors as `{"success": false, "message": "..."}`.

## Remove a mailbox

[`DELETE /email-providers/{providerId}`](https://docs.emelia.io/docs/email-providers/delete-mailbox.md)

Removes the mailbox from your account. Detach it from your running campaigns first, with [Set the sender identities](https://docs.emelia.io/docs/campaigns/set-sender-identities.md).