Skip to main content
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:
  • 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.
  • 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. To retry a connect safely, send an Idempotency-Key.
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.

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:
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.
  • 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.
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

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.
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:
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.

List your accounts

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

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

  • 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.

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: 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.