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). SendauthUserwhen 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-Usdheader is read before the fee is charged. When your available balance cannot cover them, the call answers402insufficient_balanceand 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 anIdempotency-Key.
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:
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:
- Call
GET /v1/accounts/email/bulk/statusuntilisImportingis false. - 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
409mailbox_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
402insufficient_balanceand 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: itsisActive becomes false.
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
200 with the mailbox.
dailyCapacityis 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.availableCapacityis what is left of it today. Every email the mailbox sends uses one: campaign emails, test emails, direct messages and replies.signatureis HTML, up to 10,000 characters: what{Sender Signature}puts in a campaign step. Send it empty to remove it.GET /v1/accountsleaves it out: read one mailbox withGET /v1/accounts/email/{accountId}to see it.nameis 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.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
409mailbox_name_required: setnamefirst. - A Gmail mailbox can need a Google app password for warmup. When a start answers
422warmup_app_password_required, send it again with the app password asappPassword. 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 answers404warmup_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.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
403linkedin_account_limit_reached. - When LinkedIn ends a seat’s session, its
isConnectedbecomes false.POST /v1/accounts/linkedin/{accountId}/reconnect-linksmakes a link that signs it in again; then read the seat untilisConnectedis 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}, asdailyLimitsandweeklyLimits, each withinvitationsandmessages. 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 answer422.
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
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
402insufficient_balancewhen 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.
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/accountsand 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.