Add SMTP mailbox

Add an SMTP mailbox to the workspace. Credentials are encrypted at rest.

The mailbox is created in inactive status. A background worker verifies the SMTP/IMAP credentials and either flips status to active (success) or deletes the mailbox (failure). After this request, poll GET /v1/mailboxes/{mailboxId}/connection-test until the status is no longer pending.

A DNS check (MX/SPF/DKIM/DMARC) runs automatically and populates setupStatus. Mailbox usage is incremented against the workspace owner's plan limit.

Returns 403 if the workspace owner has no active subscription or has reached the mailbox limit. Returns 409 if a mailbox with the same email already exists in the workspace.

curl -X POST "https://api.sendkit.ai/v1/mailboxes" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
  "email": "sarah@company.com",
  "displayName": "Sarah Johnson",
  "provider": "custom",
  "smtp": {
    "host": "smtp.company.com",
    "port": 587,
    "secure": true,
    "username": "sarah@company.com",
    "password": "app-password-here"
  },
  "imap": {
    "host": "imap.company.com",
    "port": 993,
    "secure": true,
    "username": "sarah@company.com",
    "password": "app-password-here"
  },
  "dailySendLimit": 15,
  "signature": "<p>Best regards,<br>Sarah Johnson</p>",
  "tags": [
    "outreach"
  ]
}'

import requests
import json

url = "https://api.sendkit.ai/v1/mailboxes"
headers = {
  "Content-Type": "application/json",
  "X-Api-Key": "YOUR_API_KEY"
}
data = {
  "email": "sarah@company.com",
  "displayName": "Sarah Johnson",
  "provider": "custom",
  "smtp": {
    "host": "smtp.company.com",
    "port": 587,
    "secure": true,
    "username": "sarah@company.com",
    "password": "app-password-here"
  },
  "imap": {
    "host": "imap.company.com",
    "port": 993,
    "secure": true,
    "username": "sarah@company.com",
    "password": "app-password-here"
  },
  "dailySendLimit": 15,
  "signature": "<p>Best regards,<br>Sarah Johnson</p>",
  "tags": [
    "outreach"
  ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const response = await fetch("https://api.sendkit.ai/v1/mailboxes", {
  method: "POST",
  headers: {
  "Content-Type": "application/json",
  "X-Api-Key": "YOUR_API_KEY"
},
  body: JSON.stringify({
  "email": "sarah@company.com",
  "displayName": "Sarah Johnson",
  "provider": "custom",
  "smtp": {
    "host": "smtp.company.com",
    "port": 587,
    "secure": true,
    "username": "sarah@company.com",
    "password": "app-password-here"
  },
  "imap": {
    "host": "imap.company.com",
    "port": 993,
    "secure": true,
    "username": "sarah@company.com",
    "password": "app-password-here"
  },
  "dailySendLimit": 15,
  "signature": "<p>Best regards,<br>Sarah Johnson</p>",
  "tags": [
    "outreach"
  ]
})
});

const data = await response.json();
console.log(data);

package main

import (
    "fmt"
    "net/http"
    "bytes"
    "encoding/json"
)

func main() {
    data := []byte(`{
  "email": "sarah@company.com",
  "displayName": "Sarah Johnson",
  "provider": "custom",
  "smtp": {
    "host": "smtp.company.com",
    "port": 587,
    "secure": true,
    "username": "sarah@company.com",
    "password": "app-password-here"
  },
  "imap": {
    "host": "imap.company.com",
    "port": 993,
    "secure": true,
    "username": "sarah@company.com",
    "password": "app-password-here"
  },
  "dailySendLimit": 15,
  "signature": "<p>Best regards,<br>Sarah Johnson</p>",
  "tags": [
    "outreach"
  ]
}`)

    req, err := http.NewRequest("POST", "https://api.sendkit.ai/v1/mailboxes", bytes.NewBuffer(data))
    if err != nil {
        panic(err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-Api-Key", "YOUR_API_KEY")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    fmt.Println("Response Status:", resp.Status)
}

require 'net/http'
require 'json'

uri = URI('https://api.sendkit.ai/v1/mailboxes')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['X-Api-Key'] = 'YOUR_API_KEY'
request.body = '{
  "email": "sarah@company.com",
  "displayName": "Sarah Johnson",
  "provider": "custom",
  "smtp": {
    "host": "smtp.company.com",
    "port": 587,
    "secure": true,
    "username": "sarah@company.com",
    "password": "app-password-here"
  },
  "imap": {
    "host": "imap.company.com",
    "port": 993,
    "secure": true,
    "username": "sarah@company.com",
    "password": "app-password-here"
  },
  "dailySendLimit": 15,
  "signature": "<p>Best regards,<br>Sarah Johnson</p>",
  "tags": [
    "outreach"
  ]
}'

response = http.request(request)
puts response.body

{
  "success": true,
  "data": {
    "_id": "665b1c2d3e4f5a6b7c8d9e0f",
    "email": "sarah@company.com",
    "displayName": "Sarah Johnson",
    "provider": "custom",
    "status": "inactive",
    "connectionType": "smtp",
    "dailySendLimit": 15,
    "sendingEnabled": false,
    "signature": "<p>Best regards,<br>Sarah Johnson</p>",
    "tags": [
      "outreach"
    ],
    "smtpHost": "smtp.company.com",
    "smtpPort": 587,
    "smtpSecure": true,
    "imapHost": "imap.company.com",
    "imapPort": 993,
    "imapSecure": true,
    "createdAt": "2025-06-10T10:30:00.000Z",
    "updatedAt": "2025-06-10T10:30:00.000Z"
  },
  "message": "Mailbox queued for SMTP verification. Poll GET /v1/mailboxes/:id/connection-test until status is no longer "inactive"."
}

POST

/v1/mailboxes

POST

API Key (header: X-Api-Key)

X-Api-Keystring

Required

Platform API key (sk_user_...) or Workspace API key (sk_...)

Content-Typestring

Required

The media type of the request body

Options: application/json

emailstring

Required

Mailbox email address (stored lowercase)

Format: email

displayNamestring

Sender display name (defaults to email username)

providerstring

Email provider (default "custom")

Options: gmail, outlook, azure, custom

smtpobject

Required

SMTP server configuration (required)

imapobject

IMAP server configuration (for receiving/replying). If omitted, the SMTP credentials are reused for IMAP.

dailySendLimitinteger

Maximum emails per day (default 15, clamped to 1-50)

Min: 1 • Max: 50

signaturestring

HTML email signature

tagsarray

Tags to assign to the mailbox

Request Preview

Response

Response will appear here after sending the request

Authentication

header

X-Api-Keystring

Required

API Key for authentication. Platform API key (sk_user_...) or Workspace API key (sk_...)

Body

application/json

emailstring

Required

Mailbox email address (stored lowercase)

displayNamestring

Sender display name (defaults to email username)

providerstring

Email provider (default "custom")

Allowed values:gmailoutlookazurecustom

smtpobject

Required

SMTP server configuration (required)

hoststring

Required

SMTP server hostname

portinteger

SMTP port (default 587)

secureboolean

Use SSL/TLS (default true)

SMTP username

SMTP password

IMAP server configuration (for receiving/replying). If omitted, the SMTP credentials are reused for IMAP.

hoststring

IMAP server hostname

portinteger

IMAP port (default 993)

secureboolean

Use SSL/TLS (default true)

usernamestring

passwordstring

dailySendLimitinteger

Maximum emails per day (default 15, clamped to 1-50)

signaturestring

HTML email signature

tagsarray

Tags to assign to the mailbox

Responses

successboolean

dataobject

Mailbox object (credentials excluded)

messagestring

Workspace owner lacks subscription or has hit the mailbox limit

Mailbox with this email already exists

Was this page helpful?

Last updated 4 days ago

Built with Documentation.AI

curl -X POST "https://api.sendkit.ai/v1/mailboxes" \ -H "Content-Type: application/json" \ -H "X-Api-Key: YOUR_API_KEY" \ -d '{ "email": "sarah@company.com", "displayName": "Sarah Johnson", "provider": "custom", "smtp": { "host": "smtp.company.com", "port": 587, "secure": true, "username": "sarah@company.com", "password": "app-password-here" }, "imap": { "host": "imap.company.com", "port": 993, "secure": true, "username": "sarah@company.com", "password": "app-password-here" }, "dailySendLimit": 15, "signature": "Best regards, Sarah Johnson", "tags": [ "outreach" ] }'

{ "success": true, "data": { "_id": "665b1c2d3e4f5a6b7c8d9e0f", "email": "sarah@company.com", "displayName": "Sarah Johnson", "provider": "custom", "status": "inactive", "connectionType": "smtp", "dailySendLimit": 15, "sendingEnabled": false, "signature": "Best regards, Sarah Johnson", "tags": [ "outreach" ], "smtpHost": "smtp.company.com", "smtpPort": 587, "smtpSecure": true, "imapHost": "imap.company.com", "imapPort": 993, "imapSecure": true, "createdAt": "2025-06-10T10:30:00.000Z", "updatedAt": "2025-06-10T10:30:00.000Z" }, "message": "Mailbox queued for SMTP verification. Poll GET /v1/mailboxes/:id/connection-test until status is no longer "inactive"." }