Settings

Set setting values

Set setting values for specific keys. Masked credential values ("******") read from GET /v1/settings are not accepted: a masked value that matches the stored one is skipped as unchanged, any other value carrying the mask is refused. Send the real credential, or leave the key out to keep the stored value.

post/v1/settings

Request

  • Base URL: https://your-emailengine-host
  • URL: https://your-emailengine-host/v1/settings
  • Auth: HTTP bearer

Headers

x-ee-timeoutinteger

Request timeout in milliseconds. Raises the command timeout above the EENGINE_TIMEOUT default for a long-running request; a value below the default has no effect

Example:30000

Request body

webhooksEnabledboolean

Enable or disable webhook delivery for all accounts

webhooksstring

Target URL that will receive webhook notifications via POST requests

webhookEventsstring[]

List of event types that will trigger webhook notifications

notifyHeadersstring[]

Email headers to include in webhook payloads for additional context

serviceUrlstring

Base URL of this EmailEngine instance (used for generating public URLs, path component is ignored)

notificationBaseUrlstring nullable

Public callback URL for external OAuth providers. Falls back to serviceUrl if not set

trackClicksboolean

Rewrite links in outgoing HTML emails to track click-through rates

trackOpensboolean

Insert a tracking pixel in outgoing HTML emails to detect when messages are opened

imapIndexer'full' | 'fast'

How much of a mailbox EmailEngine tracks on each sync

resolveGmailCategoriesboolean

Automatically detect and categorize Gmail tabs (Primary, Social, Promotions, etc.) for IMAP connections

ignoreMailCertErrorsboolean

Allow connections to mail servers with self-signed or invalid TLS certificates (not recommended for production)

generateEmailSummaryboolean

Generate AI-powered summaries for incoming emails using OpenAI

openAiAPIKeystring

Your OpenAI API key for AI features

openAiModelstring

Model name for AI processing. Empty means the built-in default, gpt-6-luna

openAiAPIUrlstring

Base URL for the OpenAI API

openAiTemperaturenumber

Controls randomness in AI responses (0 = deterministic, 2 = very creative). Not sent to a reasoning model while it reasons

openAiTopPnumber

Nucleus sampling parameter for AI text generation (0-1, lower = more focused). Not sent to a reasoning model while it reasons

openAiReasoningEffort'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'

Reasoning effort for reasoning models such as GPT-5 and later. Empty sends "low" to those models and nothing to others. A value the model refuses is dropped

openAiMaxTokensnumber

Token budget for the prompt sent to the model, the instructions and the email together. The email text is cut to fit. Defaults to 30000

openAiPromptstring

Instructions for the AI, sent as the system message ahead of the email. They say which JSON properties to return. Empty means the built-in instructions

inboxNewOnlyboolean

Trigger "messageNew" webhooks only for messages arriving in the Inbox folder

serviceSecretstring

HMAC secret for signing API requests and validating webhooks

authServerstring

External authentication service URL for retrieving mailbox credentials dynamically

tokenAuditLogboolean

Record which requests each access token makes, readable at GET /v1/tokens/{token}/log. Disabled by default, and entries only exist from the point it is enabled

proxyEnabledboolean

Route all outbound connections through a proxy server: IMAP and SMTP sessions as well as HTTP/HTTPS requests (Gmail API, Microsoft Graph, OAuth2 token exchange, webhooks, license validation) unless a dedicated HTTP proxy is configured

proxyUrlstring

Proxy server URL for outbound connections

httpProxyEnabledboolean

Route outbound HTTP/HTTPS requests (webhooks, OAuth2 token exchange, Gmail API and Microsoft Graph calls, license validation) through a dedicated proxy instead of the global proxy

httpProxyUrlstring

Dedicated proxy URL for outbound HTTP/HTTPS requests. When not set, HTTP/HTTPS requests use the global proxy

smtpEhloNamestring nullable

Hostname to use in SMTP EHLO/HELO commands (defaults to system hostname)

notifyTextboolean

Include plain text message content in webhook payloads

notifyWebSafeHtmlboolean

Sanitize HTML content to remove potentially dangerous elements before including in webhooks, and fold quoted thread history into a collapsed block

notifyTextSizeinteger

Maximum size (in bytes) of text content to include in webhook payloads

notifyAttachmentsboolean

Include attachment data in webhook payloads

notifyAttachmentSizeinteger

Maximum size (in bytes) per attachment to include in webhook payloads

notifyCalendarEventsboolean

Include parsed calendar event data in webhook payloads

mcpEnabledboolean

Enable the MCP (Model Context Protocol) endpoint at /mcp, which lets AI agents work with the connected email accounts using access tokens. Disabled by default

mcpOAuthEnabledboolean

Enable the built-in OAuth2 authorization server for the MCP endpoint, used by MCP clients that cannot be configured with a static access token. Requires mcpEnabled and a configured serviceUrl. Disabled by default

sentryEnabledboolean

Send unhandled error reports to a Sentry server. Applied at runtime, no restart needed. Ignored when the SENTRY_DSN environment variable is set

sentryDsnstring nullable

Sentry DSN to send error reports to. If empty, reports go to the Sentry instance run by the EmailEngine developers

imapStrategy'default' | 'dedicated' | 'random'

IP address selection strategy for mailbox access when multiple local addresses are available: IMAP sessions, Gmail API and MS Graph requests, and the OAuth2 token requests of every account. The key keeps its historical name

smtpStrategy'default' | 'dedicated' | 'random'

IP address selection strategy for sending over SMTP when multiple local addresses are available

localAddressesstring[]

List of local IP addresses to use for outbound connections (requires appropriate network configuration)

smtpServerEnabledboolean

Enable the built-in SMTP server for receiving emails

smtpServerPortinteger

Port number for the built-in SMTP server

smtpServerHoststring

IP address to bind the SMTP server to (empty = all interfaces)

smtpServerProxyboolean

Enable PROXY protocol support for the SMTP server. The PROXY header is accepted from any peer, so the port must only be reachable through the proxy

smtpServerAuthEnabledboolean

Require SMTP authentication for incoming connections

smtpServerPasswordstring nullable

Password for SMTP authentication (null = disable authentication)

smtpServerTLSEnabledboolean

Serve the SMTP submission server over implicit TLS. STARTTLS is never offered

tlsProvisioning'acme' | 'manual' | 'self-signed'

Where the TLS certificate for the built-in listeners comes from: "acme" orders one from Let's Encrypt, "manual" uses the certificate uploaded through the admin UI, "self-signed" stops trying to get a real one

tlsHostnamesstring[]

Additional hostnames to hold certificates for, beyond the Service URL hostname. Each one is ordered separately and served over SNI, so a mail client connecting to smtp.example.com is offered a certificate for that name

apiTLSCertificatestring nullable

The certificate the Admin UI and API presents by default (to a client that names no host, and for every name the certificate covers). "auto" lets EmailEngine decide: the material from EENGINE_API_TLS_* when it is set, otherwise the certificate for the Service URL hostname. Otherwise an id from the TLS Certificates page: "manual", "self-signed", "acme:<hostname>", or "env:api" / "env:smtp" / "env:imapProxy". A name the default does not cover is still served its own certificate

smtpServerTLSCertificatestring nullable

The certificate the SMTP server presents by default (to a client that names no host, and for every name the certificate covers). "auto" lets EmailEngine decide: the material from EENGINE_SMTP_TLS_* when it is set, otherwise the certificate for the Service URL hostname. Otherwise an id from the TLS Certificates page: "manual", "self-signed", "acme:<hostname>", or "env:api" / "env:smtp" / "env:imapProxy". A name the default does not cover is still served its own certificate

imapProxyServerTLSCertificatestring nullable

The certificate the IMAP proxy presents by default (to a client that names no host, and for every name the certificate covers). "auto" lets EmailEngine decide: the material from EENGINE_IMAPPROXY_TLS_* when it is set, otherwise the certificate for the Service URL hostname. Otherwise an id from the TLS Certificates page: "manual", "self-signed", "acme:<hostname>", or "env:api" / "env:smtp" / "env:imapProxy". A name the default does not cover is still served its own certificate

imapProxyServerEnabledboolean

Enable the IMAP proxy server

imapProxyServerPortinteger

Port number for the IMAP proxy server

imapProxyServerHoststring

IP address to bind the IMAP proxy to (empty = all interfaces)

imapProxyServerProxyboolean

Enable PROXY protocol support for the IMAP proxy. The PROXY header is accepted from any peer, so the port must only be reachable through the proxy

imapProxyServerPasswordstring nullable

Password for IMAP proxy authentication (null = disable authentication)

imapProxyServerTLSEnabledboolean

Enable TLS support for the IMAP proxy

queueKeepinteger

Number of completed and failed queue entries to retain for debugging

deliveryAttemptsinteger

Maximum number of delivery attempts before marking a message as permanently failed

gmailSubscriptionTtlinteger

Gmail Pub/Sub subscription inactivity expiration in days. Empty for Google default (31 days), 0 for no expiration.

templateHeaderstring

Custom HTML to inject at the top of hosted pages (e.g., for branding)

templateHtmlHeadstring

Custom HTML to inject into the <head> section of hosted pages (e.g., for analytics)

scriptEnvstring

JSON object containing environment variables available to pre-processing scripts

enableApiProxyboolean

Trust X-Forwarded-* headers when behind a reverse proxy

locale'en' | 'et' | 'fr' | 'de' | 'pl' | 'ja' | 'nl' | 'sv' | 'es' | 'it' | 'tr'

Default language/locale for the user interface

timezonestring

Default timezone for date/time display (IANA timezone identifier)

pageBrandNamestring nullable

Brand name displayed in page titles

openAiPreProcessingFnstring

JavaScript function to filter emails before AI processing (return true to process, false to skip)

imapClientNamestring

Client name advertised via IMAP ID extension

imapClientVersionstring

Client version advertised via IMAP ID extension

imapClientVendorstring

Vendor name advertised via IMAP ID extension

imapClientSupportUrlstring

Support URL advertised via IMAP ID extension

exportMaxConcurrentinteger

Maximum concurrent exports per account

exportMaxGlobalConcurrentinteger

Maximum concurrent exports system-wide across all accounts

gmailExportBatchSizeinteger

Number of parallel message fetch requests for Gmail export operations (default: 10, max: 50)

outlookExportBatchSizeinteger

Number of messages per batch request for Outlook export operations (default: 20, max: 20 - MS Graph API limit)

exportMaxMessagesinteger

Maximum number of messages per export (default: 500000)

exportMaxSizeinteger

Maximum export file size in bytes (default: 10GB)

exportMaxMessageSizeinteger

Maximum size of a single message included in an export, in bytes. Larger messages are skipped (default: 50MB)

exportMaxAgeinteger

How long a finished export is kept before it is deleted, in milliseconds (default: 24 hours)

Example request

{
  "webhooks": "https://api.example.com/email/webhooks",
  "webhookEvents": [
    "messageNew"
  ],
  "webhooksCustomHeaders": [
    {
      "key": "Authorization",
      "value": "Bearer <token>"
    }
  ],
  "notifyHeaders": [
    "List-ID"
  ],
  "serviceUrl": "https://emailengine.example.com",
  "notificationBaseUrl": "https://emailengine.example.com/notifications",
  "imapIndexer": "full",
  "openAiAPIKey": "sk-…",
  "openAiModel": "gpt-6-luna",
  "openAiAPIUrl": "https://api.openai.com",
  "openAiTemperature": 0.8,
  "openAiTopP": 0.1,
  "openAiReasoningEffort": "low",
  "openAiMaxTokens": 30000,
  "openAiPrompt": "Return a JSON object with the property \"language\", the ISO 639-1 code of the language the email is written in.",
  "serviceSecret": "verysecret",
  "authServer": "https://api.example.com/email/auth",
  "proxyUrl": "socks5://proxy.example.com:1080",
  "httpProxyUrl": "http://proxy.example.com:8080",
  "smtpEhloName": "relay.example.com",
  "notifyTextSize": 1048576,
  "notifyAttachmentSize": 5242880,
  "logs": {
    "maxLogLines": 10000
  },
  "sentryDsn": "https://public-key@sentry.example.com/1",
  "localAddresses": [
    "198.51.100.24"
  ],
  "smtpServerPort": 2525,
  "smtpServerHost": "0.0.0.0",
  "smtpServerPassword": "verysecret",
  "tlsProvisioning": "acme",
  "tlsHostnames": [
    "smtp.example.com"
  ],
  "apiTLSCertificate": "auto",
  "smtpServerTLSCertificate": "auto",
  "imapProxyServerTLSCertificate": "auto",
  "imapProxyServerPort": 9993,
  "imapProxyServerHost": "0.0.0.0",
  "imapProxyServerPassword": "verysecret",
  "queueKeep": 50,
  "deliveryAttempts": 10,
  "gmailSubscriptionTtl": 31,
  "templateHeader": "<div class=\"brand-bar\">Acme Mail</div>",
  "templateHtmlHead": "<link rel=\"stylesheet\" href=\"https://example.com/brand.css\">",
  "scriptEnv": "{\"key\":\"value\"}",
  "locale": "fr",
  "timezone": "Europe/Tallinn",
  "pageBrandName": "EmailEngine",
  "openAiPreProcessingFn": "return true; // pass every email",
  "imapClientName": "EmailEngine",
  "imapClientVersion": "1.3.45",
  "imapClientVendor": "Postal Systems",
  "imapClientSupportUrl": "https://github.com/postalsys/emailengine/issues",
  "exportMaxConcurrent": 2,
  "exportMaxGlobalConcurrent": 8,
  "gmailExportBatchSize": 10,
  "outlookExportBatchSize": 20,
  "exportMaxMessages": 500000,
  "exportMaxSize": 10737418240,
  "exportMaxMessageSize": 52428800,
  "exportMaxAge": 86400000
}

Response

Returns the list of setting keys that were updated.

updatedstring[]

List of updated setting keys

Example response

{
  "updated": [
    "notifyHeaders"
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.