Update IMAP email account

Fully updates an existing IMAP email account. This is a full replacement operation - all fields must be provided.

Important Restrictions:

Only IMAP/SMTP accounts can be updated via API
Attempting to update OAuth accounts (Google, Office365) will result in a 403 Forbidden error
OAuth accounts must be updated through the web application for security reasons

Update Process:

All fields must be provided (this replaces the entire account configuration)
Email address can be changed (must remain unique within workspace)
Server settings (IMAP/SMTP) can be updated
Passwords can be updated by providing new values

Validation:

Same validation rules apply as for account creation
Email must be unique if changed
All required fields must be present

Response:

Returns the updated account with all details (excluding passwords)
Account status may change based on new configuration

PUT/administration/email-accounts/{id}

Authorization

AuthorizationOAuth2 access token · headerrequired

Scopes:api:write

AuthorizationBearer token (JWT) · headerrequired

Path parameters

idstringrequired

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

200Email account updated 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

403OAuth accounts cannot be updated via API

404Email account not found

Request

curl -X PUT "https://leadtime.app/api/public/administration/email-accounts/string" \
  -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/string", {
  method: "PUT",
  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.put(
    "https://leadtime.app/api/public/administration/email-accounts/string",
    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"
}