> ## Documentation Index > Fetch the complete documentation index at: https://developer.salesforge.ai/llms.txt > Use this file to discover all available pages before exploring further. # Connect mailbox > Connect an SMTP/IMAP mailbox to the workspace. Send the outgoing server credentials under "smtp" and the incoming server credentials under "imap". Both are verified against the mail provider before anything is stored, so a bad host, port or password fails with 400 and creates nothing; the message names the failing protocol and, where the reason is recognized (wrong credentials, unreachable host, TLS mismatch, ...), a short cause. On success the mailbox is returned with status "pending": registration with the mail infrastructure finishes moments later and flips it to "active", or to "access_lost" if it fails. Poll GET /workspaces/{workspaceID}/mailboxes/{mailboxID} to observe the final status. Connecting is idempotent by address: a second request for an address already mid-connect returns 409 instead of racing the first. Google and Outlook mailboxes connect through /mailboxes/oauth-link instead. ## OpenAPI ````yaml https://api.salesforge.ai/public/v2/swagger/doc.json post /workspaces/{workspaceID}/mailboxes openapi: 3.1.0 info: description: Get mailboxes associated with the workspace. termsOfService: https://www.salesforge.ai/terms title: Salesforge API version: '2.0' servers: - url: https://api.salesforge.ai/public/v2 security: - ApiKeyAuth: [] externalDocs: description: '' url: '' paths: /workspaces/{workspaceID}/mailboxes: post: tags: - mailboxes summary: Connect mailbox description: >- Connect an SMTP/IMAP mailbox to the workspace. Send the outgoing server credentials under "smtp" and the incoming server credentials under "imap". Both are verified against the mail provider before anything is stored, so a bad host, port or password fails with 400 and creates nothing; the message names the failing protocol and, where the reason is recognized (wrong credentials, unreachable host, TLS mismatch, ...), a short cause. On success the mailbox is returned with status "pending": registration with the mail infrastructure finishes moments later and flips it to "active", or to "access_lost" if it fails. Poll GET /workspaces/{workspaceID}/mailboxes/{mailboxID} to observe the final status. Connecting is idempotent by address: a second request for an address already mid-connect returns 409 instead of racing the first. Google and Outlook mailboxes connect through /mailboxes/oauth-link instead. parameters: - description: Workspace ID in: path name: workspaceID required: true schema: type: string requestBody: content: application/json: schema: oneOf: - type: object - $ref: '#/components/schemas/api.CreateMailboxRequest' description: Mailbox connection request summary: request description: Mailbox connection request required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/api.MailboxResponse' description: Mailbox '400': content: application/json: schema: $ref: '#/components/schemas/errors.Error' description: Bad Request '409': content: application/json: schema: $ref: '#/components/schemas/errors.Error' description: Conflict '500': content: application/json: schema: $ref: '#/components/schemas/errors.Error' description: Internal Server Error security: - ApiKeyAuth: [] components: schemas: api.CreateMailboxRequest: properties: address: description: >- Email address to send from. It must not already be connected to another workspace. example: jane@example.com type: string dailyEmailLimit: description: >- Maximum emails this mailbox may send per day. Defaults to 30 when omitted. Values above the limit permitted for the workspace are rejected. example: 30 minimum: 1 type: integer firstName: description: >- First name of the sender, used in the From header of outgoing emails. example: Jane type: string imap: $ref: '#/components/schemas/api.MailboxConnectionRequest' lastName: description: Last name of the sender, used in the From header of outgoing emails. example: Doe type: string signature: description: >- HTML signature appended to outgoing emails. Scored for spam potential on connect; the result is reported on the mailbox rather than blocking the request. type: string smtp: $ref: '#/components/schemas/api.MailboxConnectionRequest' trackingDomain: description: >- Custom domain used to rewrite tracked links and open pixels. It must already have a CNAME pointing at Salesforge example: track.example.com type: string required: - address - firstName - imap - lastName - smtp type: object api.MailboxResponse: properties: address: type: string dailyEmailLimit: type: integer disconnectReason: type: string firstName: type: string id: type: string lastName: type: string mailboxProvider: $ref: '#/components/schemas/models.MailboxProvider' resolvedSignature: type: string signature: type: string status: $ref: '#/components/schemas/models.MailboxStatus' trackingDomain: type: string trackingDomainStatus: $ref: '#/components/schemas/models.TrackingDomainStatus' type: object errors.Error: allOf: - $ref: '#/components/schemas/data' properties: data: {} message: type: string type: object api.MailboxConnectionRequest: properties: host: description: >- Hostname of the mail server. Your mail provider publishes this; it is usually of the form imap.yourprovider.com or smtp.yourprovider.com. example: mail.example.com type: string password: description: >- Password or provider-issued app password for the username above. Sent over TLS, stored encrypted, and never returned by any endpoint. Where your provider supports app passwords, prefer one over the account password so it can be revoked independently. type: string port: description: >- Port the mail server listens on. It also selects how the connection is encrypted: 993 (IMAP) and 465 (SMTP) use implicit TLS, 587 (SMTP) uses STARTTLS. Any other port is attempted with TLS first and retried without strict certificate verification. example: 587 maximum: 65535 minimum: 1 type: integer username: description: >- Username the mail server authenticates with. Often, but not always, the mailbox address — check your provider, as some issue a separate login. example: jane@example.com type: string required: - host - password - port - username type: object models.MailboxProvider: enum: - gmail - outlook - smtp type: string x-enum-varnames: - MailboxProviderGmail - MailboxProviderOutlook - MailboxProviderSmtp models.MailboxStatus: enum: - active - frozen - access_lost - deleted - inactive - pending - suspended type: string x-enum-varnames: - MailboxStatusActive - MailboxStatusFrozen - MailboxStatusAccessLost - MailboxStatusDeleted - MailboxStatusInactive - MailboxStatusPending - MailboxStatusSuspended models.TrackingDomainStatus: enum: - active - pending type: string x-enum-varnames: - TrackingDomainStatusActive - TrackingDomainStatusPending data: properties: data: items: $ref: '#/components/schemas/api.DNCResponse' type: array type: object api.DNCResponse: properties: createdAt: type: string type: $ref: '#/components/schemas/models.DncType' value: type: string type: object models.DncType: enum: - email - domain - linkedin type: string x-enum-varnames: - DncTypeEmail - DncTypeDomain - DncTypeLinkedin securitySchemes: ApiKeyAuth: in: header name: Authorization type: apiKey ````