Create IMAP email account

Creates a new IMAP/SMTP email account for sending and receiving emails.

Important Restrictions:

Only IMAP/SMTP accounts can be created via API
OAuth accounts (Google, Office365) must be configured through the web application for security reasons

Required Configuration:

Email address (must be unique within the workspace)
IMAP server settings (host, port, username, password) for receiving emails
SMTP server settings (host, port, username, password) for sending emails
Optional display name for the account

Validation:

Email address must be valid and unique within the workspace
Ports must be between 1-65535
All server configuration fields are required

Response:

Returns the created account with all details (excluding passwords)
Account status will be set to “active” upon successful creation

POST/administration/email-accounts

Authorization

AuthorizationOAuth2 access token · headerrequired

Scopes:api:write

AuthorizationBearer token (JWT) · headerrequired

Query parameters

fieldsToReturnstring

Comma-separated list of top-level response fields to return. Overrides the endpoint compact default unless responseShape=full is used.

responseShapestring

Advanced override. Omit for the endpoint compact default. Use full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.

Allowed:compactfull

Header parameters

LT-Response-Shapestring

Advanced override. Set to full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.

Allowed:full

Request body

requiredapplication/json

displayNamestring

Optional display name for the email account. This name will be shown in the email account list and may be used as the sender name when sending emails.

emailstringrequired

Email address for the account. Must be unique within the workspace and will be used for sending and receiving emails.

imapsHoststringrequired

IMAP server hostname for receiving emails. This is the server address where the email client connects to retrieve incoming emails (e.g., "imap.gmail.com" for Gmail, "outlook.office365.com" for Office365).

imapsPasswordstringrequired

Password for authenticating with the IMAP server. For some providers, you may need to use an app-specific password instead of your regular account password. This field is never returned in API responses for security reasons.

imapsPortnumberrequired

IMAP server port number. Typically 993 for SSL/TLS connections or 143 for unencrypted connections. Must be between 1-65535.

min 1 · max 65535

imapsUserstringrequired

Username for authenticating with the IMAP server. This is typically the full email address, but may vary depending on your email provider.

smtpHoststringrequired

SMTP server hostname for sending emails. This is the server address where the email client connects to send outgoing emails (e.g., "smtp.gmail.com" for Gmail, "smtp.office365.com" for Office365).

smtpPasswordstringrequired

Password for authenticating with the SMTP server. For some providers, you may need to use an app-specific password instead of your regular account password. This field is never returned in API responses for security reasons.

smtpPortnumberrequired

SMTP server port number. Typically 587 for STARTTLS, 465 for SSL/TLS, or 25 for unencrypted connections. Must be between 1-65535.

min 1 · max 65535

smtpUserstringrequired

Username for authenticating with the SMTP server. This is typically the full email address, but may vary depending on your email provider.

Responses

201Email account created successfully

capabilitiesobjectrequired

Account capabilities indicating what operations can be performed via API. Includes restrictions for OAuth accounts.

Show properties

canDeletebooleanrequired

Whether the account can be deleted via API. This is `true` for all account types, including OAuth accounts.

canEditbooleanrequired

Whether the account can be edited via API. This is `true` for IMAP accounts and `false` for OAuth accounts (Google, Office365) which must be managed through the web application for security reasons.

reasonstring

Optional reason explaining why certain operations are restricted. This field is only present for OAuth accounts to explain why they cannot be created or updated via API.

createdAtstring<date-time>required

ISO 8601 timestamp indicating when the account was created

displayNameobject

Optional display name for the email account. This name will be shown in the email account list and may be used as the sender name when sending emails.

editedAtstring<date-time>required

ISO 8601 timestamp indicating when the account was last modified

emailstringrequired

Email address associated with this account. Used for sending and receiving emails.

idstring<uuid>required

Unique identifier (UUID) of the email account

lastErrorobject

Most recent error message, if the account has encountered any issues. This helps diagnose connection or authentication problems.

statusobjectrequired

Current operational status of the account. Indicates whether the account is working correctly or has encountered issues.

Show properties

object

typestringrequired

Type of email account. Determines how the account is authenticated and what operations are available via API.

Allowed:imapgoogleoffice365

400Invalid input data

401Unauthorized - Invalid or missing authentication token

403Forbidden - Insufficient API scopes or permissions

Request

curl -X POST "https://leadtime.app/api/public/administration/email-accounts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "displayName": "Support Team",
  "email": "support@example.com",
  "imapsHost": "imap.example.com",
  "imapsPassword": "secure-password",
  "imapsPort": 993,
  "imapsUser": "support@example.com",
  "smtpHost": "smtp.example.com",
  "smtpPassword": "secure-password",
  "smtpPort": 587,
  "smtpUser": "support@example.com"
}'

const response = await fetch("https://leadtime.app/api/public/administration/email-accounts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "displayName": "Support Team",
  "email": "support@example.com",
  "imapsHost": "imap.example.com",
  "imapsPassword": "secure-password",
  "imapsPort": 993,
  "imapsUser": "support@example.com",
  "smtpHost": "smtp.example.com",
  "smtpPassword": "secure-password",
  "smtpPort": 587,
  "smtpUser": "support@example.com"
})
});

import requests

response = requests.post(
    "https://leadtime.app/api/public/administration/email-accounts",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Content-Type": "application/json"
    },
    json={
  "displayName": "Support Team",
  "email": "support@example.com",
  "imapsHost": "imap.example.com",
  "imapsPassword": "secure-password",
  "imapsPort": 993,
  "imapsUser": "support@example.com",
  "smtpHost": "smtp.example.com",
  "smtpPassword": "secure-password",
  "smtpPort": 587,
  "smtpUser": "support@example.com"
},
)

Response

{
  "capabilities": {
    "canDelete": true,
    "canEdit": true,
    "reason": "OAuth accounts can only be managed through the web application"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "displayName": "Support Team",
  "editedAt": "2024-01-20T14:45:00Z",
  "email": "support@example.com",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "lastError": "Failed to connect to SMTP server",
  "status": "active",
  "type": "imap"
}