> ## 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 mailboxes in bulk

> Connects 1 to 250 mailboxes in the background, each as `POST /v1/accounts/email` takes one. It answers `202` at once with the mailboxes it left out before any sign-in (`skipped`, by their place in `mailboxes`). Follow it with `GET /v1/accounts/email/bulk/status`, then list the mailboxes with `GET /v1/accounts?channel=email`: one whose sign-in failed is not there.

One import runs at a time: another while it runs answers `409` `mailbox_import_in_progress`. Imports have their own limit, 5 a minute and 20 a day.

**Price:** \$1 a mailbox for each 30 days it stays connected, charged from your balance once it connects and then every 30 days. Your balance must cover the first 30 days of each new account when you call, or the call answers `402` `insufficient_balance` and connects nothing. An account whose first 30 days your balance no longer covers once it connects (another call spent it first) is disconnected at the next fee run, usually within 15 minutes, instead of charged. A later fee your balance cannot cover is tried again each day; still unpaid after 3 days, the account is disconnected. The call itself is free. **Scope:** connections, with a key that can write.



## OpenAPI

````yaml /openapi.json post /v1/accounts/email/bulk
openapi: 3.1.0
info:
  title: outbound.dev API
  version: v1
  description: Find people and companies, and see what every call costs, with one API key.
servers:
  - url: https://api.outbound.dev
security: []
tags:
  - name: People
    description: >-
      Search people with filters, a saved search or a plain-language query,
      count matches and look up filter values.
  - name: Companies
    description: >-
      Search companies, count matches, name one company by its name, domain or
      LinkedIn page, and list its people.
  - name: Saved searches
    description: Keep a search under a title and run it again, for people or for companies.
  - name: Lists
    description: >-
      Keep people or companies in lists: create and change lists, page through
      their rows, and add or remove people.
  - name: Folders
    description: Group lists of one kind into folders.
  - name: Enrichment
    description: >-
      Find people's work emails and phone numbers: one person, a batch of
      people, or a list.
  - name: Jobs
    description: >-
      Long tasks a call started: their progress, what they produced and what
      they were charged, and stopping them.
  - name: Accounts
    description: >-
      Connect the mailboxes and LinkedIn seats that campaigns and the inbox send
      from, and look after them.
  - name: Campaigns
    description: >-
      Email and LinkedIn campaigns: their steps, the people they enroll, their
      queue of messages, templates, the knowledge hubs and writing styles AI
      steps are written from, the tracking domain their links go through, and
      the lists every campaign leaves out.
  - name: Inbox
    description: >-
      Read and answer the conversations of your mailboxes and LinkedIn seats,
      and send new messages and invitations.
  - name: Account
    description: >-
      The calling key and its organization, its rate limits, and revoking the
      key.
  - name: Billing
    description: The balance, the ledger of every change to it, and the price list.
  - name: Usage and requests
    description: >-
      Calls and spend by day, and the record of every request of the last 30
      days.
paths:
  /v1/accounts/email/bulk:
    post:
      tags:
        - Accounts
      summary: Connect mailboxes in bulk
      description: >-
        Connects 1 to 250 mailboxes in the background, each as `POST
        /v1/accounts/email` takes one. It answers `202` at once with the
        mailboxes it left out before any sign-in (`skipped`, by their place in
        `mailboxes`). Follow it with `GET /v1/accounts/email/bulk/status`, then
        list the mailboxes with `GET /v1/accounts?channel=email`: one whose
        sign-in failed is not there.


        One import runs at a time: another while it runs answers `409`
        `mailbox_import_in_progress`. Imports have their own limit, 5 a minute
        and 20 a day.


        **Price:** \$1 a mailbox for each 30 days it stays connected, charged
        from your balance once it connects and then every 30 days. Your balance
        must cover the first 30 days of each new account when you call, or the
        call answers `402` `insufficient_balance` and connects nothing. An
        account whose first 30 days your balance no longer covers once it
        connects (another call spent it first) is disconnected at the next fee
        run, usually within 15 minutes, instead of charged. A later fee your
        balance cannot cover is tried again each day; still unpaid after 3 days,
        the account is disconnected. The call itself is free. **Scope:**
        connections, with a key that can write.
      operationId: postAccountsEmailBulk
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            Names this operation, so a retry with the same key and body gets the
            first success again, marked `Idempotent-Replayed`, instead of
            running or charging twice. A mailbox's `password` is not compared:
            the same mailbox sent again with another password is the same call,
            and gets the first answer. Kept 24 hours for your organization and
            this route. A refusal (`4xx`) frees the key at once, so a corrected
            retry runs. After a server error (`5xx`), which may still take
            effect, the key stays held for 5 minutes from the call's start, and
            a retry in that time answers `409` `idempotency_in_progress`; after
            that, a send or import that may already have gone out answers `409`
            `idempotency_outcome_unknown` instead of running again. 1 to 255
            visible ASCII characters, such as a UUID.
          schema:
            type: string
            minLength: 1
            maxLength: 255
            pattern: ^[\x21-\x7E]+$
          example: 5f1c9d2e-8a4b-4e7c-9f30-6b2a1d8e4c75
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mailboxes:
                  type: array
                  description: >-
                    1 to 250 mailboxes, each as `POST /v1/accounts/email` takes
                    one.
                  minItems: 1
                  maxItems: 250
                  items:
                    type: object
                    properties:
                      emailAddress:
                        type: string
                        description: >-
                          The mailbox's address. It becomes the account's `id`,
                          in lower case.
                        maxLength: 320
                      name:
                        type: string
                        description: The sender name, for a new mailbox.
                        maxLength: 200
                      smtpHost:
                        type: string
                        description: The outgoing (SMTP) server, such as `smtp.fernway.co`.
                      smtpPort:
                        type: number
                        description: 465 (the default) for TLS, or 587 for STARTTLS.
                      smtpSecure:
                        type: boolean
                        description: >-
                          True (the default) for TLS on port 465, false for
                          STARTTLS on 587.
                      imapHost:
                        type: string
                        description: The incoming (IMAP) server, such as `imap.fernway.co`.
                      imapPort:
                        type: number
                        description: 993 (the default).
                      imapSecure:
                        type: boolean
                        description: True (the default) for TLS.
                      authUser:
                        type: string
                        description: The sign-in name, when it is not `emailAddress`.
                        maxLength: 320
                      password:
                        type: string
                        description: >-
                          The mailbox's password, or an app password where the
                          provider asks for one. Checked by signing in, kept
                          encrypted, never shown.
                        minLength: 1
                        maxLength: 1024
                    required:
                      - emailAddress
                      - smtpHost
                      - imapHost
                      - password
              required:
                - mailboxes
            example:
              mailboxes:
                - emailAddress: maya@fernway.co
                  smtpHost: smtp.fernway.co
                  imapHost: imap.fernway.co
                  password: app-password
                - emailAddress: rui@fernway.co
                  smtpHost: smtp.fernway.co
                  imapHost: imap.fernway.co
                  password: app-password
      responses:
        '202':
          description: >-
            The import, started: how many mailboxes it is connecting, and those
            it left out at once.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            X-Charged-Usd:
              $ref: '#/components/headers/ChargedUsd'
            X-Balance-Usd:
              $ref: '#/components/headers/BalanceUsd'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                type: object
                required:
                  - totalRows
                  - connectingRows
                  - skipped
                properties:
                  totalRows:
                    type: integer
                    description: Mailboxes sent.
                  connectingRows:
                    type: integer
                    description: Mailboxes being connected in the background.
                  skipped:
                    type: array
                    description: >-
                      Mailboxes left out before any sign-in, by their place in
                      `mailboxes`.
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                          description: From 0.
                        reason:
                          type: string
                          description: >-
                            `duplicate_in_request`,
                            `email_account_already_connected`,
                            `microsoft_oauth_required` or
                            `email_account_limit_reached`.
              example:
                totalRows: 3
                connectingRows: 2
                skipped:
                  - index: 2
                    reason: duplicate_in_request
        '429':
          $ref: '#/components/responses/RateLimited'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
        - apiKey: []
components:
  headers:
    RequestId:
      description: The request's id. Quote it when you write to support.
      schema:
        type: string
        example: req_6a1f0c2b9d4e8a7f3c5b2e10
    ChargedUsd:
      description: What this call cost, in US dollars as an exact six-decimal string.
      schema:
        type: string
        example: '0.005000'
    BalanceUsd:
      description: >-
        The organization's balance after this call, in US dollars as an exact
        six-decimal string.
      schema:
        type: string
        example: '9.995000'
    RateLimitLimit:
      description: >-
        The calls allowed in the window of the route's limit with the fewest
        calls left.
      schema:
        type: integer
        example: 20
    RateLimitRemaining:
      description: The calls left in that window.
      schema:
        type: integer
        example: 19
    RateLimitReset:
      description: Seconds until that window resets.
      schema:
        type: integer
        example: 42
    IdempotentReplayed:
      description: >-
        `true` on an answer given again for an `Idempotency-Key`: it is the
        first call's, and nothing ran or was charged this time. Absent
        otherwise.
      schema:
        type: string
        enum:
          - 'true'
    RetryAfter:
      description: Seconds to wait before calling again.
      schema:
        type: integer
        example: 42
  responses:
    RateLimited:
      description: >-
        Too many calls. Wait the seconds in Retry-After, then call again. When
        the limit reached does not say when it resets, such as a mail provider's
        own limit on a mailbox, Retry-After is 60. The RateLimit headers
        describe this API's own limits, so they come only with a 429 one of
        those gave. The body is empty.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
    Error:
      description: The request was refused. The body names the reason in `error.code`.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: >-
        Something failed on our side and nothing was charged. Retry with
        backoff; quote X-Request-Id if it persists. The body is empty.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - doc_url
          properties:
            code:
              type: string
              description: >-
                Stable and machine-readable: branch on it. It never changes
                meaning.
            message:
              type: string
              description: >-
                A human-readable explanation for logs. It may be reworded at any
                time.
            param:
              type: string
              description: The request field the error is about, when there is one.
            doc_url:
              type: string
              description: The code's entry in the errors reference.
            request_id:
              type: string
              description: >-
                The request's id, as in the X-Request-Id header. Quote it to
                support.
      example:
        error:
          code: insufficient_balance
          message: Your balance cannot cover this call. Add funds and try again.
          doc_url: https://docs.outbound.dev/errors#insufficient_balance
          request_id: req_6a1f0c2b9d4e8a7f3c5b2e10
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        An API key from the console, starting `ob_live_`, sent as
        `Authorization: Bearer <key>`.

````

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