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

# Connect sending accounts

> Connect the mailboxes and LinkedIn seats your campaigns and inbox send from, set how much they send, and know what they cost.

Campaigns and the inbox send from your sending accounts: mailboxes, connected over SMTP and IMAP, and LinkedIn seats, connected with a sign-in link. Each account costs a fee for every 30 days it stays connected: \$1 a mailbox and \$10 a LinkedIn seat. Every other account call is free.

## Connect a mailbox

Any mailbox that takes a password sign-in over SMTP, to send, and IMAP, to read, can be connected. Send its address, its two servers and its password. Where the provider asks for an app password instead of the account's own, send that. For a Gmail or Google Workspace mailbox, use Gmail's servers and an app password, made in the Google account's security settings:

```bash theme={null}
curl https://api.outbound.dev/v1/accounts/email \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emailAddress": "maya@fernway.co", "name": "Maya Fern", "smtpHost": "smtp.gmail.com", "smtpPort": 465, "imapHost": "imap.gmail.com", "imapPort": 993, "password": "your-app-password"}'
```

```json theme={null}
{
  "channel": "email",
  "id": "maya@fernway.co",
  "emailAddress": "maya@fernway.co",
  "name": "Maya Fern",
  "provider": "smtp",
  "isActive": true,
  "isConnected": true,
  "dailyCapacity": 15,
  "availableCapacity": 15,
  "warmup": { "status": "new" }
}
```

* **Both sign-ins are checked before the mailbox is saved.** That takes about 3 seconds, longer for a slow server: allow two minutes.
* **Ports:** SMTP on 465 with TLS (the default), or on 587 with STARTTLS, sent as `"smtpPort": 587, "smtpSecure": false`. IMAP on 993 with TLS (the default). Send `authUser` when the sign-in name is not the address.
* **The password is kept encrypted** and never shown.
* **The address becomes the mailbox's `id`.** Connecting a mailbox you already have signs it in again and keeps its settings.
* **Its existing mail comes in too.** Once connected, the mailbox's existing mail shows in the inbox routes, not only replies to your campaigns, and any key with the campaigns scope can read it. See [Work the inbox](https://docs.outbound.dev/guides/work-the-inbox.md).
* **Its first 30 days are charged when it connects,** \$1 from your balance, as a fee of its own in your ledger: the call itself is free, and its `X-Balance-Usd` header is read before the fee is charged. When your available balance cannot cover them, the call answers `402` `insufficient_balance` and the mailbox is not connected. Connecting a mailbox whose 30 days are already paid for costs nothing. See [The 30-day fee](#the-30-day-fee). To retry a connect safely, send an [`Idempotency-Key`](https://docs.outbound.dev/idempotency).

When the server turns the sign-in down, the call answers `422` with `smtp_login_rejected`: check the password, and use an app password where the provider asks for one. Mail that Microsoft hosts takes no password sign-in, so it cannot be connected this way: `422` `microsoft_oauth_required`. When every mailbox your organization may connect is connected, another answers `403` `email_account_limit_reached`. Every code is in [Errors](https://docs.outbound.dev/errors.md#accounts).

## Import many mailboxes

`POST /v1/accounts/email/bulk` connects 1 to 250 mailboxes in the background, each written as `POST /v1/accounts/email` takes one:

```bash theme={null}
curl https://api.outbound.dev/v1/accounts/email/bulk \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mailboxes": [{"emailAddress": "maya@fernway.co", "smtpHost": "smtp.gmail.com", "imapHost": "imap.gmail.com", "password": "app-password-one"}, {"emailAddress": "rui@fernway.co", "smtpHost": "smtp.gmail.com", "imapHost": "imap.gmail.com", "password": "app-password-two"}]}'
```

```json theme={null}
{ "totalRows": 2, "connectingRows": 2, "skipped": [] }
```

It answers `202` at once. `skipped` lists the mailboxes it left out before any sign-in, by their place in `mailboxes`, such as a second copy of the same address (`duplicate_in_request`). Then:

1. Call `GET /v1/accounts/email/bulk/status` until `isImporting` is false.
2. List the mailboxes with `GET /v1/accounts?channel=email`. A mailbox whose sign-in failed is not there.

```json theme={null}
{ "isImporting": false, "startedAt": "2026-11-16T14:20:05.000Z" }
```

* **One import runs at a time.** Another while it runs answers `409` `mailbox_import_in_progress`.
* **Each imported mailbox costs the same fee** as one connected alone, charged as it connects. When your available balance cannot cover the first 30 days of every mailbox in the import that is not already paid for, the call answers `402` `insufficient_balance` and none is connected.
* **Imports have their own limit:** 5 a minute and 20 a day.

## Pause and resume a mailbox

Pausing a mailbox stops campaigns sending from it: its `isActive` becomes false.

```bash theme={null}
curl -X POST https://api.outbound.dev/v1/accounts/email/maya@fernway.co/pause \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

It answers `200` with the mailbox. `POST /v1/accounts/email/{accountId}/resume` lets campaigns send from it again. Pausing a paused mailbox, or resuming an active one, changes nothing. A paused mailbox is still connected, so its fee goes on: disconnect it to stop the fee.

The `accountId` in the path is the mailbox's address, in any case, with `@` as it is or as `%40`.

## Set its daily capacity and signature

```bash theme={null}
curl -X PATCH https://api.outbound.dev/v1/accounts/email/maya@fernway.co \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dailyCapacity": 5, "signature": "<p>Maya Fern<br>Fernway</p>"}'
```

It answers `200` with the mailbox.

* **`dailyCapacity`** is the most emails the mailbox sends a day, 1 to 15. A new mailbox starts at 15. Start a mailbox under 3 months old at 5.
* **`availableCapacity`** is what is left of it today. Every email the mailbox sends uses one: campaign emails, test emails, direct messages and replies.
* **`signature`** is HTML, up to 10,000 characters: what `{Sender Signature}` puts in a campaign step. Send it empty to remove it. `GET /v1/accounts` leaves it out: read one mailbox with `GET /v1/accounts/email/{accountId}` to see it.
* **`name`** is the sender name your recipients see.

## Warm a mailbox up

Warmup exchanges emails between your mailbox and other mailboxes, so that mail providers come to trust it. It comes at no charge.

```bash theme={null}
curl https://api.outbound.dev/v1/accounts/email/maya@fernway.co/warmup \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

It answers `200` with the mailbox. Follow the warmup in the mailbox's `warmup`: its `status` (`new`, `warming`, `warmed`, `paused` or `issue`), the days it has run, the warmup emails of the last 7 days and where they landed, and a grade for the domain's mail setup, `dnsGrade`.

* **Warmup sends under the mailbox's sender name.** A mailbox with none answers `409` `mailbox_name_required`: set `name` first.
* **A Gmail mailbox can need a Google app password** for warmup. When a start answers `422` `warmup_app_password_required`, send it again with the app password as `appPassword`. It is used to sign in once, and never kept.
* **Pause it** with `POST /v1/accounts/email/{accountId}/warmup/pause`, and start it again with the same start call. A mailbox whose warmup never started answers `404` `warmup_not_found`.

## Connect a LinkedIn seat

A LinkedIn seat connects through a hosted sign-in page, so you never handle its password or its session:

```bash theme={null}
curl -X POST https://api.outbound.dev/v1/accounts/linkedin/connect-links \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

```json theme={null}
{ "url": "https://auth.example.com/signin/3f9c2a" }
```

**1. Send the link to the seat's owner**

The link is valid for 24 hours. Keep it secret: whoever opens it can connect a seat to your organization.

**2. The owner signs in**

They sign in to LinkedIn on the page the link opens. You never see their password.

**3. Wait for the seat**

Call `GET /v1/accounts?channel=linkedin` until the new seat is listed with `isConnected` true. Its first 30 days, \$10, are charged once it connects.

Making the link answers `402` `insufficient_balance` when your available balance cannot cover a seat's first 30 days. A link that signs an existing seat in again is never refused for that.

* **When every seat your organization may have is in use,** the call answers `403` `linkedin_account_limit_reached`.
* **When LinkedIn ends a seat's session,** its `isConnected` becomes false. `POST /v1/accounts/linkedin/{accountId}/reconnect-links` makes a link that signs it in again; then read the seat until `isConnected` is true. Signing in again costs nothing while the seat's 30 days are paid for.
* **A seat's limits** are set with `PATCH /v1/accounts/linkedin/{accountId}`, as `dailyLimits` and `weeklyLimits`, each with `invitations` and `messages`. A free seat allows up to 20 invitations and 80 messages a day, and 100 and 400 a week; a premium seat up to 80 and 150 a day, and 200 and 800 a week. Limits above that answer `422`.

```bash theme={null}
curl -X PATCH https://api.outbound.dev/v1/accounts/linkedin/sBzWb1QeTTqF0vUpHKa2xg \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dailyLimits": {"invitations": 15, "messages": 60}, "weeklyLimits": {"invitations": 75, "messages": 300}}'
```

## List your accounts

```bash theme={null}
curl "https://api.outbound.dev/v1/accounts?channel=email" \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

```json theme={null}
{
  "accounts": [
    {
      "channel": "email",
      "id": "maya@fernway.co",
      "emailAddress": "maya@fernway.co",
      "name": "Maya Fern",
      "provider": "smtp",
      "isActive": true,
      "isConnected": true,
      "dailyCapacity": 5,
      "availableCapacity": 3,
      "warmup": { "status": "warming", "startedAt": "2026-11-02T09:00:00.000Z", "daysActive": 12, "last7Days": { "sent": 84, "inbox": 81, "spam": 3 }, "dnsGrade": "A" }
    }
  ]
}
```

`GET /v1/accounts` lists your mailboxes and LinkedIn seats, or one kind with `channel` (`email` or `linkedin`). For each, `isActive` says whether campaigns may send from it, and `isConnected` whether its sign-in works. `GET /v1/accounts/{channel}/{accountId}` reads one account, with its signature; a seat also shows its daily and weekly limits, with what is left of them.

## Disconnect an account

```bash theme={null}
curl -X DELETE https://api.outbound.dev/v1/accounts/email/maya@fernway.co \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

It answers `204`, and campaigns stop sending from the account. Disconnecting a mailbox also drops the emails synced from it and its warmup. Disconnect a seat the same way, with `linkedin` and its `id` in the path. Disconnecting an account again answers `404` `account_not_found`.

## The 30-day fee

| Account | Fee |
| - | - |
| A mailbox | \$1 for each 30 days it stays connected |
| A LinkedIn seat | \$10 for each 30 days it stays connected |

* **When an account connects,** its first 30 days are charged from your balance. Connecting or importing mailboxes, and making a LinkedIn sign-in link, answer `402` `insufficient_balance` when your available balance cannot cover them as the call arrives, and nothing is connected.
* **A first fee is not given time.** If other calls spend the balance before the account connects, it is disconnected the next time fees are charged, usually within 15 minutes, and your billing email hears about it.
* **Every 30 days after,** it is charged again while it stays connected. An account that is gone or signed out by then stops costing anything.
* **A renewal your balance cannot cover** is tried again each day, and your billing email hears about it. An account whose renewal is still unpaid 3 days after the first try is disconnected, and campaigns stop sending from it.
* **Disconnecting stops the fee.** Days already paid for are not refunded. Connecting the account again before they run out costs nothing more; connecting it again later starts a new 30 days.

Fees show in your ledger, `GET /v1/wallet/transactions`, under the product `connections`. See [Pricing and billing](https://docs.outbound.dev/billing.md#how-a-sending-account-is-charged).

## Keys and limits

* **Keys.** Account calls need a key with the connections scope. Read-only keys can list and read accounts and the import status. Connecting, changing and disconnecting need a key that can write.
* **Rate limits.** `GET /v1/accounts` and the import status share one [rate limit](https://docs.outbound.dev/rate-limits.md): 120 calls a minute and 10,000 a day. The other account calls share another, 20 a minute and 600 a day, and imports have their own, 5 a minute and 20 a day.


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