{"externalDocs":{"description":"EmailEngine Documentation","url":"https://learn.emailengine.app/"},"security":[{"bearerAuth":[]}],"tags":[{"name":"Account","description":"Manage email accounts, including IMAP/SMTP configuration, OAuth2 authentication, and account health monitoring"},{"name":"Mailbox","description":"List, create, modify, and manage mailbox folders. Retrieve folder statistics and special-use designations"},{"name":"Message","description":"Search, retrieve, update, and delete email messages. Manage flags, labels, and message content"},{"name":"Submit","description":"Send emails with attachments, reply to threads, forward messages, and upload to folders. Supports both immediate and scheduled sending","externalDocs":{"description":"Sending Emails Documentation","url":"https://learn.emailengine.app/docs/sending"}},{"name":"Outbox","description":"Monitor and manage the email sending queue. View pending messages, retry failed deliveries, and track sending progress"},{"name":"Delivery Test","description":"Test email deliverability and authentication. Verify SPF, DKIM signatures, DMARC alignment, and analyze potential delivery issues"},{"name":"Access Tokens","description":"Create and manage API access tokens with customizable permissions, IP restrictions, and rate limits"},{"name":"Settings","description":"Configure EmailEngine runtime settings including webhooks, tracking, AI features, and email processing options"},{"name":"Templates","description":"Create and manage reusable email templates with variable substitution, HTML/text content, and attachments","externalDocs":{"description":"Email Templates Documentation","url":"https://learn.emailengine.app/docs/sending/templates"}},{"name":"Logs","description":"Access system and account-level logs for debugging, monitoring, and audit purposes"},{"name":"Stats","description":"Retrieve usage statistics, performance metrics, and account activity data","externalDocs":{"description":"Monitoring and Analytics","url":"https://learn.emailengine.app/docs/advanced/monitoring"}},{"name":"License","description":"Manage EmailEngine licensing, view license status, and handle license-related operations"},{"name":"Webhooks","description":"Configure webhook endpoints, manage event subscriptions, and monitor webhook delivery status","externalDocs":{"description":"Webhooks Guide","url":"https://learn.emailengine.app/docs/webhooks/overview"}},{"name":"OAuth2 Applications","description":"Configure OAuth2 applications for Gmail, Outlook, and other providers. Manage client credentials and authentication flows","externalDocs":{"description":"OAuth2 Configuration Guide","url":"https://learn.emailengine.app/docs/configuration/oauth2-configuration"}},{"name":"SMTP Gateway","description":"Configure and manage the built-in SMTP server for receiving emails and integrating with external systems"},{"name":"Blocklists","description":"Manage suppression lists (blocklists) of addresses that must not receive further emails. The same lists are populated by unsubscribe actions and can be managed in the admin UI under Suppression Lists"},{"name":"Multi Message Actions","description":"Perform bulk operations on multiple messages simultaneously, such as marking as read, moving, or deleting"},{"name":"Export (Beta)","description":"Bulk export messages from email accounts. This feature is in beta and the API may change in future releases. Export files are encrypted at rest when a service secret is configured."}],"x-logo":{"url":"https://emailengine.dev/static/logo.png","altText":"EmailEngine Logo"},"info":{"title":"EmailEngine API","version":"2.79.0","contact":{"name":"EmailEngine Support","url":"https://learn.emailengine.app/docs/support","email":"support@emailengine.app"},"license":{"name":"EmailEngine License","url":"https://emailengine.dev/LICENSE_EMAILENGINE.txt"},"description":"EmailEngine provides a RESTful API for managing email accounts, sending messages, and processing email data across multiple providers.\n\nEvery request needs an access token, passed either as an `Authorization: Bearer <token>` header or an `?access_token=` query argument. Tokens are issued and revoked on the Access Tokens page of the EmailEngine admin interface.\n\nRequests against the same email account are processed sequentially to keep its state consistent, so simultaneous calls for one account queue up behind each other. Long-running operations can be given more room with the `x-ee-timeout` header, in milliseconds.\n\nEvery failure returns the same JSON envelope: a numeric `statusCode`, a short `error` label and a human-readable `message`. Each endpoint therefore documents only which status codes it can return and what they mean.\n\nFull documentation: https://learn.emailengine.app/"},"openapi":"3.0.0","servers":[{"url":"https://emailengine.dev"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Enter your access token"}},"schemas":{"AccountPath":{"type":"array","description":"Mailbox folders to monitor for changes (IMAP only). Use \"*\" to monitor all folders (default)","example":["*"],"x-meta":{"usage":"Leave this at `\"*\"` unless the account is large and you only care about a few folders. Narrowing it reduces the number of folders EmailEngine keeps open and indexes, which is the main cost of syncing a big mailbox.\n\nUnmonitored folders stay fully reachable through the API. What you give up is webhooks: nothing is emitted for changes in a folder that is not on this list."},"nullable":true,"x-constraint":{"single":true},"items":{"type":"string","description":"Mailbox paths to monitor for changes. Use folder names, special-use flags like \"\\Sent\", or \"*\" for all folders. Set to null to reset to default.","example":"INBOX","maxLength":1024}},"SubconnectionPaths":{"type":"array","description":"Additional mailbox paths to monitor with dedicated IMAP connections for faster change detection. Use sparingly as connection limits are strict.","example":["[Gmail]/Spam","\\Sent"],"x-constraint":{"single":true},"items":{"type":"string","maxLength":256}},"AccountImapIndexer":{"type":"string","description":"Override the global IMAP indexing strategy for this account","example":"full","x-meta":{"enumDescriptions":{"full":"Track every change, including deletions. Slower but complete","fast":"Detect new messages only. Cheaper, but deletions and flag changes are missed"},"usage":"Leave this unset to follow the instance-wide setting, and only override it for accounts whose mailboxes behave differently from the rest of your fleet. A very large mailbox that nothing else writes to is the usual reason."},"enum":["full","fast"],"nullable":true,"x-convert":{"trim":true}},"ImapAccessToken":{"type":"string","description":"OAuth2 access token (when using OAuth2 instead of password authentication)","example":false,"enum":[false],"maxLength":16384},"ImapAuthentication":{"type":"object","description":"Authentication credentials for the IMAP server","x-meta":{"usage":"Send this for ordinary password authentication. Omit it when `useAuthServer` is on, because EmailEngine then fetches credentials from your authentication server for every connection and a stored password would be dead configuration.\n\nOn an update this replaces the whole credentials object unless `partial` is also set."},"enum":[false],"properties":{"user":{"type":"string","description":"Username or email address for IMAP authentication","example":"myuser@gmail.com","maxLength":256},"accessToken":{"$ref":"#/components/schemas/ImapAccessToken"},"pass":{"type":"string","description":"Password for IMAP authentication","example":"verysecret","maxLength":256}},"required":["user"]},"ImapTlsOptions":{"type":"object","description":"Advanced TLS configuration options","properties":{"rejectUnauthorized":{"type":"boolean","description":"Reject connections to servers with invalid TLS certificates","example":true,"default":true},"minVersion":{"type":"string","description":"Minimum TLS version to accept (e.g., \"TLSv1.2\", \"TLSv1.3\")","example":"TLSv1.2","maxLength":256}}},"ImapConfiguration":{"type":"object","description":"IMAP configuration. Set to `false` when there is no IMAP access to configure.","enum":[false],"properties":{"useAuthServer":{"type":"boolean","description":"Use external authentication server to retrieve credentials dynamically","example":false,"x-meta":{"usage":"Turn this on when passwords must not be stored in EmailEngine, for instance when they are short-lived or held in your own vault. EmailEngine then calls your authentication server for credentials each time it needs to connect, and the `auth` block must be omitted.\n\nThe authentication server URL itself is an instance-wide setting, not a per-account one."}},"auth":{"$ref":"#/components/schemas/ImapAuthentication"},"secure":{"type":"boolean","description":"Use TLS encryption for the connection (true for port 993, false for STARTTLS on port 143)","example":true,"default":false},"tls":{"$ref":"#/components/schemas/ImapTlsOptions"},"disableIMAP4rev2":{"type":"boolean","description":"Do not use IMAP4rev2 even if the server supports it","example":false,"x-meta":{"usage":"Set this only after a server has actually misbehaved. A handful of IMAP servers advertise IMAP4rev2 support and then answer incorrectly, and this forces EmailEngine back to IMAP4rev1 for that account.\n\nIt has no effect on accounts that authenticate with OAuth2."}},"resyncDelay":{"type":"integer","description":"Delay in seconds between full mailbox resynchronizations","example":900,"default":900},"disabled":{"type":"boolean","description":"Temporarily disable IMAP operations for this account","example":false},"host":{"type":"string","description":"IMAP server hostname","example":"imap.gmail.com","x-format":{"hostname":true}},"port":{"type":"integer","description":"IMAP server port (typically 993 for IMAP over TLS, 143 for STARTTLS)","example":993,"minimum":1,"maximum":65535},"sentMailPath":{"type":"string","description":"Custom folder path for sent messages. Defaults to auto-detected \"Sent\" folder. Set to null to use default.","example":"Sent Mail","nullable":true,"maxLength":1024},"draftsMailPath":{"type":"string","description":"Custom folder path for draft messages. Defaults to auto-detected \"Drafts\" folder. Set to null to use default.","example":"Drafts","nullable":true,"maxLength":1024},"junkMailPath":{"type":"string","description":"Custom folder path for spam/junk messages. Defaults to auto-detected \"Junk\" folder. Set to null to use default.","example":"Junk","nullable":true,"maxLength":1024},"trashMailPath":{"type":"string","description":"Custom folder path for deleted messages. Defaults to auto-detected \"Trash\" folder. Set to null to use default.","example":"Trash","nullable":true,"maxLength":1024},"archiveMailPath":{"type":"string","description":"Custom folder path for archived messages. Defaults to auto-detected \"Archive\" folder. Set to null to use default.","example":"Archive","nullable":true,"maxLength":1024}}},"SmtpAccessToken":{"type":"string","description":"OAuth2 access token (when using OAuth2 instead of password authentication)","example":false,"enum":[false],"maxLength":16384},"SmtpAuthentication":{"type":"object","description":"Authentication credentials for the SMTP server","x-meta":{"usage":"Send this for ordinary password authentication. Omit it when `useAuthServer` is on, because EmailEngine then fetches credentials from your authentication server for every connection and a stored password would be dead configuration.\n\nOn an update this replaces the whole credentials object unless `partial` is also set."},"enum":[false],"properties":{"user":{"type":"string","description":"Username or email address for SMTP authentication","example":"myuser@gmail.com","maxLength":256},"accessToken":{"$ref":"#/components/schemas/SmtpAccessToken"},"pass":{"type":"string","description":"Password for SMTP authentication","example":"verysecret","maxLength":256}},"required":["user"]},"SmtpTlsOptions":{"type":"object","description":"Advanced TLS configuration options","properties":{"rejectUnauthorized":{"type":"boolean","description":"Reject connections to servers with invalid TLS certificates","example":true,"default":true},"minVersion":{"type":"string","description":"Minimum TLS version to accept (e.g., \"TLSv1.2\", \"TLSv1.3\")","example":"TLSv1.2","maxLength":256}}},"SmtpConfiguration":{"type":"object","description":"SMTP configuration. Set to `false` when there is no SMTP access to configure.","enum":[false],"properties":{"useAuthServer":{"type":"boolean","description":"Use external authentication server to retrieve credentials dynamically","example":false,"x-meta":{"usage":"Turn this on when passwords must not be stored in EmailEngine, for instance when they are short-lived or held in your own vault. EmailEngine then calls your authentication server for credentials each time it needs to connect, and the `auth` block must be omitted.\n\nThe authentication server URL itself is an instance-wide setting, not a per-account one."}},"auth":{"$ref":"#/components/schemas/SmtpAuthentication"},"host":{"type":"string","description":"SMTP server hostname","example":"smtp.gmail.com","x-format":{"hostname":true}},"port":{"type":"integer","description":"SMTP server port (typically 587 for STARTTLS, 465 for SMTP over TLS, 25 for unencrypted)","example":587,"minimum":1,"maximum":65535},"secure":{"type":"boolean","description":"Use TLS encryption from the start (true for port 465, false for STARTTLS on ports 587/25)","example":false,"default":false},"tls":{"$ref":"#/components/schemas/SmtpTlsOptions"}},"required":["host","port"]},"OAuth2Authentication":{"type":"object","properties":{"user":{"type":"string","description":"Primary email account username","example":"user@outlook.com","maxLength":256},"delegatedUser":{"type":"string","description":"Shared mailbox username (Microsoft 365 delegation)","example":"shared.mailbox@outlook.com","maxLength":256},"delegatedAccount":{"type":"string","description":"Account ID to use for authenticating the shared mailbox. When provided, EmailEngine uses this account's credentials instead of creating new ones.","example":"user123","maxLength":256,"x-convert":{"trim":true}}}},"OAuth2":{"type":"object","description":"OAuth2 configuration. Set to `false` when the account does not authenticate with OAuth2.","enum":[false],"properties":{"authorize":{"type":"boolean","description":"Request an OAuth2 authorization URL instead of directly configuring credentials","example":false},"redirectUrl":{"type":"string","description":"URL to redirect to after OAuth2 authorization completes (only used when authorize=true)","example":"https://myapp/account/settings.php","x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"provider":{"type":"string","description":"OAuth2 Application ID configured in EmailEngine","example":"AAABhaBPHscAAAAH","maxLength":256},"auth":{"$ref":"#/components/schemas/OAuth2Authentication"},"useAuthServer":{"type":"boolean","description":"Use external authentication server for token management instead of EmailEngine","example":false,"x-meta":{"usage":"Turn this on when passwords must not be stored in EmailEngine, for instance when they are short-lived or held in your own vault. EmailEngine then calls your authentication server for credentials each time it needs to connect, and the `auth` block must be omitted.\n\nThe authentication server URL itself is an instance-wide setting, not a per-account one."}},"accessToken":{"type":"string","description":"OAuth2 access token for the email account","example":"ya29.a0ARrdaM8a...","maxLength":16384},"refreshToken":{"type":"string","description":"OAuth2 refresh token for obtaining new access tokens","example":"1//09Ie3CtORQYm...","maxLength":16384},"expires":{"type":"string","format":"date-time","description":"Access token expiration timestamp","example":"2021-03-22T13:13:31.000Z"}},"required":["auth"]},"WebhooksCustomHeader":{"type":"object","properties":{"key":{"type":"string","example":"Authorization","maxLength":1024,"x-convert":{"trim":true}},"value":{"type":"string","example":"Bearer <token>","default":"","maxLength":10240,"x-convert":{"trim":true}}},"required":["key"]},"AccountWebhooksCustomHeaders":{"type":"array","description":"Additional HTTP headers to include with every webhook request for authentication or tracking","items":{"$ref":"#/components/schemas/WebhooksCustomHeader"}},"CreateAccount":{"type":"object","example":{"account":"example","name":"Nyan Cat","email":"nyan.cat@example.com","imap":{"auth":{"user":"nyan.cat","pass":"sercretpass"},"host":"mail.example.com","port":993,"secure":true},"smtp":{"auth":{"user":"nyan.cat","pass":"secretpass"},"host":"mail.example.com","port":465,"secure":true}},"properties":{"account":{"type":"string","description":"Account ID. If set to `null`, a unique ID will be generated automatically","example":"example","x-meta":{"usage":"Set this when your own system already has an identifier for the mailbox, for example a user id, so you can address the account later without storing a second id. Leave it `null` and EmailEngine generates one, which comes back in the response.\n\nReusing an existing id is an update, not an error: the registration endpoint applies the new settings to that account rather than creating a second one."},"nullable":true,"maxLength":256,"x-convert":{"trim":true}},"name":{"type":"string","description":"Display name for the account","example":"My Email Account","maxLength":256},"email":{"type":"string","description":"Default email address of the account","example":"user@example.com","x-format":{"email":true}},"expectedEmail":{"type":"string","description":"Pins the account to an email address","example":"user@example.com","x-meta":{"usage":"Set this when the account is created through a hosted authentication form and you already know which mailbox the user is supposed to connect, so a user cannot finish the form against a different account than the one you provisioned.\n\nFor OAuth2 the address is compared against what the provider reports, never against anything the caller supplied, so for a shared or delegated mailbox this has to be the authenticating principal rather than the mailbox address. For IMAP it is compared against the address typed into the form, which the credentials do not prove ownership of.\n\nThe constraint stays on the account and is enforced again on every later reauthentication."},"x-format":{"email":true}},"path":{"$ref":"#/components/schemas/AccountPath"},"subconnections":{"$ref":"#/components/schemas/SubconnectionPaths"},"webhooks":{"type":"string","description":"Account-specific webhook URL","example":"https://myservice.com/imap/webhooks","x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"copy":{"type":"boolean","description":"Copy submitted messages to Sent folder. Set to `null` to unset and use provider specific default.","example":null,"nullable":true},"logs":{"type":"boolean","description":"Store recent logs","example":false,"default":false},"notifyFrom":{"type":"string","format":"date-time","description":"Only send webhooks for messages received after this date. Defaults to account creation time. IMAP only.","example":"2021-07-08T07:06:34.336Z","default":"now","nullable":true},"proxy":{"type":"string","description":"Proxy server URL for outbound connections","example":"socks5://proxy.example.com:1080","x-format":{"uri":{"scheme":["http","https","socks","socks4","socks4a","socks5"],"allowRelative":false}}},"smtpEhloName":{"type":"string","description":"Hostname to use in SMTP EHLO/HELO commands (defaults to system hostname)","example":"relay.example.com","nullable":true,"x-format":{"hostname":true}},"imapIndexer":{"$ref":"#/components/schemas/AccountImapIndexer"},"imap":{"$ref":"#/components/schemas/ImapConfiguration"},"smtp":{"$ref":"#/components/schemas/SmtpConfiguration"},"oauth2":{"$ref":"#/components/schemas/OAuth2"},"webhooksCustomHeaders":{"$ref":"#/components/schemas/AccountWebhooksCustomHeaders"},"locale":{"type":"string","description":"Optional locale","example":"fr","maxLength":100},"tz":{"type":"string","description":"Optional timezone","example":"Europe/Tallinn","maxLength":100}},"required":["account","name"]},"CreateAccountState":{"type":"string","description":"Whether the account was created or updated. Not present when a redirect URL is returned","example":"new","x-meta":{"enumDescriptions":{"new":"The entry did not exist and was created","existing":"The entry already existed and was updated"}},"enum":["existing","new"]},"CreateAccountResponse":{"type":"object","properties":{"account":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"state":{"$ref":"#/components/schemas/CreateAccountState"},"redirect":{"type":"string","description":"OAuth2 authorization URL. Returned instead of account and state when the request used oauth2.authorize=true - send the user to this URL to complete the OAuth2 flow","example":"https://emailengine.example.com/oauth?account=example","x-format":{"uri":true}}}},"ValidationErrorField":{"type":"object","properties":{"message":{"type":"string","description":"Description of the validation failure","example":"\"pageSize\" must be less than or equal to 1000"},"key":{"type":"string","description":"Name of the input field that failed validation","example":"pageSize"}}},"ValidationErrorFields":{"type":"array","description":"List of input fields that failed validation","items":{"$ref":"#/components/schemas/ValidationErrorField"}},"ValidationErrorResponse":{"type":"object","description":"Validation error","properties":{"statusCode":{"type":"integer","description":"HTTP status code","example":400},"error":{"type":"string","description":"HTTP status text","example":"Bad Request"},"message":{"type":"string","description":"Error message","example":"Invalid input"},"fields":{"$ref":"#/components/schemas/ValidationErrorFields"}}},"AuthenticationErrorResponse":{"type":"object","description":"Authentication error","properties":{"statusCode":{"type":"integer","description":"HTTP status code","example":401},"error":{"type":"string","description":"HTTP status text","example":"Unauthorized"},"message":{"type":"string","description":"Error message","example":"Missing authentication"}}},"AccessDeniedErrorResponse":{"type":"object","description":"Access denied error","properties":{"statusCode":{"type":"integer","description":"HTTP status code","example":403},"error":{"type":"string","description":"HTTP status text","example":"Forbidden"},"message":{"type":"string","description":"Error message","example":"Unauthorized scope"}}},"NotFoundErrorResponse":{"type":"object","description":"Not found error","properties":{"statusCode":{"type":"integer","description":"HTTP status code","example":404},"error":{"type":"string","description":"HTTP status text","example":"Not Found"},"message":{"type":"string","description":"Error message","example":"Requested message was not found"},"code":{"type":"string","description":"Machine-readable error code","example":"MessageNotFound"}}},"RateLimitErrorResponse":{"type":"object","description":"Rate limit error","properties":{"statusCode":{"type":"integer","description":"HTTP status code","example":429},"error":{"type":"string","description":"HTTP status text","example":"Too Many Requests"},"message":{"type":"string","description":"Error message","example":"Rate limit exceeded"},"ttl":{"type":"integer","description":"Seconds until the rate limit window resets","example":30}}},"InternalErrorResponse":{"type":"object","description":"Internal server error","properties":{"statusCode":{"type":"integer","description":"HTTP status code","example":500},"error":{"type":"string","description":"HTTP status text","example":"Internal Server Error"},"message":{"type":"string","description":"Error message","example":"An internal server error occurred"},"code":{"type":"string","description":"Machine-readable error code, if available","example":"InternalError"},"details":{"type":"string","description":"Additional error details, if available"}}},"IMAPResponse":{"type":"object","description":"IMAP configuration","properties":{"useAuthServer":{"type":"boolean","description":"Use external authentication server to retrieve credentials dynamically","example":false,"x-meta":{"usage":"Turn this on when passwords must not be stored in EmailEngine, for instance when they are short-lived or held in your own vault. EmailEngine then calls your authentication server for credentials each time it needs to connect, and the `auth` block must be omitted.\n\nThe authentication server URL itself is an instance-wide setting, not a per-account one."}},"auth":{"$ref":"#/components/schemas/ImapAuthentication"},"secure":{"type":"boolean","description":"Use TLS encryption for the connection (true for port 993, false for STARTTLS on port 143)","example":true,"default":false},"tls":{"$ref":"#/components/schemas/ImapTlsOptions"},"disableIMAP4rev2":{"type":"boolean","description":"Do not use IMAP4rev2 even if the server supports it","example":false,"x-meta":{"usage":"Set this only after a server has actually misbehaved. A handful of IMAP servers advertise IMAP4rev2 support and then answer incorrectly, and this forces EmailEngine back to IMAP4rev1 for that account.\n\nIt has no effect on accounts that authenticate with OAuth2."}},"resyncDelay":{"type":"integer","description":"Delay in seconds between full mailbox resynchronizations","example":900,"default":900},"disabled":{"type":"boolean","description":"Temporarily disable IMAP operations for this account","example":false},"host":{"type":"string","description":"IMAP server hostname","example":"imap.gmail.com","x-format":{"hostname":true}},"port":{"type":"integer","description":"IMAP server port (typically 993 for IMAP over TLS, 143 for STARTTLS)","example":993,"minimum":1,"maximum":65535},"sentMailPath":{"type":"string","description":"Custom folder path for sent messages. Defaults to auto-detected \"Sent\" folder. Set to null to use default.","example":"Sent Mail","nullable":true,"maxLength":1024},"draftsMailPath":{"type":"string","description":"Custom folder path for draft messages. Defaults to auto-detected \"Drafts\" folder. Set to null to use default.","example":"Drafts","nullable":true,"maxLength":1024},"junkMailPath":{"type":"string","description":"Custom folder path for spam/junk messages. Defaults to auto-detected \"Junk\" folder. Set to null to use default.","example":"Junk","nullable":true,"maxLength":1024},"trashMailPath":{"type":"string","description":"Custom folder path for deleted messages. Defaults to auto-detected \"Trash\" folder. Set to null to use default.","example":"Trash","nullable":true,"maxLength":1024},"archiveMailPath":{"type":"string","description":"Custom folder path for archived messages. Defaults to auto-detected \"Archive\" folder. Set to null to use default.","example":"Archive","nullable":true,"maxLength":1024}}},"SMTPResponse":{"type":"object","description":"SMTP configuration","properties":{"useAuthServer":{"type":"boolean","description":"Use external authentication server to retrieve credentials dynamically","example":false,"x-meta":{"usage":"Turn this on when passwords must not be stored in EmailEngine, for instance when they are short-lived or held in your own vault. EmailEngine then calls your authentication server for credentials each time it needs to connect, and the `auth` block must be omitted.\n\nThe authentication server URL itself is an instance-wide setting, not a per-account one."}},"auth":{"$ref":"#/components/schemas/SmtpAuthentication"},"host":{"type":"string","description":"SMTP server hostname","example":"smtp.gmail.com","x-format":{"hostname":true}},"port":{"type":"integer","description":"SMTP server port (typically 587 for STARTTLS, 465 for SMTP over TLS, 25 for unencrypted)","example":587,"minimum":1,"maximum":65535},"secure":{"type":"boolean","description":"Use TLS encryption from the start (true for port 465, false for STARTTLS on ports 587/25)","example":false,"default":false},"tls":{"$ref":"#/components/schemas/SmtpTlsOptions"}},"required":["host","port"]},"AccountOauth2Scopes":{"type":"array","description":"OAuth2 scopes granted for this account","items":{"type":"string","example":"https://mail.google.com/"}},"AccountOauth2UserFlag":{"type":"object","description":"Account-level OAuth2 error flag, if any"},"Oauth2Response":{"type":"object","description":"OAuth2 configuration","properties":{"authorize":{"type":"boolean","description":"Request an OAuth2 authorization URL instead of directly configuring credentials","example":false},"redirectUrl":{"type":"string","description":"URL to redirect to after OAuth2 authorization completes (only used when authorize=true)","example":"https://myapp/account/settings.php","x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"provider":{"type":"string","description":"OAuth2 Application ID configured in EmailEngine","example":"AAABhaBPHscAAAAH","maxLength":256},"auth":{"$ref":"#/components/schemas/OAuth2Authentication"},"useAuthServer":{"type":"boolean","description":"Use external authentication server for token management instead of EmailEngine","example":false,"x-meta":{"usage":"Turn this on when passwords must not be stored in EmailEngine, for instance when they are short-lived or held in your own vault. EmailEngine then calls your authentication server for credentials each time it needs to connect, and the `auth` block must be omitted.\n\nThe authentication server URL itself is an instance-wide setting, not a per-account one."}},"accessToken":{"type":"string","description":"OAuth2 access token for the email account","example":"ya29.a0ARrdaM8a...","maxLength":16384},"refreshToken":{"type":"string","description":"OAuth2 refresh token for obtaining new access tokens","example":"1//09Ie3CtORQYm...","maxLength":16384},"expires":{"type":"string","format":"date-time","description":"Access token expiration timestamp","example":"2021-03-22T13:13:31.000Z"},"scope":{"$ref":"#/components/schemas/AccountOauth2Scopes"},"tokenType":{"type":"string","description":"OAuth2 token type","example":"Bearer"},"generated":{"type":"string","format":"date-time","description":"When the current access token was generated","example":"2021-03-22T13:13:31.000Z"},"refreshTokenGenerated":{"type":"string","format":"date-time","description":"When the current refresh token was generated","example":"2021-03-22T13:13:31.000Z"},"userFlag":{"$ref":"#/components/schemas/AccountOauth2UserFlag"}},"required":["auth"]},"AccountInfoState":{"type":"string","description":"Informational account state","example":"connected","x-meta":{"enumDescriptions":{"init":"The account was just registered and has not connected yet","connecting":"Connecting to the mail server or authorizing with the provider","syncing":"Connected and performing the initial or a periodic mailbox sync","connected":"Connected and watching for changes. This is the healthy steady state","disconnected":"The connection dropped and EmailEngine is retrying with backoff","paused":"Syncing was paused through the API. No connection is maintained","authenticationError":"The credentials were rejected. Requires re-authentication before syncing resumes","connectError":"The server could not be reached or the TLS handshake failed. Retried with backoff","unset":"No IMAP or OAuth2 configuration is set, so the account is not synced"}},"enum":["init","unset","connected","connecting","syncing","authenticationError","connectError","disconnected","paused"]},"SMTPStatusStatus":{"type":"string","description":"Was the last SMTP attempt successful or not","enum":["ok","error"]},"SMTPStatusNetworkRouting":{"type":"object","description":"Network routing information for the delivery attempt","example":{"localAddress":"198.51.100.24","name":"relay.example.com"},"nullable":true},"SMTPInfoStatus":{"type":"object","description":"Information about the last SMTP connection attempt. Null when no SMTP connection has been attempted","nullable":true,"properties":{"created":{"type":"string","format":"date-time","description":"When was the status for SMTP connection last updated","example":"2021-07-08T07:06:34.336Z","nullable":true},"status":{"$ref":"#/components/schemas/SMTPStatusStatus"},"response":{"type":"string","description":"SMTP response message for delivery attempt","example":"250 OK"},"description":{"type":"string","description":"Error information","example":"Authentication failed"},"responseCode":{"type":"integer","description":"Error status code","example":500},"code":{"type":"string","description":"Error type identifier","example":"EAUTH"},"command":{"type":"string","description":"SMTP command that failed","example":"AUTH PLAIN"},"networkRouting":{"$ref":"#/components/schemas/SMTPStatusNetworkRouting"}}},"AccountSyncError":{"type":"object","description":"Information about the last mailbox sync error (IMAP accounts only)","properties":{"path":{"type":"string","description":"Mailbox folder path where the error occurred","example":"INBOX"},"time":{"type":"string","format":"date-time","description":"When the error occurred","example":"2021-07-08T07:06:34.336Z"},"error":{"type":"string","description":"Error message","example":"Failed to open mailbox"}}},"AccountType":{"type":"string","description":"How the account connects to its mailbox","example":"outlook","x-meta":{"enumDescriptions":{"imap":"Plain IMAP and SMTP, authenticated with a username and password","gmail":"Gmail or Google Workspace, through a user-consented OAuth2 app","gmailService":"Google Workspace through a service account, with no per-user consent screen","outlook":"Outlook or Microsoft 365, through a user-consented OAuth2 app","outlookService":"Microsoft 365 through application permissions, with no per-user consent screen","mailRu":"Mail.ru, through an OAuth2 app","oauth2":"An OAuth2 account whose application is no longer configured in EmailEngine","delegated":"A shared or delegated mailbox accessed through another account credentials","sending":"Send-only. No IMAP access is configured, so nothing is synced","invalid":"Delegation could not be resolved, so the account cannot be used"}},"enum":["imap","gmail","gmailService","outlook","outlookService","mailRu","oauth2","delegated","sending","invalid"]},"AccountBaseScopes":{"type":"string","description":"OAuth2 Base Scopes","example":"imap","enum":["imap","api","pubsub"],"x-convert":{"trim":true}},"AccountCountersEvents":{"type":"object","description":"Cumulative event counters for the account lifetime","example":{"messageNew":30,"messageDeleted":5}},"AccountCounters":{"type":"object","properties":{"events":{"$ref":"#/components/schemas/AccountCountersEvents"}}},"AccountQuota":{"type":"object","description":"Account quota information if query argument quota=true. This value will be false if the server does not provide quota information.","enum":[false],"properties":{"usage":{"type":"integer","description":"How many bytes has the account stored in emails","example":8547884032},"limit":{"type":"integer","description":"How many bytes can the account store emails","example":16106127360},"status":{"type":"string","description":"Textual information about the usage","example":"53%"}}},"state":{"type":"string","description":"Subscription state","x-meta":{"enumDescriptions":{"creating":"The subscription is being created","created":"Active and delivering notifications","renewing":"Being renewed before it expires","error":"Creation or renewal failed. See the error field"}},"enum":["creating","created","renewing","error"]},"state1":{"type":"object","description":"Current subscription state","properties":{"state":{"$ref":"#/components/schemas/state"},"time":{"type":"number","description":"Timestamp of last state change","example":1625727994336},"error":{"type":"string","description":"Error message if state is error, null after a successful renewal","example":"Subscription renewal was rejected","nullable":true},"retryCount":{"type":"integer","description":"How many times the subscription renewal has been retried","example":0},"createRetryCount":{"type":"integer","description":"How many times the subscription creation has been retried","example":0}}},"outlookSubscription":{"type":"object","description":"Microsoft Graph subscription details (Outlook accounts only)","properties":{"id":{"type":"string","description":"Microsoft Graph subscription ID","example":"0fc0f6bb-a3e1-4f7a-9d3a-8e2f1f8b9c11"},"expirationDateTime":{"type":"string","format":"date-time","description":"When the subscription expires","example":"2021-07-11T07:06:34.336Z","nullable":true},"state":{"$ref":"#/components/schemas/state1"}}},"OAuthGrant":{"type":"string","description":"OAuth2 grant type being requested","example":"refresh_token","enum":["refresh_token","authorization_code"]},"OAuthTokenErrorFlag":{"type":"object","description":"Application-level error flag raised by this failure","properties":{"message":{"type":"string","description":"Description of the application-level problem","example":"Please verify the OAuth2 application credentials"},"code":{"type":"string","description":"Machine-readable code of the application-level problem","example":"INVALID_CLIENT_SECRET"},"url":{"type":"string","description":"Link with instructions to resolve the problem","example":"https://console.developers.google.com/"}}},"OAuthTokenUserFlag":{"type":"object","description":"Account-level error flag raised by this failure","properties":{"message":{"type":"string","description":"Description of the account-level problem","example":"The grant for this account has been revoked"}}},"OauthScopes":{"type":"array","description":"Requested OAuth2 permission scopes","items":{"type":"string","description":"OAuth2 permission scope","example":"https://mail.google.com/"}},"OAuthTokenErrorResponse":{"type":"object","description":"Raw error response from the OAuth2 server","example":{"error":"invalid_grant","error_description":"Bad Request"}},"OAuthTokenRequestError":{"type":"object","description":"Details about the failed OAuth2 token request","properties":{"url":{"type":"string","description":"OAuth2 token endpoint URL","example":"https://oauth2.googleapis.com/token"},"method":{"type":"string","description":"HTTP method used for the token request","example":"post"},"grant":{"$ref":"#/components/schemas/OAuthGrant"},"provider":{"type":"string","description":"OAuth2 provider name","example":"gmail","maxLength":256},"status":{"type":"integer","description":"HTTP status code from the OAuth2 server","example":400},"clientId":{"type":"string","description":"OAuth2 client ID used for authentication","example":"1023289917884-h3nu00e9cb7h252e24c23sv19l8k57ah.apps.googleusercontent.com"},"clientSecret":{"type":"string","description":"Partially masked OAuth2 client secret, included when the OAuth2 server indicates an invalid client secret","example":"GOCSPX...V-Da"},"authority":{"type":"string","description":"Microsoft tenant configuration (Outlook applications only)","example":"common"},"serviceClient":{"type":"string","description":"Service client ID (2-legged OAuth2 applications only)","example":"113328088575113530522"},"signer":{"type":"string","description":"Signing method used for service account token requests","example":"serviceKey"},"googleProjectId":{"type":"string","description":"Google Cloud project ID (Gmail service applications only)","example":"project-name-425411"},"serviceClientEmail":{"type":"string","description":"Service account email (Gmail service applications only)","example":"service-account@project-name-425411.iam.gserviceaccount.com"},"code":{"type":"string","description":"Value of the authorization code or error code related to the failure","example":"AAABhaBPHscAAAAH"},"flag":{"$ref":"#/components/schemas/OAuthTokenErrorFlag"},"userFlag":{"$ref":"#/components/schemas/OAuthTokenUserFlag"},"scopes":{"$ref":"#/components/schemas/OauthScopes"},"response":{"$ref":"#/components/schemas/OAuthTokenErrorResponse"}}},"AccountErrorEntry":{"type":"object","nullable":true,"properties":{"response":{"type":"string","description":"Human-readable error message","example":"Token request failed for gmail (refresh_token, HTTP 400): invalid_grant - Token has been expired or revoked."},"description":{"type":"string","description":"Additional details about the error","example":"Authentication failed"},"serverResponseCode":{"type":"string","description":"Error code or classification","example":"OauthRenewError"},"tokenRequest":{"$ref":"#/components/schemas/OAuthTokenRequestError"}}},"AccountResponse":{"type":"object","properties":{"account":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"name":{"type":"string","description":"Display name for the account","example":"My Email Account","maxLength":256},"email":{"type":"string","description":"Default email address of the account","example":"user@example.com","x-format":{"email":true}},"expectedEmail":{"type":"string","description":"Pins the account to an email address","example":"user@example.com","x-meta":{"usage":"Set this when the account is created through a hosted authentication form and you already know which mailbox the user is supposed to connect, so a user cannot finish the form against a different account than the one you provisioned.\n\nFor OAuth2 the address is compared against what the provider reports, never against anything the caller supplied, so for a shared or delegated mailbox this has to be the authenticating principal rather than the mailbox address. For IMAP it is compared against the address typed into the form, which the credentials do not prove ownership of.\n\nThe constraint stays on the account and is enforced again on every later reauthentication."},"x-format":{"email":true}},"copy":{"type":"boolean","description":"Copy submitted messages to Sent folder","example":true},"logs":{"type":"boolean","description":"Store recent logs","example":false},"notifyFrom":{"type":"string","format":"date-time","description":"Only send webhooks for messages received after this date. Defaults to account creation time. IMAP only.","example":"2021-07-08T07:06:34.336Z","nullable":true},"path":{"$ref":"#/components/schemas/AccountPath"},"imapIndexer":{"$ref":"#/components/schemas/AccountImapIndexer"},"subconnections":{"$ref":"#/components/schemas/SubconnectionPaths"},"webhooks":{"type":"string","description":"Account-specific webhook URL","example":"https://myservice.com/imap/webhooks","x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"proxy":{"type":"string","description":"Proxy server URL for outbound connections","example":"socks5://proxy.example.com:1080","x-format":{"uri":{"scheme":["http","https","socks","socks4","socks4a","socks5"],"allowRelative":false}}},"smtpEhloName":{"type":"string","description":"Hostname to use in SMTP EHLO/HELO commands (defaults to system hostname)","example":"relay.example.com","nullable":true,"x-format":{"hostname":true}},"imap":{"$ref":"#/components/schemas/IMAPResponse"},"smtp":{"$ref":"#/components/schemas/SMTPResponse"},"oauth2":{"$ref":"#/components/schemas/Oauth2Response"},"state":{"$ref":"#/components/schemas/AccountInfoState"},"smtpStatus":{"$ref":"#/components/schemas/SMTPInfoStatus"},"syncError":{"$ref":"#/components/schemas/AccountSyncError"},"connections":{"type":"integer","description":"Number of open IMAP connections for this account (IMAP accounts only)","example":2},"sendOnly":{"type":"boolean","description":"Whether this is a send-only account that does not sync messages","example":false},"webhooksCustomHeaders":{"$ref":"#/components/schemas/AccountWebhooksCustomHeaders"},"locale":{"type":"string","description":"Optional locale","example":"fr","maxLength":100},"tz":{"type":"string","description":"Optional timezone","example":"Europe/Tallinn","maxLength":100},"type":{"$ref":"#/components/schemas/AccountType"},"app":{"type":"string","description":"OAuth2 application ID","example":"AAABhaBPHscAAAAH","maxLength":256},"baseScopes":{"$ref":"#/components/schemas/AccountBaseScopes"},"counters":{"$ref":"#/components/schemas/AccountCounters"},"quota":{"$ref":"#/components/schemas/AccountQuota"},"syncTime":{"type":"string","format":"date-time","description":"Last sync time (IMAP accounts only)","example":"2021-02-17T13:43:18.860Z"},"outlookSubscription":{"$ref":"#/components/schemas/outlookSubscription"},"lastError":{"$ref":"#/components/schemas/AccountErrorEntry"}},"required":["account","type"]},"ImapUpdateAccessToken":{"type":"string","description":"OAuth2 access token (when using OAuth2 instead of password authentication)","example":false,"enum":[false],"maxLength":16384},"ImapUpdateAuthentication":{"type":"object","description":"Authentication credentials for the IMAP server","x-meta":{"usage":"Send this for ordinary password authentication. Omit it when `useAuthServer` is on, because EmailEngine then fetches credentials from your authentication server for every connection and a stored password would be dead configuration.\n\nOn an update this replaces the whole credentials object unless `partial` is also set."},"enum":[false],"properties":{"user":{"type":"string","description":"Username or email address for IMAP authentication","example":"myuser@gmail.com","maxLength":256},"accessToken":{"$ref":"#/components/schemas/ImapUpdateAccessToken"},"pass":{"type":"string","description":"Password for IMAP authentication","example":"verysecret","maxLength":256}},"required":["user"]},"ImapUpdateTlsOptions":{"type":"object","description":"Advanced TLS configuration options","properties":{"rejectUnauthorized":{"type":"boolean","description":"Reject connections to servers with invalid TLS certificates","example":true},"minVersion":{"type":"string","description":"Minimum TLS version to accept","example":"TLSv1.2","maxLength":256}}},"IMAPUpdate":{"type":"object","description":"IMAP configuration. Set to `false` to remove the stored IMAP configuration from the account.","enum":[false],"properties":{"partial":{"type":"boolean","description":"Update only the provided fields instead of replacing the entire configuration","example":false,"x-meta":{"usage":"Set this when you are changing one setting and do not want to resend the rest. Without it the configuration object you send replaces the stored one wholesale, so any key you leave out is cleared.\n\nIt applies only to the block it sits in: a partial `imap` update alongside a full `smtp` object updates one and replaces the other."},"default":false},"useAuthServer":{"type":"boolean","description":"Use external authentication server to retrieve credentials dynamically","example":false,"x-meta":{"usage":"Turn this on when passwords must not be stored in EmailEngine, for instance when they are short-lived or held in your own vault. EmailEngine then calls your authentication server for credentials each time it needs to connect, and the `auth` block must be omitted.\n\nThe authentication server URL itself is an instance-wide setting, not a per-account one."}},"auth":{"$ref":"#/components/schemas/ImapUpdateAuthentication"},"host":{"type":"string","description":"IMAP server hostname","example":"imap.gmail.com","x-format":{"hostname":true}},"port":{"type":"integer","description":"IMAP server port","example":993,"minimum":1,"maximum":65535},"secure":{"type":"boolean","description":"Use TLS encryption for the connection","example":true},"tls":{"$ref":"#/components/schemas/ImapUpdateTlsOptions"},"disableIMAP4rev2":{"type":"boolean","description":"Do not use IMAP4rev2 even if the server supports it","example":false,"x-meta":{"usage":"Set this only after a server has actually misbehaved. A handful of IMAP servers advertise IMAP4rev2 support and then answer incorrectly, and this forces EmailEngine back to IMAP4rev1 for that account.\n\nIt has no effect on accounts that authenticate with OAuth2."}},"resyncDelay":{"type":"integer","description":"Delay in seconds between full mailbox resynchronizations","example":900},"disabled":{"type":"boolean","description":"Temporarily disable IMAP operations for this account","example":false},"sentMailPath":{"type":"string","description":"Custom folder path for sent messages. Set to null to use default.","example":"Sent Mail","nullable":true,"maxLength":1024},"draftsMailPath":{"type":"string","description":"Custom folder path for draft messages. Set to null to use default.","example":"Drafts","nullable":true,"maxLength":1024},"junkMailPath":{"type":"string","description":"Custom folder path for spam/junk messages. Set to null to use default.","example":"Junk","nullable":true,"maxLength":1024},"trashMailPath":{"type":"string","description":"Custom folder path for deleted messages. Set to null to use default.","example":"Trash","nullable":true,"maxLength":1024},"archiveMailPath":{"type":"string","description":"Custom folder path for archived messages. Set to null to use default.","example":"Archive","nullable":true,"maxLength":1024}}},"SmtpUpdateAccessToken":{"type":"string","description":"OAuth2 access token (when using OAuth2 instead of password authentication)","example":false,"enum":[false],"maxLength":16384},"SmtpUpdateAuthentication":{"type":"object","description":"Authentication credentials for the SMTP server","x-meta":{"usage":"Send this for ordinary password authentication. Omit it when `useAuthServer` is on, because EmailEngine then fetches credentials from your authentication server for every connection and a stored password would be dead configuration.\n\nOn an update this replaces the whole credentials object unless `partial` is also set."},"enum":[false],"properties":{"user":{"type":"string","description":"Username or email address for SMTP authentication","example":"myuser@gmail.com","maxLength":256},"accessToken":{"$ref":"#/components/schemas/SmtpUpdateAccessToken"},"pass":{"type":"string","description":"Password for SMTP authentication","example":"verysecret","maxLength":256}},"required":["user"]},"SmtpUpdateTlsOptions":{"type":"object","description":"Advanced TLS configuration options","properties":{"rejectUnauthorized":{"type":"boolean","description":"Reject connections to servers with invalid TLS certificates","example":true},"minVersion":{"type":"string","description":"Minimum TLS version to accept","example":"TLSv1.2","maxLength":256}}},"SMTPUpdate":{"type":"object","description":"SMTP configuration. Set to `false` to remove the stored SMTP configuration from the account.","enum":[false],"properties":{"partial":{"type":"boolean","description":"Update only the provided fields instead of replacing the entire configuration","example":false,"x-meta":{"usage":"Set this when you are changing one setting and do not want to resend the rest. Without it the configuration object you send replaces the stored one wholesale, so any key you leave out is cleared.\n\nIt applies only to the block it sits in: a partial `imap` update alongside a full `smtp` object updates one and replaces the other."},"default":false},"useAuthServer":{"type":"boolean","description":"Use external authentication server to retrieve credentials dynamically","example":false,"x-meta":{"usage":"Turn this on when passwords must not be stored in EmailEngine, for instance when they are short-lived or held in your own vault. EmailEngine then calls your authentication server for credentials each time it needs to connect, and the `auth` block must be omitted.\n\nThe authentication server URL itself is an instance-wide setting, not a per-account one."}},"auth":{"$ref":"#/components/schemas/SmtpUpdateAuthentication"},"host":{"type":"string","description":"SMTP server hostname","example":"smtp.gmail.com","x-format":{"hostname":true}},"port":{"type":"integer","description":"SMTP server port","example":587,"minimum":1,"maximum":65535},"secure":{"type":"boolean","description":"Use TLS encryption from the start","example":false},"tls":{"$ref":"#/components/schemas/SmtpUpdateTlsOptions"}}},"OAuth2Update":{"type":"object","description":"OAuth2 configuration. Set to `false` to remove the stored OAuth2 configuration from the account.","enum":[false],"properties":{"partial":{"type":"boolean","description":"Update only the provided fields instead of replacing the entire configuration","example":false,"x-meta":{"usage":"Set this when you are changing one setting and do not want to resend the rest. Without it the configuration object you send replaces the stored one wholesale, so any key you leave out is cleared.\n\nIt applies only to the block it sits in: a partial `imap` update alongside a full `smtp` object updates one and replaces the other."},"default":false},"authorize":{"type":"boolean","description":"Request an OAuth2 authorization URL instead of directly configuring credentials","example":false},"provider":{"type":"string","description":"OAuth2 Application ID configured in EmailEngine","example":"AAABhaBPHscAAAAH","maxLength":256},"auth":{"$ref":"#/components/schemas/OAuth2Authentication"},"useAuthServer":{"type":"boolean","description":"Use external authentication server for token management instead of EmailEngine","example":false,"x-meta":{"usage":"Turn this on when passwords must not be stored in EmailEngine, for instance when they are short-lived or held in your own vault. EmailEngine then calls your authentication server for credentials each time it needs to connect, and the `auth` block must be omitted.\n\nThe authentication server URL itself is an instance-wide setting, not a per-account one."}},"accessToken":{"type":"string","description":"OAuth2 access token for the email account","example":"ya29.a0ARrdaM8a...","maxLength":16384},"refreshToken":{"type":"string","description":"OAuth2 refresh token for obtaining new access tokens","example":"1//09Ie3CtORQYm...","maxLength":16384},"expires":{"type":"string","format":"date-time","description":"Access token expiration timestamp","example":"2021-03-22T13:13:31.000Z"}},"required":["auth"]},"UpdateAccount":{"type":"object","example":{"name":"Nyan Cat","email":"nyan.cat@example.com","imap":{"partial":true,"disabled":true},"smtp":{"partial":true,"host":"mail.example.com"}},"properties":{"name":{"type":"string","description":"Display name for the account","example":"My Email Account","maxLength":256},"email":{"type":"string","description":"Default email address of the account","example":"user@example.com","x-format":{"email":true}},"expectedEmail":{"type":"string","description":"Pins the account to an email address. Set to `null` to remove the constraint","example":"user@example.com","x-meta":{"usage":"Set this when the account is created through a hosted authentication form and you already know which mailbox the user is supposed to connect, so a user cannot finish the form against a different account than the one you provisioned.\n\nFor OAuth2 the address is compared against what the provider reports, never against anything the caller supplied, so for a shared or delegated mailbox this has to be the authenticating principal rather than the mailbox address. For IMAP it is compared against the address typed into the form, which the credentials do not prove ownership of.\n\nThe constraint stays on the account and is enforced again on every later reauthentication."},"nullable":true,"x-format":{"email":true}},"path":{"$ref":"#/components/schemas/AccountPath"},"subconnections":{"$ref":"#/components/schemas/SubconnectionPaths"},"webhooks":{"type":"string","description":"Account-specific webhook URL","example":"https://myservice.com/imap/webhooks","x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"copy":{"type":"boolean","description":"Copy submitted messages to Sent folder. Set to `null` to unset and use provider specific default.","example":null,"nullable":true},"logs":{"type":"boolean","description":"Store recent logs","example":false},"notifyFrom":{"type":"string","format":"date-time","description":"Only send webhooks for messages received after this date. Defaults to account creation time. IMAP only.","example":"2021-07-08T07:06:34.336Z","nullable":true},"proxy":{"type":"string","description":"Proxy server URL for outbound connections","example":"socks5://proxy.example.com:1080","x-format":{"uri":{"scheme":["http","https","socks","socks4","socks4a","socks5"],"allowRelative":false}}},"smtpEhloName":{"type":"string","description":"Hostname to use in SMTP EHLO/HELO commands (defaults to system hostname)","example":"relay.example.com","nullable":true,"x-format":{"hostname":true}},"imap":{"$ref":"#/components/schemas/IMAPUpdate"},"smtp":{"$ref":"#/components/schemas/SMTPUpdate"},"oauth2":{"$ref":"#/components/schemas/OAuth2Update"},"webhooksCustomHeaders":{"$ref":"#/components/schemas/AccountWebhooksCustomHeaders"},"locale":{"type":"string","description":"Optional locale","example":"fr","maxLength":100},"tz":{"type":"string","description":"Optional timezone","example":"Europe/Tallinn","maxLength":100}}},"UpdateAccountResponse":{"type":"object","properties":{"account":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}}},"required":["account"]},"DeleteAccountResponse":{"type":"object","properties":{"account":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"deleted":{"type":"boolean","description":"Was the account deleted","default":true}},"required":["account"]},"ServiceUnavailableErrorResponse":{"type":"object","description":"Service unavailable error","properties":{"statusCode":{"type":"integer","description":"HTTP status code","example":503},"error":{"type":"string","description":"HTTP status text","example":"Service Unavailable"},"message":{"type":"string","description":"Error message","example":"No active handler for requested account. Try again later."},"code":{"type":"string","description":"Machine-readable error code","example":"WorkerNotAvailable"}}},"ExportFolders":{"type":"array","description":"Folder paths or special-use flags (e.g., \\Inbox, \\Sent, \\All) to export from","x-meta":{"usage":"Name folders when you want a subset, by path or by special-use flag such as `\\Sent`. Leaving it empty is not \"nothing\", it is a documented default: Gmail and Outlook API accounts export All Mail, and every other account exports every folder except Junk and Trash."},"x-constraint":{"single":true},"items":{"type":"string","example":"INBOX","maxLength":1024}},"ExportTextType":{"type":"string","description":"Which message bodies to include in the export","example":"*","x-meta":{"enumDescriptions":{"plain":"Plain text bodies only","html":"HTML bodies only","*":"Both the plain text and the HTML body"}},"default":"*","enum":["plain","html","*"]},"ExportRequest":{"type":"object","properties":{"folders":{"$ref":"#/components/schemas/ExportFolders"},"startDate":{"type":"string","format":"date-time","description":"Export messages from this date","example":"2024-01-01T00:00:00Z"},"endDate":{"type":"string","format":"date-time","description":"Export messages until this date","example":"2024-12-31T23:59:59Z"},"textType":{"$ref":"#/components/schemas/ExportTextType"},"maxBytes":{"type":"integer","description":"Maximum bytes for text content (0 = unlimited)","example":5242880,"default":5242880,"minimum":0},"includeAttachments":{"type":"boolean","description":"Include attachment content as base64 blob in attachments array","default":false}},"required":["startDate","endDate"]},"CreateExportResponse":{"type":"object","properties":{"exportId":{"type":"string","description":"Export job identifier","example":"exp_abc123def456abc123def456"},"status":{"type":"string","description":"Export status","example":"queued"},"created":{"type":"string","format":"date-time","description":"When export was created","example":"2024-01-15T10:30:00Z"}}},"ExportStatusValue":{"type":"string","description":"Export status","example":"processing","enum":["queued","processing","completed","failed","cancelled"]},"ExportPhase":{"type":"string","description":"Current export phase","example":"indexing","x-meta":{"enumDescriptions":{"indexing":"Listing the folders and counting the messages to export","exporting":"Writing messages to the export file","complete":"All messages have been written"}},"enum":["indexing","exporting","complete"]},"ExportStatusFolders":{"type":"array","description":"Folders being exported","items":{"type":"string","example":"INBOX"}},"ExportProgress":{"type":"object","properties":{"foldersScanned":{"type":"integer","description":"Number of folders scanned","example":1},"foldersTotal":{"type":"integer","description":"Total number of folders to scan","example":2},"messagesQueued":{"type":"integer","description":"Number of messages queued for export","example":1500},"messagesExported":{"type":"integer","description":"Number of messages exported","example":500},"messagesSkipped":{"type":"integer","description":"Number of messages skipped (deleted or inaccessible)","example":5},"bytesWritten":{"type":"integer","description":"Bytes written to export file","example":52428800}}},"ExportStatus":{"type":"object","properties":{"exportId":{"type":"string","description":"Export job identifier","example":"exp_abc123def456abc123def456"},"status":{"$ref":"#/components/schemas/ExportStatusValue"},"phase":{"$ref":"#/components/schemas/ExportPhase"},"folders":{"$ref":"#/components/schemas/ExportStatusFolders"},"startDate":{"type":"string","format":"date-time","description":"Export start date filter","example":"2024-01-01T00:00:00Z"},"endDate":{"type":"string","format":"date-time","description":"Export end date filter","example":"2024-12-31T23:59:59Z"},"isEncrypted":{"type":"boolean","description":"Whether the export file is encrypted","example":false},"progress":{"$ref":"#/components/schemas/ExportProgress"},"created":{"type":"string","format":"date-time","description":"When export was created","example":"2024-01-15T10:30:00Z"},"expiresAt":{"type":"string","format":"date-time","description":"When export file expires","example":"2024-01-16T10:30:00Z"},"truncated":{"type":"boolean","description":"Whether the export was truncated due to message count or size limits. Only present (as true) for truncated exports","example":true},"error":{"type":"string","description":"Error message if export failed","example":"Mailbox listing failed","nullable":true}}},"DeleteExportResponse":{"type":"object","properties":{"deleted":{"type":"boolean","description":"True if export was deleted","example":true}}},"ExportListStatusValue":{"type":"string","description":"Export status","example":"completed","x-meta":{"enumDescriptions":{"queued":"Accepted and waiting for an export worker","processing":"Currently reading messages from the account","completed":"Finished. The download endpoint now serves the archive","failed":"Stopped on an error. See the error field","cancelled":"Deleted through the API before it finished"}},"enum":["queued","processing","completed","failed","cancelled"]},"ExportListEntry":{"type":"object","properties":{"exportId":{"type":"string","description":"Export job identifier","example":"exp_abc123def456abc123def456"},"status":{"$ref":"#/components/schemas/ExportListStatusValue"},"created":{"type":"string","format":"date-time","description":"When export was created","example":"2024-01-15T10:30:00Z"},"expiresAt":{"type":"string","format":"date-time","description":"When export file expires","example":"2024-01-16T10:30:00Z"}}},"ExportEntries":{"type":"array","description":"Export entries","items":{"$ref":"#/components/schemas/ExportListEntry"}},"ExportList":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of exports","example":5},"page":{"type":"integer","description":"Current page number","example":0},"pages":{"type":"integer","description":"Total number of pages","example":1},"exports":{"$ref":"#/components/schemas/ExportEntries"}}},"RequestFlush":{"type":"object","properties":{"flush":{"type":"boolean","description":"Only flush the account if true","default":false},"notifyFrom":{"type":"string","format":"date-time","description":"Only send webhooks for messages received after this date. Defaults to account creation time. IMAP only.","example":"2021-07-08T07:06:34.336Z","default":"now","nullable":true},"imapIndexer":{"$ref":"#/components/schemas/AccountImapIndexer"}}},"RequestFlushResponse":{"type":"object","properties":{"flush":{"type":"boolean","description":"Flush status","default":false}}},"CreateMailboxPathInput":{"type":"array","description":"Mailbox path as an array or a string. If account is namespaced then namespace prefix is added by default.","example":["Parent folder","Subfolder"],"x-constraint":{"single":true},"items":{"type":"string","maxLength":256}},"CreateMailbox":{"type":"object","properties":{"path":{"$ref":"#/components/schemas/CreateMailboxPathInput"}}},"CreateMailboxResponse":{"type":"object","properties":{"path":{"type":"string","description":"Full path to mailbox","example":"Kalender/S&APw-nnip&AOQ-evad"},"mailboxId":{"type":"string","description":"Mailbox ID (if server has support)","example":"1439876283476"},"created":{"type":"boolean","description":"Was the mailbox created","example":true}},"required":["path"]},"TargetMailboxPath":{"type":"array","description":"New mailbox path as an array or a string. If account is namespaced then namespace prefix is added by default. Optional.","example":["Parent folder","Subfolder"],"x-constraint":{"single":true},"items":{"type":"string","maxLength":256}},"ModifyMailbox":{"type":"object","properties":{"path":{"type":"string","description":"Mailbox folder path to modify","example":"Folder Name"},"newPath":{"$ref":"#/components/schemas/TargetMailboxPath"},"subscribed":{"type":"boolean","description":"Change mailbox subscription status","example":true,"x-meta":{"usage":"Only IMAP accounts have a subscription list, so this is ignored for Gmail API and MS Graph accounts. It controls whether a folder shows up in clients that list subscribed folders only; it does not affect whether EmailEngine syncs it, which `path` on the account decides."}}},"required":["path"]},"ModifyMailboxResponse":{"type":"object","properties":{"path":{"type":"string","description":"Mailbox folder path","example":"Mail"},"newPath":{"type":"string","description":"Full path to mailbox if renamed","example":"Kalender/S&APw-nnip&AOQ-evad"},"mailboxId":{"type":"string","description":"Mailbox ID after the rename (Gmail API and MS Graph API accounts only)","example":"1439876283476"},"renamed":{"type":"boolean","description":"Was the mailbox renamed","example":true},"subscribed":{"type":"boolean","description":"Subscription status after modification","example":true}}},"DeleteMailboxResponse":{"type":"object","properties":{"path":{"type":"string","description":"Full path to mailbox","example":"Kalender/S&APw-nnip&AOQ-evad"},"mailboxId":{"type":"string","description":"ID of the deleted mailbox (Gmail API and MS Graph API accounts only)","example":"1439876283476"},"deleted":{"type":"boolean","description":"Was the mailbox deleted","example":true}},"required":["path"]},"MailboxSpecialUse":{"type":"string","description":"Special folder type (Inbox, Sent, Drafts, etc.)","example":"\\Sent","enum":["\\All","\\Archive","\\Drafts","\\Flagged","\\Junk","\\Sent","\\Trash","\\Inbox"]},"MailboxSpecialUseSource":{"type":"string","description":"How the special-use flag was determined","example":"extension","x-meta":{"enumDescriptions":{"user":"Set explicitly through the API","extension":"Reported by the mail server through the SPECIAL-USE extension","name":"Guessed from the folder name"}},"enum":["user","extension","name"]},"MailboxResponseStatus":{"type":"object","description":"Additional mailbox statistics","properties":{"messages":{"type":"integer","description":"Message count from STATUS command","example":120},"unseen":{"type":"integer","description":"Unread message count from STATUS command","example":120},"error":{"type":"string","description":"Error message if the STATUS command failed for this mailbox","example":"Mailbox does not exist"}}},"MailboxResponseItem":{"type":"object","properties":{"path":{"type":"string","description":"Full path to the mailbox","example":"Kalender/S&APw-nnip&AOQ-evad"},"id":{"type":"string","description":"Stable folder ID (Gmail API and MS Graph API accounts only)","example":"AAMkAGVmMDEzMTM4LTZmYWUtNDdkNC1hMDZiLTU1OGY5OTZhYmY4OAAuAAAAAAAiQ8W967B7TKBjgx9rVEURAQAiIsqMbYjsT5e-T7KzowPTAAAAAAEMAAA="},"delimiter":{"type":"string","description":"Hierarchy delimiter character used in paths (can be null when the server uses a NIL delimiter)","example":"/","nullable":true},"parentPath":{"type":"string","description":"Path to the parent mailbox. Not set (or empty) for root level mailboxes","example":"Kalender"},"name":{"type":"string","description":"Display name of the mailbox","example":"Sünnipäevad"},"listed":{"type":"boolean","description":"Whether this mailbox appears in LIST command results","example":true},"subscribed":{"type":"boolean","description":"Whether the user is subscribed to this mailbox","example":true},"noSelect":{"type":"boolean","description":"Whether this mailbox can not be selected (virtual folders like \"\\\\All\")","example":false},"specialUse":{"$ref":"#/components/schemas/MailboxSpecialUse"},"specialUseSource":{"$ref":"#/components/schemas/MailboxSpecialUseSource"},"noInferiors":{"type":"boolean","description":"Whether this mailbox can contain child mailboxes","example":false},"messages":{"type":"integer","description":"Total number of messages in the mailbox. False if the count is not known","example":120,"enum":[false]},"uidNext":{"type":"integer","description":"Next UID value that will be assigned. False if the value is not known","example":121,"enum":[false]},"status":{"$ref":"#/components/schemas/MailboxResponseStatus"}},"required":["path","name"]},"MailboxesList":{"type":"array","items":{"$ref":"#/components/schemas/MailboxResponseItem"}},"MailboxesFilterResponse":{"type":"object","properties":{"mailboxes":{"$ref":"#/components/schemas/MailboxesList"}}},"Flags":{"type":"array","description":"Message flags","example":["\\Seen","\\Draft"],"items":{"type":"string","maxLength":128}},"MessageAction":{"type":"string","description":"What to do with the referenced message","example":"reply","x-meta":{"enumDescriptions":{"reply":"Reply to the sender","reply-all":"Reply to the sender and every other recipient","forward":"Forward the message to new recipients"}},"default":"reply","enum":["forward","reply","reply-all"],"x-convert":{"case":"lower"}},"MessageReference":{"type":"object","description":"Configuration for replying to or forwarding an existing message","properties":{"message":{"type":"string","description":"EmailEngine message ID to reply to or forward","example":"AAAAAQAACnA","maxLength":256},"action":{"$ref":"#/components/schemas/MessageAction"},"inline":{"type":"boolean","description":"Include the original message as quoted text in the response","default":false},"forwardAttachments":{"type":"boolean","description":"Include original attachments when forwarding","default":false},"ignoreMissing":{"type":"boolean","description":"Continue sending even if the referenced message cannot be found","default":false},"messageId":{"type":"string","description":"Verify the Message-ID of the referenced email matches this value before proceeding","example":"<test123@example.com>","maxLength":996},"threadId":{"type":"string","description":"Gmail thread ID to attach the outgoing message to","example":"1694936993596975454","x-meta":{"usage":"Set this when you know the Gmail thread the outgoing message belongs to and do not want EmailEngine to work it out from the referenced message.\n\nGmail API accounts only. IMAP and MS Graph derive threading from the `In-Reply-To` and `References` headers and ignore it. When both `message` and `threadId` are given, this one wins."}}}},"FromAddress":{"type":"object","description":"Sender email address","example":{"name":"From Me","address":"sender@example.com"},"properties":{"name":{"type":"string","description":"Display name for the email address","example":"Some Name","maxLength":256,"x-convert":{"trim":true}},"address":{"type":"string","description":"Email address","example":"user@example.com","x-format":{"email":{"ignoreLength":false}}}},"required":["address"]},"EmailAddress":{"type":"object","description":"Email address with optional display name","properties":{"name":{"type":"string","description":"Display name for the email address","example":"Some Name","maxLength":256,"x-convert":{"trim":true}},"address":{"type":"string","description":"Email address","example":"user@example.com","x-format":{"email":{"ignoreLength":false}}}},"required":["address"]},"AddressList":{"type":"array","description":"List of addresses","example":[{"address":"recipient@example.com"}],"x-constraint":{"single":true},"items":{"$ref":"#/components/schemas/EmailAddress"}},"AddressList1":{"type":"array","description":"List of addresses","x-constraint":{"single":true},"items":{"$ref":"#/components/schemas/EmailAddress"}},"MsgUploadContentDisposition":{"type":"string","x-meta":{"enumDescriptions":{"inline":"Rendered inside the message body, referenced by a cid: URL","attachment":"Offered as a downloadable file"}},"enum":["inline","attachment"],"x-convert":{"case":"lower"}},"MsgUploadEncoding":{"type":"string","default":"base64","enum":["base64"]},"MsgUploadReference":{"type":"string","description":"References an existing attachment by its ID instead of providing new attachment content","example":"AAAAAQAACnAcde","x-meta":{"usage":"Use this to forward an attachment that is already on another message without downloading and re-uploading it. Take the id from the attachment list of the referenced message.\n\nIt is exclusive with `content`: send one or the other, never both."},"enum":[false],"nullable":true,"maxLength":256},"UploadAttachment":{"type":"object","properties":{"filename":{"type":"string","example":"transparent.gif","maxLength":256},"contentType":{"type":"string","example":"image/gif","maxLength":256,"x-convert":{"case":"lower"}},"contentDisposition":{"$ref":"#/components/schemas/MsgUploadContentDisposition"},"cid":{"type":"string","description":"Content-ID value for embedded images","example":"unique-image-id@localhost","maxLength":256},"encoding":{"$ref":"#/components/schemas/MsgUploadEncoding"},"reference":{"$ref":"#/components/schemas/MsgUploadReference"},"content":{"type":"string","description":"Base64 formatted attachment file","example":"R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=","maxLength":52428800}},"required":["content"]},"UploadAttachmentList":{"type":"array","description":"List of attachments","items":{"$ref":"#/components/schemas/UploadAttachment"}},"CustomHeaders":{"type":"object","description":"Custom Headers","example":{"X-My-Custom-Header":"Custom header value"}},"MessageUpload":{"type":"object","properties":{"path":{"type":"string","description":"Target mailbox folder path","example":"INBOX"},"flags":{"$ref":"#/components/schemas/Flags"},"internalDate":{"type":"string","format":"date-time","description":"Sets the internal date for this message","example":"2021-07-08T07:06:34.336Z"},"reference":{"$ref":"#/components/schemas/MessageReference"},"raw":{"type":"string","description":"A Base64-encoded email message in RFC 822 format","example":"TUlNRS1WZXJzaW9uOiAxLjANClN1YmplY3Q6IGhlbGxvIHdvcmxkDQoNCkhlbGxvIQ0K","x-meta":{"usage":"Send `raw` when you have already built the MIME message yourself, for example when relaying something you fetched from another system, and it has to go out unchanged.\n\nAnything else you send alongside it overrides the matching header inside it, so a `subject` sent with a raw body replaces the subject in the message. If you are composing from parts, use `text` and `html` and let EmailEngine build the MIME structure."},"maxLength":52428800},"from":{"$ref":"#/components/schemas/FromAddress"},"to":{"$ref":"#/components/schemas/AddressList"},"cc":{"$ref":"#/components/schemas/AddressList1"},"bcc":{"$ref":"#/components/schemas/AddressList1"},"subject":{"type":"string","description":"Message subject","example":"What a wonderful message","maxLength":10240},"text":{"type":"string","description":"Message Text","example":"Hello from myself!","maxLength":52428800},"html":{"type":"string","description":"Message HTML","example":"<p>Hello from myself!</p>","maxLength":52428800},"attachments":{"$ref":"#/components/schemas/UploadAttachmentList"},"messageId":{"type":"string","description":"Message ID","example":"<test123@example.com>","maxLength":996},"headers":{"$ref":"#/components/schemas/CustomHeaders"},"locale":{"type":"string","description":"Optional locale","example":"fr","maxLength":100},"tz":{"type":"string","description":"Optional timezone","example":"Europe/Tallinn","maxLength":100}},"required":["path"]},"ResponseReference":{"type":"object","description":"Reference info if referencing was requested","properties":{"message":{"type":"string","description":"Referenced message ID. Not present when only a thread ID was referenced","example":"AAAAAQAACnA","maxLength":256},"threadId":{"type":"string","description":"Referenced thread ID (Gmail API accounts only)","example":"1694936993596975454"},"success":{"type":"boolean","description":"Was the referenced message processed","example":true},"error":{"type":"string","description":"An error message if referenced message processing failed","example":"Referenced message was not found"}}},"MessageUploadResponse":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the message. NB! This and other fields might not be present if server did not provide enough information","example":"AAAAAgAACrI"},"path":{"type":"string","description":"Folder this message was uploaded to","example":"INBOX"},"uid":{"type":"integer","description":"UID of uploaded message (IMAP accounts only)","example":12345},"uidValidity":{"type":"string","description":"UIDVALIDITY of the target folder. Numeric value cast as string. IMAP accounts only.","example":"12345"},"seq":{"type":"integer","description":"Sequence number of uploaded message (IMAP accounts only)","example":12345},"messageId":{"type":"string","description":"Message ID","example":"<test123@example.com>","maxLength":996},"reference":{"$ref":"#/components/schemas/ResponseReference"}}},"FromAddressResponse":{"type":"object","description":"Sender email address","example":{"name":"From Me","address":"sender@example.com"},"properties":{"name":{"type":"string","description":"Display name for the email address","example":"Some Name","maxLength":256,"x-convert":{"trim":true}},"address":{"type":"string","description":"Email address (can be empty for name-only entries)","example":"user@example.com"}}},"RcptAddressEntry":{"type":"object","description":"Email address with optional display name","properties":{"name":{"type":"string","description":"Display name for the email address","example":"Some Name","maxLength":256,"x-convert":{"trim":true}},"address":{"type":"string","description":"Email address (can be empty for name-only entries)","example":"user@example.com"}}},"AddressList2":{"type":"array","description":"List of email addresses","items":{"$ref":"#/components/schemas/RcptAddressEntry"}},"FlagList":{"type":"array","description":"IMAP flags set on this message","items":{"type":"string","example":"\\Seen"}},"LabelList":{"type":"array","description":"Gmail labels applied to this message","items":{"type":"string","example":"\\Important"}},"AttachmentEntry":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the attachment","example":"AAAAAgAACrIyLjI"},"contentType":{"type":"string","description":"MIME type of the attachment","example":"image/gif"},"encodedSize":{"type":"integer","description":"Size of the attachment as stored in the email (base64 encoded). The actual decoded file size is approximately 75% of this value.","example":48},"embedded":{"type":"boolean","description":"Whether the attachment is embedded in the HTML content","example":true},"inline":{"type":"boolean","description":"Whether the attachment should be displayed inline rather than as a download","example":true},"encodedInMessage":{"type":"boolean","description":"Whether the attachment is part of an enclosed message/rfc822 attachment rather than the message itself","example":false},"contentId":{"type":"string","description":"Content-ID header value used for embedding images in HTML","example":"<unique-image-id@localhost>"},"filename":{"type":"string","description":"Original filename of the attachment","example":"image.png"},"method":{"type":"string","description":"Calendar method (REQUEST, REPLY, CANCEL, etc.) for iCalendar attachments","example":"REQUEST"}}},"AttachmentList":{"type":"array","description":"List of attachments","items":{"$ref":"#/components/schemas/AttachmentEntry"}},"MessageHeaders":{"type":"object","description":"Raw email headers as key-value pairs (arrays contain multiple values for headers that appear multiple times)","example":{"from":["From Me <sender@example.com>"],"subject":["What a wonderful message"]}},"TextDetailEncodedSize":{"type":"object","description":"Sizes of different message parts","properties":{"plain":{"type":"integer","description":"Size of the plain text part in bytes","example":1013},"html":{"type":"integer","description":"Size of the HTML part in bytes","example":1013}}},"TextInfoDetails":{"type":"object","properties":{"id":{"type":"string","description":"Identifier for fetching additional text content","example":"AAAAAgAACqiTkaExkaEykA"},"encodedSize":{"$ref":"#/components/schemas/TextDetailEncodedSize"},"plain":{"type":"string","description":"Plain text version of the message","example":"Hello from myself!"},"html":{"type":"string","description":"HTML version of the message","example":"<p>Hello from myself!</p>"},"hasMore":{"type":"boolean","description":"Whether the message content was truncated (true if more content is available via separate API call)","example":false},"webSafe":{"type":"boolean","description":"Whether the HTML content has been processed into a web-safe version (set when webSafeHtml was requested). Web-safe HTML for a reply also carries the quoted thread in a single collapsed <details class=\"ee-collapsed-thread\"> element, so renderers can hide it behind one control. Its <summary> is deliberately empty - supply your own label.","example":true}}},"BounceResponse":{"type":"object","properties":{"message":{"type":"string","description":"Error message from the receiving server","example":"550 5.1.1 No such user"},"status":{"type":"string","description":"SMTP status code","example":"5.1.1"}}},"BounceEntry":{"type":"object","properties":{"message":{"type":"string","description":"EmailEngine identifier of the bounce notification","example":"AAAAAQAACnA","maxLength":256},"recipient":{"type":"string","description":"Email address that bounced","example":"recipient@example.com","x-format":{"email":true}},"action":{"type":"string","description":"Bounce action (failed, delayed, etc.)","example":"failed"},"response":{"$ref":"#/components/schemas/BounceResponse"},"date":{"type":"string","format":"date-time","description":"When the bounce was detected","example":"2021-03-22T13:13:31.000Z"}},"required":["message"]},"BounceList":{"type":"array","description":"Bounce notifications detected for this message (IMAP accounts only)","items":{"$ref":"#/components/schemas/BounceEntry"}},"MessageCategory":{"type":"string","description":"Gmail inbox tab/category of the message (Gmail API accounts only)","example":"primary","x-meta":{"enumDescriptions":{"primary":"The Primary inbox tab","social":"The Social tab (notifications from social networks)","promotions":"The Promotions tab (marketing mail)","updates":"The Updates tab (receipts, confirmations, statements)","forums":"The Forums tab (mailing lists and discussion groups)"}},"enum":["primary","social","promotions","updates","forums"]},"MailboxSpecialUse1":{"type":"string","description":"Special folder type of the mailbox containing this message (IMAP accounts only)","example":"\\Sent","x-meta":{"enumDescriptions":{"\\All":"Contains every message in the account (Gmail \"All Mail\")","\\Archive":"Archived messages","\\Drafts":"Unsent drafts","\\Flagged":"Messages the user flagged or starred","\\Junk":"Spam","\\Sent":"Sent messages","\\Trash":"Deleted messages awaiting purge","\\Inbox":"The inbox"}},"enum":["\\All","\\Archive","\\Drafts","\\Flagged","\\Junk","\\Sent","\\Trash","\\Inbox"]},"MessageSpecialUse":{"type":"string","description":"Special folder type where this message is stored","example":"\\Sent","x-meta":{"enumDescriptions":{"\\All":"Contains every message in the account (Gmail \"All Mail\")","\\Archive":"Archived messages","\\Drafts":"Unsent drafts","\\Flagged":"Messages the user flagged or starred","\\Junk":"Spam","\\Sent":"Sent messages","\\Trash":"Deleted messages awaiting purge","\\Inbox":"The inbox"}},"enum":["\\Drafts","\\Junk","\\Sent","\\Trash","\\Inbox"]},"MessageDetails":{"type":"object","properties":{"id":{"type":"string","description":"EmailEngine message identifier","example":"AAAAAgAACrI"},"uid":{"type":"integer","description":"IMAP UID (unique identifier within the mailbox). IMAP accounts only","example":12345},"emailId":{"type":"string","description":"Globally unique email identifier (when supported by the email server)","example":"1278455344230334865","maxLength":256},"threadId":{"type":"string","description":"Thread identifier for email conversations (when supported by the email server)","example":"1694936993596975454"},"path":{"type":"string","description":"Mailbox folder path that contains this message. Not returned for Gmail API accounts","example":"INBOX"},"date":{"type":"string","format":"date-time","description":"Date when the message was received by the mail server","example":"2021-03-22T13:13:31.000Z"},"draft":{"type":"boolean","description":"Whether this message is a draft","example":false},"unseen":{"type":"boolean","description":"Whether this message is unread","example":true},"flagged":{"type":"boolean","description":"Whether this message is flagged/starred","example":true},"answered":{"type":"boolean","description":"Whether this message has been answered (IMAP accounts only)","example":false},"size":{"type":"integer","description":"Message size in bytes. Not returned for MS Graph API accounts","example":1040},"subject":{"type":"string","description":"Message subject line","example":"What a wonderful message"},"from":{"$ref":"#/components/schemas/FromAddressResponse"},"sender":{"$ref":"#/components/schemas/FromAddressResponse"},"to":{"$ref":"#/components/schemas/AddressList2"},"cc":{"$ref":"#/components/schemas/AddressList2"},"bcc":{"$ref":"#/components/schemas/AddressList2"},"replyTo":{"$ref":"#/components/schemas/AddressList2"},"messageId":{"type":"string","description":"Message-ID header value","example":"<test123@example.com>"},"inReplyTo":{"type":"string","description":"Message-ID of the message this is replying to","example":"<7JBUMt0WOn+_==MOkaCOQ@mail.gmail.com>"},"flags":{"$ref":"#/components/schemas/FlagList"},"labels":{"$ref":"#/components/schemas/LabelList"},"attachments":{"$ref":"#/components/schemas/AttachmentList"},"headers":{"$ref":"#/components/schemas/MessageHeaders"},"text":{"$ref":"#/components/schemas/TextInfoDetails"},"bounces":{"$ref":"#/components/schemas/BounceList"},"isAutoReply":{"type":"boolean","description":"Whether this message appears to be an automatic reply (out of office, vacation responder, etc.)","example":false},"preview":{"type":"string","description":"Short preview of the message content (Gmail API and MS Graph API accounts only)","example":"Hello, here is the report you asked for"},"category":{"$ref":"#/components/schemas/MessageCategory"},"specialUse":{"$ref":"#/components/schemas/MailboxSpecialUse1"},"messageSpecialUse":{"$ref":"#/components/schemas/MessageSpecialUse"}}},"AddFlags":{"type":"array","description":"Flags to add to the message","example":["\\Seen"],"x-constraint":{"single":true},"items":{"type":"string","maxLength":128}},"DeleteFlags":{"type":"array","description":"Flags to remove from the message","example":["\\Flagged"],"x-constraint":{"single":true},"items":{"type":"string","maxLength":128}},"SetFlags":{"type":"array","description":"Replace all flags with this list","example":["\\Seen","\\Flagged"],"x-constraint":{"single":true},"items":{"type":"string","maxLength":128}},"FlagUpdate":{"type":"object","description":"Flag operations to perform","properties":{"add":{"$ref":"#/components/schemas/AddFlags"},"delete":{"$ref":"#/components/schemas/DeleteFlags"},"set":{"$ref":"#/components/schemas/SetFlags"}}},"AddLabels":{"type":"array","description":"Gmail labels to add (use label ID or path)","example":["Label_971539351003152516"],"x-constraint":{"single":true},"items":{"type":"string","maxLength":128}},"DeleteLabels":{"type":"array","description":"Gmail labels to remove (use label ID or path)","example":["Label_971539351003152516"],"x-constraint":{"single":true},"items":{"type":"string","maxLength":128}},"LabelUpdate":{"type":"object","description":"Label operations to perform (Gmail only)","properties":{"add":{"$ref":"#/components/schemas/AddLabels"},"delete":{"$ref":"#/components/schemas/DeleteLabels"}}},"MessageUpdate":{"type":"object","example":{"flags":{"add":"\\Seen","delete":"\\Flagged"}},"properties":{"flags":{"$ref":"#/components/schemas/FlagUpdate"},"labels":{"$ref":"#/components/schemas/LabelUpdate"}}},"FlagAddResult":{"type":"array","items":{"type":"string","example":"\\Seen"}},"FlagDeleteResult":{"type":"array","items":{"type":"string","example":"\\Seen"}},"FlagSetResult":{"type":"array","items":{"type":"string","example":"\\Seen"}},"FlagResultList":{"type":"array","description":"Resulting flag set after the update (Gmail API and MS Graph API accounts only)","example":["\\Seen"],"items":{"type":"string"}},"FlagUpdateResponse":{"type":"object","properties":{"add":{"description":"Did the add operation succeed (boolean, IMAP accounts) or the requested flags (array, API-based accounts)","example":true,"anyOf":[{"type":"boolean"},{"$ref":"#/components/schemas/FlagAddResult"}]},"delete":{"description":"Did the delete operation succeed (boolean, IMAP accounts) or the requested flags (array, API-based accounts)","example":false,"anyOf":[{"type":"boolean"},{"$ref":"#/components/schemas/FlagDeleteResult"}]},"set":{"description":"Did the set operation succeed (boolean, IMAP accounts) or the requested flags (array, API-based accounts)","example":true,"anyOf":[{"type":"boolean"},{"$ref":"#/components/schemas/FlagSetResult"}]},"result":{"$ref":"#/components/schemas/FlagResultList"}}},"LabelAddResult":{"type":"array","items":{"type":"string","example":"Label_971539351003152516"}},"LabelDeleteResult":{"type":"array","items":{"type":"string","example":"Label_971539351003152516"}},"LabelSetResult":{"type":"array","items":{"type":"string","example":"Label_971539351003152516"}},"LabelResultList":{"type":"array","description":"Resulting label set after the update (Gmail API and MS Graph API accounts only)","example":["Label1"],"items":{"type":"string"}},"LabelUpdateResponse":{"type":"object","properties":{"add":{"description":"Did the add operation succeed (boolean, IMAP accounts) or the requested labels (array, API-based accounts)","example":["Label1","Label2"],"anyOf":[{"type":"boolean"},{"$ref":"#/components/schemas/LabelAddResult"}]},"delete":{"description":"Did the delete operation succeed (boolean, IMAP accounts) or the requested labels (array, API-based accounts)","example":["Label3"],"anyOf":[{"type":"boolean"},{"$ref":"#/components/schemas/LabelDeleteResult"}]},"set":{"description":"Did the set operation succeed (boolean, IMAP accounts) or the requested labels (array, API-based accounts)","example":["Label1"],"anyOf":[{"type":"boolean"},{"$ref":"#/components/schemas/LabelSetResult"}]},"result":{"$ref":"#/components/schemas/LabelResultList"}}},"MessageUpdateResponse":{"type":"object","properties":{"flags":{"$ref":"#/components/schemas/FlagUpdateResponse"},"labels":{"$ref":"#/components/schemas/LabelUpdateResponse"}}},"MessageMovedToTrash":{"type":"object","description":"Present if message was moved to Trash","properties":{"destination":{"type":"string","description":"Trash folder path. Can be missing if the server did not provide the destination folder","example":"Trash"},"message":{"type":"string","description":"Message ID in Trash. Can be missing if the server did not provide the new message ID","example":"AAAAAwAAAWg"}}},"MessageDeleteResponse":{"type":"object","properties":{"deleted":{"type":"boolean","description":"Was the message deleted permanently. IMAP accounts return false when the message was moved to Trash, Gmail API and MS Graph API accounts return true also for moves to Trash","example":false},"moved":{"$ref":"#/components/schemas/MessageMovedToTrash"}}},"MessageMove":{"type":"object","example":{"path":"Target/Folder"},"properties":{"path":{"type":"string","description":"Destination mailbox folder path","example":"INBOX"},"source":{"type":"string","description":"Source mailbox folder path (Gmail API only). Needed to remove the label from the message.","example":"INBOX"}},"required":["path"]},"MessageMoveResponse":{"type":"object","properties":{"path":{"type":"string","description":"Destination mailbox folder path","example":"INBOX"},"id":{"type":"string","description":"ID of the moved message. Only included if the server provides it.","example":"AAAAAQAACnA","maxLength":256},"uid":{"type":"integer","description":"UID of the moved message, applies only to IMAP accounts. Only included if the server provides it.","example":12345}},"required":["path"]},"DraftSmtpEnvelopeTo":{"type":"array","x-constraint":{"single":true},"items":{"type":"string","example":"recipient@example.com","x-format":{"email":true}}},"DraftSMTPEnvelope":{"type":"object","description":"An optional object specifying the SMTP envelope used during email transmission. Only used when the message is delivered over SMTP","x-meta":{"usage":"Send this only when the SMTP envelope has to differ from the message headers, which in practice means variable envelope return paths, a bounce address that is not the From address, or delivering to an address that does not appear in the headers.\n\nLeft out, the envelope is derived from the headers, which is what you want for an ordinary message."},"properties":{"from":{"type":"string","example":"sender@example.com","x-format":{"email":true}},"to":{"$ref":"#/components/schemas/DraftSmtpEnvelopeTo"}}},"DsnReturn":{"type":"string","description":"Specifies if only headers or the entire body of the message should be included in the response (RET)","enum":["headers","full"],"x-convert":{"trim":true}},"NotifyEntry":{"type":"string","x-meta":{"enumDescriptions":{"never":"Never send a delivery status notification","success":"Notify when the message is delivered","failure":"Notify when the message cannot be delivered","delay":"Notify when the message is delayed"}},"enum":["never","success","failure","delay"]},"DsnNotify":{"type":"array","description":"Defines the conditions under which a DSN response should be sent","example":["failure","delay"],"x-constraint":{"single":true},"items":{"$ref":"#/components/schemas/NotifyEntry"}},"DraftDSN":{"type":"object","description":"Request DSN notifications. Only used when the message is delivered over SMTP.","properties":{"id":{"type":"string","description":"The envelope identifier that would be included in the response (ENVID)","example":"order-4815-notify","maxLength":256,"x-convert":{"trim":true}},"return":{"$ref":"#/components/schemas/DsnReturn"},"notify":{"$ref":"#/components/schemas/DsnNotify"},"recipient":{"type":"string","description":"The email address the DSN should be sent (ORCPT)","example":"bounces@example.com","x-format":{"email":true},"x-convert":{"trim":true}}},"required":["return"]},"SubmitDraft":{"type":"object","nullable":true,"properties":{"envelope":{"$ref":"#/components/schemas/DraftSMTPEnvelope"},"copy":{"type":"boolean","description":"If set then either copies the message to the Sent Mail folder or not. If not set then uses the account's default setting","example":null,"x-meta":{"usage":"Leave this unset to follow the account default. Set it explicitly when one message should be filed differently from the rest, for instance an automated notification you do not want in the user Sent folder.\n\nIt only affects SMTP deliveries. Gmail and MS Graph file sent messages themselves, so the flag is a no-op there."},"nullable":true},"sentMailPath":{"type":"string","description":"Upload sent message to this folder. By default the account's Sent Mail folder is used. Only applies to SMTP deliveries.","example":"Sent Mail","maxLength":1024},"sendAt":{"type":"string","format":"date-time","description":"Send message at specified time","example":"2021-07-08T07:06:34.336Z"},"deliveryAttempts":{"type":"integer","description":"How many delivery attempts to make until message is considered as failed","example":10},"gateway":{"type":"string","description":"Optional SMTP gateway ID for message routing","example":"example","maxLength":256},"dsn":{"$ref":"#/components/schemas/DraftDSN"},"proxy":{"type":"string","description":"Optional proxy URL to use when connecting to the SMTP server. A token with restricted permissions can not set this - it redirects a session that carries the account credentials","example":"socks5://proxy.example.com:1080","x-format":{"uri":{"scheme":["http","https","socks","socks4","socks4a","socks5"],"allowRelative":false}}},"localAddress":{"type":"string","description":"Optional local IP address to bind to when connecting to the SMTP server","example":"127.0.0.1","x-format":{"ip":{"cidr":"forbidden","version":["ipv4","ipv6"]}},"x-convert":{"trim":true}}}},"status":{"type":"string","description":"Whether this response was produced now or replayed from the idempotency cache","example":"MISS","x-meta":{"enumDescriptions":{"MISS":"The request ran now and this is its result","HIT":"An identical request ran earlier and its stored result was replayed"}},"enum":["MISS","HIT"]},"ResponseIdempotency":{"type":"object","description":"Idempotency info, present when an Idempotency-Key header was used","properties":{"key":{"type":"string","description":"Idempotency key from the request","example":"submit-12345","minLength":0,"maxLength":1024,"x-convert":{"trim":true}},"status":{"$ref":"#/components/schemas/status"}}},"SubmitDraftResponse":{"type":"object","properties":{"response":{"type":"string","example":"Queued for delivery"},"messageId":{"type":"string","description":"Message-ID header value","example":"<a2184d08-a470-fec6-a493-fa211a3756e9@example.com>"},"queueId":{"type":"string","description":"Queue identifier for scheduled email","example":"d41f0423195f271f"},"sendAt":{"type":"string","format":"date-time","description":"Scheduled send time","example":"2021-07-08T07:06:34.336Z"},"idempotency":{"$ref":"#/components/schemas/ResponseIdempotency"}}},"TextEncodedSize":{"type":"object","description":"Sizes of different message parts","properties":{"plain":{"type":"integer","description":"Size of the plain text part in bytes","example":1013},"html":{"type":"integer","description":"Size of the HTML part in bytes","example":1013}}},"TextInfo":{"type":"object","properties":{"id":{"type":"string","description":"Identifier for fetching the full message text","example":"AAAAAgAACqiTkaExkaEykA"},"encodedSize":{"$ref":"#/components/schemas/TextEncodedSize"}}},"MessageListEntry":{"type":"object","properties":{"id":{"type":"string","description":"EmailEngine message identifier","example":"AAAAAgAACrI"},"uid":{"type":"integer","description":"IMAP UID (unique identifier within the mailbox). IMAP accounts only","example":12345},"emailId":{"type":"string","description":"Globally unique email identifier (when supported by the email server)","example":"1278455344230334865","maxLength":256},"threadId":{"type":"string","description":"Thread identifier for email conversations (when supported by the email server)","example":"1694936993596975454"},"path":{"type":"string","description":"Mailbox folder path that contains this message. Returned when listing a virtual folder like \"\\\\All\" or when extended info is requested","example":"INBOX"},"date":{"type":"string","format":"date-time","description":"Date when the message was received by the mail server","example":"2021-03-22T13:13:31.000Z"},"draft":{"type":"boolean","description":"Whether this message is a draft","example":false},"unseen":{"type":"boolean","description":"Whether this message is unread","example":true},"flagged":{"type":"boolean","description":"Whether this message is flagged/starred","example":true},"answered":{"type":"boolean","description":"Whether this message has been answered (IMAP accounts only)","example":false},"size":{"type":"integer","description":"Message size in bytes","example":1040},"subject":{"type":"string","description":"Message subject line","example":"What a wonderful message"},"from":{"$ref":"#/components/schemas/FromAddressResponse"},"replyTo":{"$ref":"#/components/schemas/AddressList2"},"to":{"$ref":"#/components/schemas/AddressList2"},"cc":{"$ref":"#/components/schemas/AddressList2"},"messageId":{"type":"string","description":"Message-ID header value","example":"<test123@example.com>"},"inReplyTo":{"type":"string","description":"Message-ID of the message this is replying to","example":"<7JBUMt0WOn+_==MOkaCOQ@mail.gmail.com>"},"flags":{"$ref":"#/components/schemas/FlagList"},"labels":{"$ref":"#/components/schemas/LabelList"},"attachments":{"$ref":"#/components/schemas/AttachmentList"},"text":{"$ref":"#/components/schemas/TextInfo"},"preview":{"type":"string","description":"Short preview of the message content","example":"Hello, here is the report you asked for"},"category":{"$ref":"#/components/schemas/MessageCategory"},"messageSpecialUse":{"$ref":"#/components/schemas/MessageSpecialUse"},"isAutoReply":{"type":"boolean","description":"Whether this message appears to be an automatic reply (out of office, vacation responder, etc.)","example":false},"bounces":{"$ref":"#/components/schemas/BounceList"}}},"PageMessages":{"type":"array","items":{"$ref":"#/components/schemas/MessageListEntry"}},"MessageList":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of messages matching the query (exact for IMAP, approximate for Gmail API, can be omitted for MS Graph API and Outlook search results)","example":120},"page":{"type":"integer","description":"Current page number (zero-based)","example":0},"pages":{"type":"integer","description":"Total number of pages available (exact for IMAP, approximate for Gmail API, can be omitted for MS Graph API and Outlook search results)","example":24},"nextPageCursor":{"type":"string","description":"Cursor for fetching the next page (null when no more pages)","example":"imap_kcQIji3UobDDTxc","nullable":true},"prevPageCursor":{"type":"string","description":"Cursor for fetching the previous page","example":"imap_kcQIji3UobDDTxc","nullable":true},"messages":{"$ref":"#/components/schemas/PageMessages"}}},"Headers":{"type":"object","description":"Search specific email headers","example":{"Message-ID":"<1DAF52A51E674A2@example.com>"}},"HasLabels":{"type":"array","description":"Match messages that contain ALL of these labels/categories. Supported for Gmail and MS Graph (Outlook) accounts only.","example":["Horizon"],"x-constraint":{"single":true},"items":{"type":"string","maxLength":128}},"NotLabels":{"type":"array","description":"Match messages that contain NONE of these labels/categories. Supported for Gmail and MS Graph (Outlook) accounts only.","example":["Horizon"],"x-constraint":{"single":true},"items":{"type":"string","maxLength":128}},"LabelFilter":{"type":"object","description":"Filter by Gmail labels or MS Graph (Outlook) categories. Not supported for generic IMAP accounts.","properties":{"has":{"$ref":"#/components/schemas/HasLabels"},"not":{"$ref":"#/components/schemas/NotLabels"}}},"EmailIds":{"type":"array","description":"List of specific email IDs to fetch","example":["1278455344230334865"],"x-meta":{"usage":"Use this when you already know which messages you want, typically from an earlier search or from a webhook. It is not a filter that narrows the other criteria - when it is present every other search field is ignored."},"x-constraint":{"single":true},"items":{"type":"string","description":"Globally unique email identifier (when supported by the email server)","example":"1278455344230334865","maxLength":256}},"SearchQuery":{"type":"object","description":"Search criteria for filtering messages","properties":{"seq":{"type":"string","description":"Sequence number range (e.g., \"1:10\" or \"1,3,5\"). Only supported for IMAP.","example":"1:10","maxLength":8192},"answered":{"type":"boolean","description":"Filter for messages that have been replied to. Only supported for IMAP."},"deleted":{"type":"boolean","description":"Filter for messages marked for deletion. Only supported for IMAP."},"draft":{"type":"boolean","description":"Filter for draft messages"},"unseen":{"type":"boolean","description":"Filter for unread messages"},"flagged":{"type":"boolean","description":"Filter for flagged/starred messages"},"seen":{"type":"boolean","description":"Filter for read messages"},"from":{"type":"string","description":"Search in From addresses","example":"nyan.cat@example.com","maxLength":256},"to":{"type":"string","description":"Search in To addresses. Not supported for MS Graph API.","example":"support@example.com","maxLength":256},"cc":{"type":"string","description":"Search in Cc addresses. Not supported for MS Graph API.","example":"billing@example.com","maxLength":256},"bcc":{"type":"string","description":"Search in Bcc addresses. Not supported for MS Graph API.","example":"archive@example.com","maxLength":256},"body":{"type":"string","description":"Search in message body content","example":"Hello world","maxLength":256},"subject":{"type":"string","description":"Search in message subject","example":"Hello world","maxLength":2560},"larger":{"type":"integer","description":"Find messages larger than specified size in bytes. Not supported for MS Graph API.","example":1048576,"minimum":0,"maximum":1073741824},"smaller":{"type":"integer","description":"Find messages smaller than specified size in bytes. Not supported for MS Graph API.","example":102400,"minimum":0,"maximum":1073741824},"uid":{"type":"string","description":"UID range (e.g., \"100:200\" or \"150,200,250\"). Only supported for IMAP.","example":"100:200","maxLength":8192},"modseq":{"type":"integer","description":"Find messages with modification sequence higher than specified value. Only supported for IMAP with CONDSTORE.","example":12345,"minimum":0},"before":{"type":"string","format":"date-time","description":"Find messages received before this date","example":"2024-08-09"},"since":{"type":"string","format":"date-time","description":"Find messages received after this date","example":"2022-08-09"},"sentBefore":{"type":"string","format":"date-time","description":"Find messages sent before this date","example":"2024-08-09"},"sentSince":{"type":"string","format":"date-time","description":"Find messages sent after this date","example":"2022-08-09"},"emailId":{"type":"string","description":"Globally unique email identifier (when supported by the email server)","example":"1278455344230334865","maxLength":256},"threadId":{"type":"string","description":"Thread identifier for email conversations (when supported by the email server)","example":"1694936993596975454"},"header":{"$ref":"#/components/schemas/Headers"},"gmailRaw":{"type":"string","description":"Gmail search syntax (only works with Gmail accounts)","example":"has:attachment in:unread","maxLength":1024},"labels":{"$ref":"#/components/schemas/LabelFilter"},"emailIds":{"$ref":"#/components/schemas/EmailIds"}}},"MessagesUpdateRequest":{"type":"object","properties":{"search":{"$ref":"#/components/schemas/SearchQuery"},"update":{"$ref":"#/components/schemas/MessageUpdate"}},"required":["search"]},"BulkFlagAddResult":{"type":"array","items":{"type":"string","example":"\\Seen"}},"BulkFlagDeleteResult":{"type":"array","items":{"type":"string","example":"\\Seen"}},"BulkFlagSetResult":{"type":"array","items":{"type":"string","example":"\\Seen"}},"BulkFlagUpdateResponse":{"type":"object","properties":{"add":{"description":"Did the add operation succeed (boolean, IMAP accounts) or the requested flags (array, API-based accounts)","example":true,"anyOf":[{"type":"boolean"},{"$ref":"#/components/schemas/BulkFlagAddResult"}]},"delete":{"description":"Did the delete operation succeed (boolean, IMAP accounts) or the requested flags (array, API-based accounts)","example":false,"anyOf":[{"type":"boolean"},{"$ref":"#/components/schemas/BulkFlagDeleteResult"}]},"set":{"description":"Did the set operation succeed (boolean, IMAP accounts) or the requested flags (array, API-based accounts)","example":true,"anyOf":[{"type":"boolean"},{"$ref":"#/components/schemas/BulkFlagSetResult"}]}}},"BulkLabelAddResult":{"type":"array","items":{"type":"string","example":"Label_971539351003152516"}},"BulkLabelDeleteResult":{"type":"array","items":{"type":"string","example":"Label_971539351003152516"}},"BulkLabelSetResult":{"type":"array","items":{"type":"string","example":"Label_971539351003152516"}},"BulkLabelUpdateResponse":{"type":"object","properties":{"add":{"description":"Did the add operation succeed (boolean, IMAP accounts) or the requested labels (array, API-based accounts)","example":["Label1","Label2"],"anyOf":[{"type":"boolean"},{"$ref":"#/components/schemas/BulkLabelAddResult"}]},"delete":{"description":"Did the delete operation succeed (boolean, IMAP accounts) or the requested labels (array, API-based accounts)","example":["Label3"],"anyOf":[{"type":"boolean"},{"$ref":"#/components/schemas/BulkLabelDeleteResult"}]},"set":{"description":"Did the set operation succeed (boolean, IMAP accounts) or the requested labels (array, API-based accounts)","example":["Label1"],"anyOf":[{"type":"boolean"},{"$ref":"#/components/schemas/BulkLabelSetResult"}]}}},"BulkUpdatedEmailIds":{"type":"array","description":"List of updated email IDs (Gmail API and MS Graph API accounts only)","items":{"type":"string","description":"Globally unique email identifier (when supported by the email server)","example":"1278455344230334865","maxLength":256}},"BulkMessageUpdateResponse":{"type":"object","properties":{"flags":{"$ref":"#/components/schemas/BulkFlagUpdateResponse"},"labels":{"$ref":"#/components/schemas/BulkLabelUpdateResponse"},"emailIds":{"$ref":"#/components/schemas/BulkUpdatedEmailIds"}}},"MessagesDeleteRequest":{"type":"object","properties":{"search":{"$ref":"#/components/schemas/SearchQuery"}},"required":["search"]},"IdMapTuple":{"type":"array","x-constraint":{"length":2},"items":{"type":"string","description":"Message ID","maxLength":256}},"IdMapArray":{"type":"array","description":"An optional map of source and target ID values, if the server provided this info (IMAP accounts only)","example":[["AAAAAQAACnA","AAAAAwAAAD4"]],"items":{"$ref":"#/components/schemas/IdMapTuple"}},"TrashedEmailIdsArray":{"type":"array","description":"An optional list of emailId values, if the server supports unique email IDs (Gmail API and MS Graph API accounts only)","items":{"type":"string","description":"Globally unique email identifier (when supported by the email server)","example":"1278455344230334865","maxLength":256}},"MessagesMovedToTrash":{"type":"object","description":"Value is present if messages were moved to Trash","properties":{"destination":{"type":"string","description":"Trash folder path","example":"Trash"},"idMap":{"$ref":"#/components/schemas/IdMapArray"},"emailIds":{"$ref":"#/components/schemas/TrashedEmailIdsArray"}},"required":["destination"]},"DeletedEmailIdsArray":{"type":"array","description":"List of emailId values of the permanently deleted messages","items":{"type":"string","description":"Globally unique email identifier (when supported by the email server)","example":"1278455344230334865","maxLength":256}},"MessagesDeleted":{"type":"object","description":"Value is present if messages were deleted permanently (MS Graph API accounts only)","properties":{"emailIds":{"$ref":"#/components/schemas/DeletedEmailIdsArray"}}},"MessagesDeleteResponse":{"type":"object","properties":{"deleted":{"type":"boolean","description":"Was the delete action executed. IMAP accounts return false when messages were moved to Trash, Gmail API and MS Graph API accounts return true also for moves to Trash","example":false},"moved":{"$ref":"#/components/schemas/MessagesMovedToTrash"},"deletedMessages":{"$ref":"#/components/schemas/MessagesDeleted"}}},"MessagesMoveRequest":{"type":"object","properties":{"search":{"$ref":"#/components/schemas/SearchQuery"},"path":{"type":"string","description":"Target mailbox folder path","example":"INBOX"}},"required":["search","path"]},"MovedEmailIdsArray":{"type":"array","description":"An optional list of emailId values, if the server supports unique email IDs (Gmail API and MS Graph API accounts only). Null when no messages matched the search (Gmail API)","nullable":true,"items":{"type":"string","description":"Globally unique email identifier (when supported by the email server)","example":"1278455344230334865","maxLength":256}},"MessagesMoveResponse":{"type":"object","properties":{"path":{"type":"string","description":"Target mailbox folder path","example":"INBOX"},"idMap":{"$ref":"#/components/schemas/IdMapArray"},"emailIds":{"$ref":"#/components/schemas/MovedEmailIdsArray"}},"required":["path"]},"OAuth2Provider":{"type":"string","description":"OAuth2 provider","example":"gmail","enum":["gmail","gmailService","outlook","outlookService","mailRu"]},"RegisteredScopes":{"type":"array","description":"OAuth2 scopes registered for this account","items":{"type":"string","example":"https://mail.google.com/"}},"AccountTokenResponse":{"type":"object","properties":{"account":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"user":{"type":"string","description":"Username","example":"user@example.com","maxLength":256},"accessToken":{"type":"string","description":"Access Token. Can be missing if the external authentication server provided password-based credentials","example":"aGVsbG8gd29ybGQ=","maxLength":16384},"provider":{"$ref":"#/components/schemas/OAuth2Provider"},"app":{"type":"string","description":"OAuth2 application ID","example":"AAABhaBPHscAAAAH","maxLength":256},"registeredScopes":{"$ref":"#/components/schemas/RegisteredScopes"},"expires":{"type":"string","format":"date-time","description":"When the access token expires","example":"2021-03-22T13:13:31.000Z"},"cached":{"type":"boolean","description":"Whether the token was returned from cache or was freshly renewed","example":false}},"required":["account","user","provider"]},"RequestReconnect":{"type":"object","properties":{"reconnect":{"type":"boolean","description":"Only reconnect if true","default":false}}},"RequestReconnectResponse":{"type":"object","properties":{"reconnect":{"type":"boolean","description":"Reconnection status","default":false}}},"MessageSearchPayload":{"type":"object","example":{"search":{"unseen":true,"flagged":true,"from":"nyan.cat@example.com","body":"Hello world","subject":"Hello world","sentBefore":"2024-08-09","sentSince":"2022-08-09","emailId":"1278455344230334865","threadId":"1266894439832287888","header":{"Message-ID":"<12345@example.com>"},"gmailRaw":"has:attachment in:unread","labels":{"has":["Important"],"not":["Horizon"]}}},"properties":{"search":{"$ref":"#/components/schemas/SearchQuery"}},"required":["search"]},"UnprocessableErrorResponse":{"type":"object","description":"Unprocessable request error","properties":{"statusCode":{"type":"integer","description":"HTTP status code","example":422},"error":{"type":"string","description":"HTTP status text","example":"Unprocessable Entity"},"message":{"type":"string","description":"Error message","example":"The mail server does not support the requested operation"},"code":{"type":"string","description":"Machine-readable error code","example":"MissingServerExtension"}}},"SignatureResponseItem":{"type":"object","properties":{"address":{"type":"string","description":"Email address associated with the signature","example":"user@example.com","x-format":{"email":true}},"signature":{"type":"string","description":"Signature HTML code","example":"<div>Best regards,</div>"}},"required":["address","signature"]},"SignatureEntries":{"type":"array","items":{"$ref":"#/components/schemas/SignatureResponseItem"}},"AccountSignaturesResponse":{"type":"object","properties":{"signatures":{"$ref":"#/components/schemas/SignatureEntries"},"signaturesSupported":{"type":"boolean","description":"Whether the account type supports listing signatures (currently Gmail API accounts only)","example":true}}},"ReplyToAddress":{"type":"object","description":"Email address with optional display name","properties":{"name":{"type":"string","description":"Display name for the email address","example":"Some Name","maxLength":256,"x-convert":{"trim":true}},"address":{"type":"string","description":"Email address","example":"user@example.com","x-format":{"email":{"ignoreLength":false}}}},"required":["address"]},"ReplyTo":{"type":"array","description":"List of Reply-To addresses","example":[{"name":"From Me","address":"sender@example.com"}],"x-constraint":{"single":true},"items":{"$ref":"#/components/schemas/ReplyToAddress"}},"ToAddress":{"type":"object","description":"Email address with optional display name","properties":{"name":{"type":"string","description":"Display name for the email address","example":"Some Name","maxLength":256,"x-convert":{"trim":true}},"address":{"type":"string","description":"Email address","example":"user@example.com","x-format":{"email":{"ignoreLength":false}}}},"required":["address"]},"RenderValues":{"type":"object","description":"An object of variables for the template renderer","example":{"firstName":"Nyan","orderId":"4815"}},"MailMergeListEntry":{"type":"object","properties":{"to":{"$ref":"#/components/schemas/ToAddress"},"messageId":{"type":"string","description":"Message ID","example":"<test123@example.com>","maxLength":996},"params":{"$ref":"#/components/schemas/RenderValues"},"sendAt":{"type":"string","format":"date-time","description":"Send message at specified time. Overrides message level `sendAt` value.","example":"2021-07-08T07:06:34.336Z"}},"required":["to"]},"MailMergeList":{"type":"array","description":"Mail merge options. A separate email is generated for each recipient","x-meta":{"usage":"Use this to send one personalised message per recipient in a single request, instead of one request each. Each entry gets its own queue id and its own delivery.\n\nIt takes over addressing and rendering for the whole request: `messageId`, `envelope`, `to`, `cc`, `bcc` and `render` at the message root are rejected, because each entry supplies its own."},"minItems":1,"items":{"$ref":"#/components/schemas/MailMergeListEntry"}},"SmtpEnvelopeTo":{"type":"array","x-constraint":{"single":true},"items":{"type":"string","example":"recipient@example.com","x-format":{"email":true}}},"SMTPEnvelope":{"type":"object","description":"An optional object specifying the SMTP envelope used during email transmission","x-meta":{"usage":"Send this only when the SMTP envelope has to differ from the message headers, which in practice means variable envelope return paths, a bounce address that is not the From address, or delivering to an address that does not appear in the headers.\n\nLeft out, the envelope is derived from the headers, which is what you want for an ordinary message."},"properties":{"from":{"type":"string","example":"sender@example.com","x-format":{"email":true}},"to":{"$ref":"#/components/schemas/SmtpEnvelopeTo"}}},"ToAddressList":{"type":"array","description":"List of recipient addresses","example":[{"address":"recipient@example.com"}],"x-constraint":{"single":true},"items":{"$ref":"#/components/schemas/ToAddress"}},"CcAddress":{"type":"object","description":"Email address with optional display name","properties":{"name":{"type":"string","description":"Display name for the email address","example":"Some Name","maxLength":256,"x-convert":{"trim":true}},"address":{"type":"string","description":"Email address","example":"user@example.com","x-format":{"email":{"ignoreLength":false}}}},"required":["address"]},"CcAddressList":{"type":"array","description":"List of CC addresses","x-constraint":{"single":true},"items":{"$ref":"#/components/schemas/CcAddress"}},"BccAddress":{"type":"object","description":"Email address with optional display name","properties":{"name":{"type":"string","description":"Display name for the email address","example":"Some Name","maxLength":256,"x-convert":{"trim":true}},"address":{"type":"string","description":"Email address","example":"user@example.com","x-format":{"email":{"ignoreLength":false}}}},"required":["address"]},"BccAddressList":{"type":"array","description":"List of BCC addresses","x-constraint":{"single":true},"items":{"$ref":"#/components/schemas/BccAddress"}},"RenderFormat":{"type":"string","description":"Markup language the template is written in","x-meta":{"enumDescriptions":{"html":"The template is already HTML","markdown":"The template is Markdown and is converted to HTML"}},"default":"html","enum":["html","markdown"]},"TemplateRender":{"type":"object","description":"Template rendering options. Set to `false` to send the template as-is, without rendering it.","enum":[false],"properties":{"format":{"$ref":"#/components/schemas/RenderFormat"},"params":{"$ref":"#/components/schemas/RenderValues"}}},"AttachmentContentDisposition":{"type":"string","enum":["inline","attachment"],"x-convert":{"case":"lower"}},"AttachmentEncoding":{"type":"string","default":"base64","enum":["base64"]},"AttachmentReference":{"type":"string","description":"References an existing attachment by its ID instead of providing new attachment content","example":"AAAAAQAACnAcde","x-meta":{"usage":"Use this to forward an attachment that is already on another message without downloading and re-uploading it. Take the id from the attachment list of the referenced message.\n\nIt is exclusive with `content`: send one or the other, never both."},"enum":[false],"nullable":true,"maxLength":256},"UploadAttachment1":{"type":"object","properties":{"filename":{"type":"string","example":"transparent.gif","maxLength":256},"contentType":{"type":"string","example":"image/gif","maxLength":256,"x-convert":{"case":"lower"}},"contentDisposition":{"$ref":"#/components/schemas/AttachmentContentDisposition"},"cid":{"type":"string","description":"Content-ID value for embedded images","example":"unique-image-id@localhost","maxLength":256},"encoding":{"$ref":"#/components/schemas/AttachmentEncoding"},"reference":{"$ref":"#/components/schemas/AttachmentReference"},"content":{"type":"string","description":"Base64 formatted attachment file","example":"R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=","maxLength":52428800}},"required":["content"]},"UploadAttachmentList1":{"type":"array","description":"List of attachments","items":{"$ref":"#/components/schemas/UploadAttachment1"}},"DSN":{"type":"object","description":"Request DSN notifications","properties":{"id":{"type":"string","description":"The envelope identifier that would be included in the response (ENVID)","example":"order-4815-notify","maxLength":256,"x-convert":{"trim":true}},"return":{"$ref":"#/components/schemas/DsnReturn"},"notify":{"$ref":"#/components/schemas/DsnNotify"},"recipient":{"type":"string","description":"The email address the DSN should be sent (ORCPT)","example":"bounces@example.com","x-format":{"email":true},"x-convert":{"trim":true}}},"required":["return"]},"SubmitMessage":{"type":"object","example":{"to":[{"name":"Nyan Cat","address":"nyan.cat@example.com"}],"subject":"What a wonderful message!","text":"Hello from myself!","html":"<p>Hello from myself!</p>","attachments":[{"filename":"transparent.gif","content":"R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=","contentType":"image/gif"}]},"properties":{"reference":{"$ref":"#/components/schemas/MessageReference"},"from":{"$ref":"#/components/schemas/FromAddress"},"replyTo":{"$ref":"#/components/schemas/ReplyTo"},"subject":{"type":"string","description":"Email subject line","example":"What a wonderful message","maxLength":10240,"x-convert":{"trim":true}},"text":{"type":"string","description":"Plain text message content","example":"Hello from myself!","maxLength":52428800,"x-convert":{"trim":true}},"html":{"type":"string","description":"HTML message content","example":"<p>Hello from myself!</p>","maxLength":52428800,"x-convert":{"trim":true}},"previewText":{"type":"string","description":"Preview text shown in email clients after the subject line","example":"Welcome to our newsletter!","maxLength":1024},"template":{"type":"string","description":"Stored template ID to load the email content from","example":"example","maxLength":256},"mailMerge":{"$ref":"#/components/schemas/MailMergeList"},"envelope":{"$ref":"#/components/schemas/SMTPEnvelope"},"raw":{"type":"string","description":"A Base64-encoded email message in RFC 822 format","example":"TUlNRS1WZXJzaW9uOiAxLjANClN1YmplY3Q6IGhlbGxvIHdvcmxkDQoNCkhlbGxvIQ0K","x-meta":{"usage":"Send `raw` when you have already built the MIME message yourself, for example when relaying something you fetched from another system, and it has to go out unchanged.\n\nAnything else you send alongside it overrides the matching header inside it, so a `subject` sent with a raw body replaces the subject in the message. If you are composing from parts, use `text` and `html` and let EmailEngine build the MIME structure."},"maxLength":52428800},"to":{"$ref":"#/components/schemas/ToAddressList"},"cc":{"$ref":"#/components/schemas/CcAddressList"},"bcc":{"$ref":"#/components/schemas/BccAddressList"},"render":{"$ref":"#/components/schemas/TemplateRender"},"attachments":{"$ref":"#/components/schemas/UploadAttachmentList1"},"messageId":{"type":"string","description":"Message ID","example":"<test123@example.com>","maxLength":996},"headers":{"$ref":"#/components/schemas/CustomHeaders"},"trackOpens":{"type":"boolean","description":"Should EmailEngine track opens for this message","example":false},"trackClicks":{"type":"boolean","description":"Should EmailEngine track clicks for this message","example":false},"copy":{"type":"boolean","description":"If set then either copies the message to the Sent Mail folder or not. If not set then uses the account's default setting","example":null,"x-meta":{"usage":"Leave this unset to follow the account default. Set it explicitly when one message should be filed differently from the rest, for instance an automated notification you do not want in the user Sent folder.\n\nIt only affects SMTP deliveries. Gmail and MS Graph file sent messages themselves, so the flag is a no-op there."},"nullable":true},"sentMailPath":{"type":"string","description":"Upload sent message to this folder. By default the account's Sent Mail folder is used.","example":"Sent Mail","maxLength":1024},"locale":{"type":"string","description":"Optional locale","example":"fr","maxLength":100},"tz":{"type":"string","description":"Optional timezone","example":"Europe/Tallinn","maxLength":100},"sendAt":{"type":"string","format":"date-time","description":"Send message at specified time","example":"2021-07-08T07:06:34.336Z"},"deliveryAttempts":{"type":"integer","description":"How many delivery attempts to make until message is considered as failed","example":10},"gateway":{"type":"string","description":"Optional SMTP gateway ID for message routing","example":"example","maxLength":256},"listId":{"type":"string","description":"List ID for Mail Merge. Must use a subdomain name format. Lists are registered ad-hoc, so a new identifier defines a new list.","example":"test-list","x-format":{"hostname":true}},"dsn":{"$ref":"#/components/schemas/DSN"},"baseUrl":{"type":"string","description":"Optional base URL for trackers. This URL must point to your EmailEngine instance.","example":"https://customer123.myservice.com","x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}},"x-convert":{"trim":true}},"proxy":{"type":"string","description":"Optional proxy URL to use when connecting to the SMTP server. A token with restricted permissions can not set this - it redirects a session that carries the account credentials","example":"socks5://proxy.example.com:1080","x-format":{"uri":{"scheme":["http","https","socks","socks4","socks4a","socks5"],"allowRelative":false}}},"localAddress":{"type":"string","description":"Optional local IP address to bind to when connecting to the SMTP server","example":"127.0.0.1","x-format":{"ip":{"cidr":"forbidden","version":["ipv4","ipv6"]}},"x-convert":{"trim":true}},"dryRun":{"type":"boolean","description":"If true, then EmailEngine does not send the email and returns an RFC822 formatted email file. Tracking information is not added to the email.","default":false}}},"ResponseReference1":{"type":"object","description":"Reference info if referencing was requested","properties":{"message":{"type":"string","description":"Referenced message ID. Not present when only a thread ID was referenced","example":"AAAAAQAACnA","maxLength":256},"threadId":{"type":"string","description":"Referenced thread ID (Gmail API accounts only)","example":"1694936993596975454"},"success":{"type":"boolean","description":"Was the referenced message processed successfully","example":true},"error":{"type":"string","description":"An error message if referenced message processing failed","example":"Referenced message was not found"}}},"ToAddressSingle":{"type":"object","description":"Email address with optional display name","properties":{"name":{"type":"string","description":"Display name for the email address","example":"Some Name","maxLength":256,"x-convert":{"trim":true}},"address":{"type":"string","description":"Email address","example":"user@example.com","x-format":{"email":{"ignoreLength":false}}}},"required":["address"]},"SkippedMessageInfo":{"type":"object","description":"Info about skipped message. If this value is set, then the message was not sent","properties":{"reason":{"type":"string","description":"Why this message was skipped","example":"unsubscribe"},"listId":{"type":"string","example":"test-list"}}},"BulkResponseEntry":{"type":"object","example":{"success":true,"to":{"name":"Andris 2","address":"andris@ethereal.email"},"messageId":"<19b9c433-d428-f6d8-1d00-d666ebcadfc4@ekiri.ee>","queueId":"1812477338914c8372a","sendAt":"2021-07-08T07:06:34.336Z"},"properties":{"success":{"type":"boolean","description":"Was the message queued successfully","example":true},"to":{"$ref":"#/components/schemas/ToAddressSingle"},"messageId":{"type":"string","description":"Message ID","example":"<test123@example.com>","maxLength":996},"queueId":{"type":"string","description":"Queue identifier for the scheduled email","example":"d41f0423195f271f"},"sendAt":{"type":"string","format":"date-time","description":"Scheduled send time for this recipient","example":"2021-07-08T07:06:34.336Z"},"error":{"type":"string","description":"Error message if queueing failed for this recipient","example":"Failed to queue message"},"code":{"type":"string","description":"Error code if queueing failed for this recipient","example":"EENVELOPE"},"statusCode":{"type":"integer","description":"Error status code if queueing failed for this recipient","example":500,"nullable":true},"skipped":{"$ref":"#/components/schemas/SkippedMessageInfo"}}},"BulkResponseList":{"type":"array","description":"Bulk message responses","items":{"$ref":"#/components/schemas/BulkResponseEntry"}},"SubmitMessageResponse":{"type":"object","properties":{"response":{"type":"string","example":"Queued for delivery"},"messageId":{"type":"string","description":"Message-ID header value. Not present for bulk messages.","example":"<a2184d08-a470-fec6-a493-fa211a3756e9@example.com>"},"queueId":{"type":"string","description":"Queue identifier for scheduled email. Not present for bulk messages.","example":"d41f0423195f271f"},"sendAt":{"type":"string","format":"date-time","description":"Scheduled send time","example":"2021-07-08T07:06:34.336Z"},"reference":{"$ref":"#/components/schemas/ResponseReference1"},"preview":{"type":"string","description":"Base64 encoded RFC822 email if a preview was requested. Not returned for mail-merge submissions.","example":"Q29udGVudC1UeXBlOiBtdWx0aX..."},"idempotency":{"$ref":"#/components/schemas/ResponseIdempotency"},"mailMerge":{"$ref":"#/components/schemas/BulkResponseList"}}},"RequestSync":{"type":"object","properties":{"sync":{"type":"boolean","description":"Only sync if true","default":false}}},"RequestSyncResponse":{"type":"object","properties":{"sync":{"type":"boolean","description":"Sync status","default":false}}},"TextResponse":{"type":"object","properties":{"plain":{"type":"string","description":"Plaintext content","example":"Hello world"},"html":{"type":"string","description":"HTML content","example":"<p>Hello world</p>"},"hasMore":{"type":"boolean","description":"Is the current text output capped or not. Always false for Gmail API and MS Graph API accounts","example":false}}},"AccountsQueryFilter":{"type":"string","description":"Search term used for filtering, or false when no filter was applied","example":false,"enum":[false]},"AccountListState":{"type":"string","description":"Account state","example":"connected","x-meta":{"enumDescriptions":{"init":"The account was just registered and has not connected yet","connecting":"Connecting to the mail server or authorizing with the provider","syncing":"Connected and performing the initial or a periodic mailbox sync","connected":"Connected and watching for changes. This is the healthy steady state","disconnected":"The connection dropped and EmailEngine is retrying with backoff","paused":"Syncing was paused through the API. No connection is maintained","authenticationError":"The credentials were rejected. Requires re-authentication before syncing resumes","connectError":"The server could not be reached or the TLS handshake failed. Retried with backoff","unset":"No IMAP or OAuth2 configuration is set, so the account is not synced"}},"enum":["init","unset","connected","connecting","syncing","authenticationError","connectError","disconnected","paused"]},"AccountResponseItem":{"type":"object","properties":{"account":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"name":{"type":"string","description":"Display name for the account","example":"My Email Account","maxLength":256},"email":{"type":"string","description":"Default email address of the account","example":"user@example.com","x-format":{"email":true}},"type":{"$ref":"#/components/schemas/AccountType"},"app":{"type":"string","description":"OAuth2 application ID","example":"AAABhaBPHscAAAAH","maxLength":256},"state":{"$ref":"#/components/schemas/AccountListState"},"webhooks":{"type":"string","description":"Account-specific webhook URL","example":"https://myservice.com/imap/webhooks","x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"proxy":{"type":"string","description":"Proxy server URL for outbound connections","example":"socks5://proxy.example.com:1080","x-format":{"uri":{"scheme":["http","https","socks","socks4","socks4a","socks5"],"allowRelative":false}}},"smtpEhloName":{"type":"string","description":"Hostname to use in SMTP EHLO/HELO commands (defaults to system hostname)","example":"relay.example.com","nullable":true,"x-format":{"hostname":true}},"counters":{"$ref":"#/components/schemas/AccountCounters"},"syncTime":{"type":"string","format":"date-time","description":"Last sync time (IMAP accounts only)","example":"2021-02-17T13:43:18.860Z"},"lastError":{"$ref":"#/components/schemas/AccountErrorEntry"},"delegationError":{"type":"string","description":"Error message if the delegated account could not be resolved","example":"Delegated account was not found"}},"required":["account","type","state"]},"AccountEntries":{"type":"array","items":{"$ref":"#/components/schemas/AccountResponseItem"}},"AccountsFilterResponse":{"type":"object","properties":{"total":{"type":"integer","description":"How many matching entries","example":120},"page":{"type":"integer","description":"Current page (0-based index)","example":0},"pages":{"type":"integer","description":"Total page count","example":24},"query":{"$ref":"#/components/schemas/AccountsQueryFilter"},"state":{"type":"string","description":"Account state filter used for the listing, or \"*\" when no filter was applied","example":"*"},"accounts":{"$ref":"#/components/schemas/AccountEntries"}}},"AccountFormPath":{"type":"array","description":"Mailbox folders to monitor for changes (IMAP only). Use \"*\" to monitor all folders (default)","example":["*"],"x-meta":{"usage":"Leave this at `\"*\"` unless the account is large and you only care about a few folders. Narrowing it reduces the number of folders EmailEngine keeps open and indexes, which is the main cost of syncing a big mailbox.\n\nUnmonitored folders stay fully reachable through the API. What you give up is webhooks: nothing is emitted for changes in a folder that is not on this list."},"nullable":true,"x-constraint":{"single":true},"items":{"type":"string","description":"Mailbox paths to monitor for changes. Use folder names, special-use flags like \"\\Sent\", or \"*\" for all folders. Set to null to reset to default.","example":"INBOX","maxLength":1024}},"DefaultAccountType":{"type":"string","description":"Pre-select a specific account type (use \"imap\" or an OAuth2 app ID) instead of showing the selection screen","example":"imap","default":false,"enum":[false]},"RequestAuthForm":{"type":"object","properties":{"account":{"type":"string","description":"Account ID. If set to `null`, a unique ID will be generated automatically","example":"example","x-meta":{"usage":"Set this when your own system already has an identifier for the mailbox, for example a user id, so you can address the account later without storing a second id. Leave it `null` and EmailEngine generates one, which comes back in the response.\n\nReusing an existing id is an update, not an error: the registration endpoint applies the new settings to that account rather than creating a second one."},"default":null,"nullable":true,"maxLength":256,"x-convert":{"trim":true}},"name":{"type":"string","description":"Display name for the account","example":"My Email Account","maxLength":256},"email":{"type":"string","description":"Specifies the default email address for this account. Users can change it if needed.","example":"user@example.com","x-format":{"email":true}},"expectedEmail":{"type":"string","description":"Pins the account to an email address","example":"user@example.com","x-meta":{"usage":"Set this when the account is created through a hosted authentication form and you already know which mailbox the user is supposed to connect, so a user cannot finish the form against a different account than the one you provisioned.\n\nFor OAuth2 the address is compared against what the provider reports, never against anything the caller supplied, so for a shared or delegated mailbox this has to be the authenticating principal rather than the mailbox address. For IMAP it is compared against the address typed into the form, which the credentials do not prove ownership of.\n\nThe constraint stays on the account and is enforced again on every later reauthentication."},"x-format":{"email":true}},"delegated":{"type":"boolean","description":"If true, configures this account as a shared mailbox. Currently supported by MS365 OAuth2 accounts","default":false},"notifyFrom":{"type":"string","format":"date-time","description":"Only send webhooks for messages received after this date. Defaults to account creation time. IMAP only.","example":"2021-07-08T07:06:34.336Z","nullable":true},"subconnections":{"$ref":"#/components/schemas/SubconnectionPaths"},"path":{"$ref":"#/components/schemas/AccountFormPath"},"redirectUrl":{"type":"string","description":"After the authentication process is completed, the user is redirected to this URL","example":"https://myapp/account/settings.php","x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"type":{"$ref":"#/components/schemas/DefaultAccountType"}},"required":["redirectUrl"]},"RequestAuthFormResponse":{"type":"object","properties":{"url":{"type":"string","description":"Generated URL to the hosted authentication form","example":"https://ee.example.com/accounts/new?data=eyJhY2NvdW50IjoiZXhh...L0W_BkFH5HW6Krwmr7c&type=imap","x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}}},"required":["url"]},"DetectedAuthenticationInfo":{"type":"object","properties":{"user":{"type":"string","description":"Account username","example":"myuser@gmail.com","maxLength":256}}},"ResolvedServerSettings":{"type":"object","description":"Discovered IMAP settings. False if IMAP settings were not found","enum":[false],"properties":{"auth":{"$ref":"#/components/schemas/DetectedAuthenticationInfo"},"host":{"type":"string","description":"Hostname to connect to","example":"imap.gmail.com","x-format":{"hostname":true}},"port":{"type":"integer","description":"Service port number","example":993,"minimum":1,"maximum":65536},"secure":{"type":"boolean","description":"Should connection use TLS. Usually true for port 993","example":true,"default":false}}},"DiscoveredServerSettings":{"type":"object","description":"Discovered SMTP settings. False if SMTP settings were not found","enum":[false],"properties":{"auth":{"$ref":"#/components/schemas/DetectedAuthenticationInfo"},"host":{"type":"string","description":"Hostname to connect to","example":"smtp.gmail.com","x-format":{"hostname":true}},"port":{"type":"integer","description":"Service port number","example":465,"minimum":1,"maximum":65536},"secure":{"type":"boolean","description":"Should connection use TLS. Usually true for port 465","example":true,"default":false}}},"DiscoveredAppPasswordInfo":{"type":"object","description":"App password requirements for the provider, if known","properties":{"required":{"type":"boolean","description":"Whether the provider requires an app password","example":true},"provider":{"type":"string","description":"Provider name","example":"Gmail"},"instructions":{"type":"string","description":"Instructions for setting up an app password","example":"Use an app password instead of the regular account password"}}},"DiscoveredEmailSettings":{"type":"object","properties":{"imap":{"$ref":"#/components/schemas/ResolvedServerSettings"},"smtp":{"$ref":"#/components/schemas/DiscoveredServerSettings"},"appPassword":{"$ref":"#/components/schemas/DiscoveredAppPasswordInfo"},"_source":{"type":"string","description":"Source for the detected info","example":"srv"}}},"BlocklistListResponseItem":{"type":"object","properties":{"recipient":{"type":"string","description":"Listed email address","example":"user@example.com","x-format":{"email":true}},"account":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"messageId":{"type":"string","description":"Message ID","example":"<test123@example.com>"},"source":{"type":"string","description":"Which mechanism was used to add the entry","example":"api"},"reason":{"type":"string","description":"Why this entry was added","example":"block"},"remoteAddress":{"type":"string","description":"Which IP address triggered the entry","example":"198.51.100.24","x-format":{"ip":{"cidr":"optional","version":["ipv4","ipv6"]}}},"userAgent":{"type":"string","description":"Which user agent triggered the entry","example":"Mozilla/5.0 (Macintosh)"},"created":{"type":"string","format":"date-time","description":"The time this entry was added or updated","example":"2021-02-17T13:43:18.860Z"}},"required":["recipient","account","created"]},"BlocklistListEntries":{"type":"array","items":{"$ref":"#/components/schemas/BlocklistListResponseItem"}},"BlocklistListResponse":{"type":"object","properties":{"listId":{"type":"string","description":"List ID","example":"example","maxLength":256},"total":{"type":"integer","description":"How many matching entries","example":120},"page":{"type":"integer","description":"Current page (0-based index)","example":0},"pages":{"type":"integer","description":"Total page count","example":24},"addresses":{"$ref":"#/components/schemas/BlocklistListEntries"}},"required":["listId"]},"BlocklistListAddPayload":{"type":"object","properties":{"account":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"recipient":{"type":"string","description":"Email address to add to the list","example":"user@example.com","x-format":{"email":true}},"reason":{"type":"string","description":"Identifier for the blocking reason","example":"unsubscribe","default":"block"}},"required":["account","recipient"]},"BlocklistListAddResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Was the request successful","example":true},"added":{"type":"boolean","description":"Was the address added to the list","example":true}}},"DeleteBlocklistResponse":{"type":"object","properties":{"deleted":{"type":"boolean","description":"Was the address removed from the list","default":true}}},"BlocklistsResponseItem":{"type":"object","properties":{"listId":{"type":"string","description":"List ID","example":"example","maxLength":256},"count":{"type":"integer","description":"Count of blocked addresses in this list","example":12}},"required":["listId"]},"BlocklistsEntries":{"type":"array","items":{"$ref":"#/components/schemas/BlocklistsResponseItem"}},"BlocklistsResponse":{"type":"object","properties":{"total":{"type":"integer","description":"How many matching entries","example":120},"page":{"type":"integer","description":"Current page (0-based index)","example":0},"pages":{"type":"integer","description":"Total page count","example":24},"blocklists":{"$ref":"#/components/schemas/BlocklistsEntries"}}},"DeliveryTestGateway":{"type":"string","description":"Optional gateway ID","example":false,"enum":[false],"nullable":true,"maxLength":256},"DeliveryStartRequest":{"type":"object","properties":{"gateway":{"$ref":"#/components/schemas/DeliveryTestGateway"}}},"DeliveryStartResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Was the test started. Not present if queueing the test message failed","example":true},"deliveryTest":{"type":"string","description":"Test ID. Not present if queueing the test message failed","example":"6420a6ad-7f82-4e4f-8112-82a9dad1f34d","x-format":{"guid":{"version":["uuidv4","uuidv5"]}}},"error":{"type":"string","description":"Error message. Only present if queueing the test message failed - in that case success and deliveryTest are not set","example":"Oops, something went wrong"}}},"DkimResults":{"type":"object","description":"DKIM results"},"SpfResults":{"type":"object","description":"SPF results"},"DmarcResults":{"type":"object","description":"DMARC results"},"BimiResults":{"type":"object","description":"BIMI results"},"ArcResults":{"type":"object","description":"ARC results"},"MainSignature":{"type":"object","description":"Primary DKIM signature. `status.aligned` should be set, otherwise DKIM check should not be considered as passed."},"DeliveryCheckResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Was the test completed","example":true},"status":{"type":"string","description":"Test status. Only present while the test message has not yet been received (success=false)","example":"pending"},"dkim":{"$ref":"#/components/schemas/DkimResults"},"spf":{"$ref":"#/components/schemas/SpfResults"},"dmarc":{"$ref":"#/components/schemas/DmarcResults"},"bimi":{"$ref":"#/components/schemas/BimiResults"},"arc":{"$ref":"#/components/schemas/ArcResults"},"mainSig":{"$ref":"#/components/schemas/MainSignature"}}},"CreateGateway":{"type":"object","properties":{"gateway":{"type":"string","description":"Gateway ID","example":"sendgun","default":null,"maxLength":256,"x-convert":{"trim":true}},"name":{"type":"string","description":"Account Name","example":"John Smith","maxLength":256},"user":{"type":"string","description":"SMTP authentication username","example":"smtp-user","default":null,"maxLength":1024,"x-convert":{"trim":true}},"pass":{"type":"string","description":"SMTP authentication password","example":"verysecret","default":null,"maxLength":1024},"host":{"type":"string","description":"Hostname to connect to","example":"smtp.gmail.com","x-format":{"hostname":true}},"port":{"type":"integer","description":"Service port number","example":465,"minimum":1,"maximum":65536},"secure":{"type":"boolean","description":"Should connection use TLS. Usually true for port 465","example":true,"default":false}},"required":["gateway","name","host","port"]},"CreateGatewayState":{"type":"string","description":"Whether the gateway was created or updated","example":"new","x-meta":{"enumDescriptions":{"new":"The entry did not exist and was created","existing":"The entry already existed and was updated"}},"enum":["existing","new"]},"CreateGatewayResponse":{"type":"object","properties":{"gateway":{"type":"string","description":"Gateway ID","example":"example","maxLength":256},"state":{"$ref":"#/components/schemas/CreateGatewayState"}},"required":["gateway","state"]},"status1":{"type":"string","description":"Status of the last delivery attempt","example":"error","enum":["error"]},"GatewayErrorNetworkRouting":{"type":"object","description":"Network routing information for the delivery attempt","example":{"localAddress":"198.51.100.24","name":"relay.example.com"},"nullable":true},"GatewayErrorEntry":{"type":"object","description":"Information about the last failed delivery attempt using this gateway","nullable":true,"properties":{"created":{"type":"integer","description":"Timestamp of the error as milliseconds from epoch","example":1623868624153},"status":{"$ref":"#/components/schemas/status1"},"response":{"type":"string","description":"SMTP server response for the failed delivery","example":"535 Authentication failed"},"responseCode":{"type":"integer","description":"SMTP response code","example":535},"code":{"type":"string","description":"Error type identifier","example":"EAUTH"},"command":{"type":"string","description":"SMTP command that failed","example":"AUTH PLAIN"},"description":{"type":"string","description":"Error description","example":"Authentication failed"},"networkRouting":{"$ref":"#/components/schemas/GatewayErrorNetworkRouting"}}},"GatewayResponse":{"type":"object","properties":{"gateway":{"type":"string","description":"Gateway ID","example":"example","maxLength":256},"name":{"type":"string","description":"Display name for the gateway","example":"My Email Gateway","maxLength":256},"deliveries":{"type":"integer","description":"Count of email deliveries using this gateway","example":100},"lastUse":{"type":"string","format":"date-time","description":"Last delivery time. Null for gateways that have not been used yet","example":"2021-02-17T13:43:18.860Z","nullable":true},"user":{"type":"string","description":"SMTP authentication username","example":"smtp-user","nullable":true,"maxLength":1024,"x-convert":{"trim":true}},"pass":{"type":"string","description":"SMTP authentication password. Always returned as the masked value \"******\" when a password is set","example":"******","maxLength":1024},"host":{"type":"string","description":"Hostname to connect to","example":"smtp.gmail.com","x-format":{"hostname":true}},"port":{"type":"integer","description":"Service port number","example":465,"minimum":1,"maximum":65536},"secure":{"type":"boolean","description":"Should connection use TLS. Usually true for port 465","example":true,"default":false,"nullable":true},"lastError":{"$ref":"#/components/schemas/GatewayErrorEntry"}},"required":["gateway","name"]},"DeleteGatewayResponse":{"type":"object","properties":{"gateway":{"type":"string","description":"Gateway ID","example":"example","maxLength":256},"deleted":{"type":"boolean","description":"Was the gateway deleted","default":true}},"required":["gateway"]},"UpdateGateway":{"type":"object","properties":{"name":{"type":"string","description":"Account Name","example":"John Smith","maxLength":256},"user":{"type":"string","description":"SMTP authentication username","example":"smtp-user","nullable":true,"maxLength":1024,"x-convert":{"trim":true}},"pass":{"type":"string","description":"SMTP authentication password","example":"verysecret","nullable":true,"maxLength":1024},"host":{"type":"string","description":"Hostname to connect to","example":"smtp.gmail.com","x-format":{"hostname":true}},"port":{"type":"integer","description":"Service port number","example":465,"minimum":1,"maximum":65536},"secure":{"type":"boolean","description":"Should connection use TLS. Usually true for port 465","example":true}}},"UpdateGatewayResponse":{"type":"object","properties":{"gateway":{"type":"string","description":"Gateway ID","example":"example","maxLength":256}},"required":["gateway"]},"GatewayResponseItem":{"type":"object","properties":{"gateway":{"type":"string","description":"Gateway ID","example":"example","maxLength":256},"name":{"type":"string","description":"Display name for the gateway","example":"My Email Gateway","maxLength":256},"deliveries":{"type":"integer","description":"Count of email deliveries using this gateway","example":100},"lastUse":{"type":"string","format":"date-time","description":"Last delivery time. Null for gateways that have not been used yet","example":"2021-02-17T13:43:18.860Z","nullable":true},"lastError":{"$ref":"#/components/schemas/GatewayErrorEntry"}},"required":["gateway"]},"GatewayEntries":{"type":"array","items":{"$ref":"#/components/schemas/GatewayResponseItem"}},"GatewaysFilterResponse":{"type":"object","properties":{"total":{"type":"integer","description":"How many matching entries","example":120},"page":{"type":"integer","description":"Current page (0-based index)","example":0},"pages":{"type":"integer","description":"Total page count","example":24},"gateways":{"$ref":"#/components/schemas/GatewayEntries"}}},"LicenseDetails":{"type":"object","description":"Details of the registered license. False when no license is registered.","enum":[false],"properties":{"application":{"type":"string","description":"Licensed application identifier","example":"@postalsys/emailengine-app"},"key":{"type":"string","description":"License key","example":"1edf01e35e75ed3425808eba","x-format":{"hex":{"byteAligned":false,"prefix":false}}},"licensedTo":{"type":"string","description":"Organization or individual the license is issued to","example":"Kreata OÜ"},"hostname":{"type":"string","description":"Licensed hostname or environment","example":"emailengine.example.com"},"created":{"type":"string","format":"date-time","description":"License creation date","example":"2021-10-13T07:47:42.695Z"},"trial":{"type":"boolean","description":"Whether this is a trial license","example":false},"lt":{"type":"boolean","description":"Whether this is a lifetime license","example":false},"expires":{"type":"string","format":"date-time","description":"License expiration time, if the license is time-limited","example":"2026-01-01T00:00:00.000Z"}}},"LicenseResponse":{"type":"object","properties":{"active":{"type":"boolean","description":"Whether a valid license is currently active","example":true},"type":{"type":"string","description":"License type/product name","example":"EmailEngine License"},"details":{"$ref":"#/components/schemas/LicenseDetails"},"suspended":{"type":"boolean","description":"Whether email operations are suspended due to license issues","example":false}}},"RegisterLicense":{"type":"object","properties":{"license":{"type":"string","description":"License file","example":"-----BEGIN LICENSE-----\r\n...","maxLength":10240}},"required":["license"]},"EmptyLicenseResponse":{"type":"object","properties":{"active":{"type":"boolean","example":false},"details":{"type":"boolean","example":false},"type":{"type":"string","example":"LICENSE_EMAILENGINE"}}},"GoogleProjectId":{"type":"string","description":"Google Cloud Project ID","example":"project-name-425411","enum":[false],"nullable":true,"maxLength":256,"pattern":"^[a-z][a-z0-9-]{4,28}[a-z0-9]$","x-convert":{"trim":true}},"GoogleTopicName":{"type":"string","description":"Google Pub/Sub topic name for Gmail push notifications","example":"ee-pub-12345","enum":[false],"nullable":true,"maxLength":256,"pattern":"^(?!goog)[A-Za-z][A-Za-z0-9\\-_.~+%]{2,254}$","x-convert":{"trim":true}},"GoogleSubscriptionName":{"type":"string","description":"Google Pub/Sub subscription name","example":"ee-sub-12345","enum":[false],"nullable":true,"maxLength":256,"pattern":"^(?!goog)[A-Za-z][A-Za-z0-9\\-_.~+%]{2,254}$","x-convert":{"trim":true}},"AppExtraScopes":{"type":"array","description":"Additional OAuth2 scopes requested for this app","items":{"type":"string","example":"https://graph.microsoft.com/.default"}},"AppSkipScopes":{"type":"array","description":"OAuth2 scopes excluded from the defaults for this app","items":{"type":"string","example":"SMTP.Send"}},"AppBaseScopes":{"type":"string","description":"OAuth2 base scopes for this app","example":"imap","x-meta":{"enumDescriptions":{"imap":"Access mailboxes over IMAP and SMTP using OAuth2 credentials","api":"Access mailboxes through the provider API (Gmail API or MS Graph)","pubsub":"Receive Gmail push notifications through Google Pub/Sub"}},"enum":["imap","api","pubsub"],"x-convert":{"trim":true}},"AppPubSubApp":{"type":"string","description":"Cloud Pub/Sub app ID used for Gmail change notifications","example":"AAAAAQAACnA","enum":[false],"nullable":true,"maxLength":512},"PubSubError":{"type":"object","description":"Pub/Sub subscription error, if any","nullable":true,"properties":{"message":{"type":"string","description":"Error message","example":"Failed to process subscription loop"},"description":{"type":"string","description":"Error details","example":"Subscription not found","nullable":true}}},"OAuth2ResponseItem":{"type":"object","properties":{"id":{"type":"string","description":"OAuth2 application ID","example":"AAABhaBPHscAAAAH","maxLength":256},"name":{"type":"string","description":"Display name for the app","example":"My OAuth2 App","maxLength":256},"description":{"type":"string","description":"OAuth2 application description","example":"App description","maxLength":1024,"x-convert":{"trim":true}},"title":{"type":"string","description":"Title for the application button","example":"App title","maxLength":256,"x-convert":{"trim":true}},"provider":{"$ref":"#/components/schemas/OAuth2Provider"},"enabled":{"type":"boolean","description":"Is the application enabled","example":true},"created":{"type":"string","format":"date-time","description":"The time this entry was added","example":"2021-02-17T13:43:18.860Z"},"updated":{"type":"string","format":"date-time","description":"The time this entry was updated","example":"2021-02-17T13:43:18.860Z"},"includeInListing":{"type":"boolean","description":"Is the application listed in the hosted authentication form","example":true},"clientId":{"type":"string","description":"Client or Application ID for 3-legged OAuth2 applications","example":"4f05f488-d858-4f2c-bd12-1039062612fe"},"clientSecret":{"type":"string","description":"Client secret for 3-legged OAuth2 applications. Actual value is not revealed.","example":"******"},"authority":{"type":"string","description":"Authorization tenant value for Outlook OAuth2 applications","example":"common"},"redirectUrl":{"type":"string","description":"Redirect URL for 3-legged OAuth2 applications","example":"https://myservice.com/oauth","x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"serviceClient":{"type":"string","description":"Service client ID for 2-legged OAuth2 applications","example":"9103965568215821627203"},"googleProjectId":{"$ref":"#/components/schemas/GoogleProjectId"},"googleWorkspaceAccounts":{"type":"boolean","description":"Restrict OAuth2 login to Google Workspace accounts only","example":false},"googleTopicName":{"$ref":"#/components/schemas/GoogleTopicName"},"googleSubscriptionName":{"$ref":"#/components/schemas/GoogleSubscriptionName"},"serviceClientEmail":{"type":"string","description":"Service Client Email for 2-legged OAuth2 applications","example":"name@project-123.iam.gserviceaccount.com","x-format":{"email":true}},"serviceKey":{"type":"string","description":"PEM formatted service secret for 2-legged OAuth2 applications. Actual value is not revealed.","example":"******"},"extraScopes":{"$ref":"#/components/schemas/AppExtraScopes"},"skipScopes":{"$ref":"#/components/schemas/AppSkipScopes"},"baseScopes":{"$ref":"#/components/schemas/AppBaseScopes"},"pubSubApp":{"$ref":"#/components/schemas/AppPubSubApp"},"authMethod":{"type":"string","description":"Authentication method for Gmail service accounts","example":"serviceKey"},"cloud":{"type":"string","description":"Azure cloud type for Outlook OAuth2 applications","example":"global"},"tenant":{"type":"string","description":"Deprecated and unused directory tenant value. Use the authority field instead","example":"f8cdef31-a31e-4b4a-93e4-5f571e91255a"},"externalAccount":{"type":"string","description":"External account identifier for 2-legged OAuth2 applications. Actual value is not revealed.","example":"******"},"accessToken":{"type":"string","description":"Access token for app-based authentication. Actual value is not revealed.","example":"******"},"pubSubTopic":{"type":"string","description":"Cloud Pub/Sub topic name for Gmail change notifications","example":"projects/project-name/topics/ee-pub-12345"},"pubSubSubscription":{"type":"string","description":"Cloud Pub/Sub subscription name for Gmail change notifications","example":"projects/project-name/subscriptions/ee-sub-12345"},"pubSubIamPolicy":{"type":"boolean","description":"Whether the IAM policy for the Cloud Pub/Sub topic has been set up","example":true},"lastError":{"$ref":"#/components/schemas/AccountErrorEntry"},"pubSubError":{"$ref":"#/components/schemas/PubSubError"}},"required":["id","provider"]},"OAuth2Entries":{"type":"array","items":{"$ref":"#/components/schemas/OAuth2ResponseItem"}},"OAuth2FilterResponse":{"type":"object","properties":{"total":{"type":"integer","description":"How many matching entries","example":120},"page":{"type":"integer","description":"Current page (0-based index)","example":0},"pages":{"type":"integer","description":"Total page count","example":24},"apps":{"$ref":"#/components/schemas/OAuth2Entries"}}},"CreateOAuth2Provider":{"type":"string","description":"OAuth2 provider type","example":"gmail","x-meta":{"enumDescriptions":{"gmail":"Gmail and Google Workspace, using a user-consented OAuth2 flow","gmailService":"Google Workspace using a service account, with no per-user consent screen","outlook":"Outlook and Microsoft 365, using a user-consented OAuth2 flow","outlookService":"Microsoft 365 using application permissions, with no per-user consent screen","mailRu":"Mail.ru"}},"enum":["gmail","gmailService","outlook","outlookService","mailRu"],"maxLength":256,"x-convert":{"trim":true}},"OAuth2BaseScopes":{"type":"string","description":"Connection type (IMAP, API, or Pub/Sub)","example":"imap","enum":["imap","api","pubsub"],"x-convert":{"trim":true}},"PubSubAppId":{"type":"string","description":"Pub/Sub application ID for Gmail push notifications","example":"AAAAAQAACnA","enum":[false],"nullable":true,"maxLength":512},"OAuth2ExtraScopesApi":{"type":"array","items":{"type":"string","example":"User.Read","maxLength":255,"x-convert":{"trim":true}}},"OAuth2SkipScopesApi":{"type":"array","items":{"type":"string","example":"SMTP.Send","maxLength":255,"x-convert":{"trim":true}}},"authMethod":{"type":"string","description":"How token requests for the Gmail service account are signed","example":"externalAccount","x-meta":{"enumDescriptions":{"serviceKey":"Sign token requests with an uploaded service account key","externalAccount":"Sign token requests through Workload Identity Federation, with no key to store"}},"enum":["serviceKey","externalAccount"]},"CreateOAuth2App":{"type":"object","properties":{"name":{"type":"string","description":"Display name for the OAuth2 application","example":"My Gmail App","maxLength":256,"x-convert":{"trim":true}},"description":{"type":"string","description":"Detailed description of the application","example":"My cool app","maxLength":1024,"x-convert":{"trim":true}},"title":{"type":"string","description":"Short title shown on the OAuth2 button","example":"App title","maxLength":256,"x-convert":{"trim":true}},"provider":{"$ref":"#/components/schemas/CreateOAuth2Provider"},"enabled":{"type":"boolean","description":"Whether this OAuth2 app is active","example":true,"default":false},"clientId":{"type":"string","description":"OAuth2 client ID from the provider","example":"52422112755-3uov8bjwlrullq122rdm6l8ui25ho7qf.apps.googleusercontent.com","maxLength":256,"x-convert":{"trim":true}},"clientSecret":{"type":"string","description":"OAuth2 client secret from the provider","example":"boT7Q~dUljnfFdVuqpC11g8nGMjO8kpRAv-ZB","maxLength":256,"x-convert":{"trim":true}},"baseScopes":{"$ref":"#/components/schemas/OAuth2BaseScopes"},"pubSubApp":{"$ref":"#/components/schemas/PubSubAppId"},"extraScopes":{"$ref":"#/components/schemas/OAuth2ExtraScopesApi"},"skipScopes":{"$ref":"#/components/schemas/OAuth2SkipScopesApi"},"serviceClient":{"type":"string","description":"Service account unique ID (for 2-legged OAuth2)","example":"7103296518315821565203","maxLength":256,"x-convert":{"trim":true}},"googleProjectId":{"$ref":"#/components/schemas/GoogleProjectId"},"googleWorkspaceAccounts":{"type":"boolean","description":"Restrict OAuth2 login to Google Workspace accounts only","example":false},"googleTopicName":{"$ref":"#/components/schemas/GoogleTopicName"},"googleSubscriptionName":{"$ref":"#/components/schemas/GoogleSubscriptionName"},"serviceClientEmail":{"type":"string","description":"Service account email address","example":"name@project-123.iam.gserviceaccount.com","x-format":{"email":true},"x-convert":{"trim":true}},"serviceKey":{"type":"string","description":"Service account private key in PEM format","example":"-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgk...","maxLength":102400,"x-convert":{"trim":true}},"authMethod":{"$ref":"#/components/schemas/authMethod"},"externalAccount":{"type":"string","description":"Google external_account credential JSON for Workload Identity Federation","example":"{\"type\":\"external_account\",\"audience\":\"//iam.googleapis.com/projects/.../providers/...\",...}","maxLength":65536,"x-convert":{"trim":true}},"authority":{"type":"string","description":"Microsoft tenant configuration (common, organizations, consumers, or tenant ID)","example":"common","maxLength":1024,"x-convert":{"trim":true}},"cloud":{"type":"string","description":"Microsoft Azure cloud environment","example":"global","x-meta":{"enumDescriptions":{"global":"The worldwide Azure cloud, used by most tenants","gcc-high":"US Government Community Cloud High","dod":"US Department of Defense cloud","china":"Azure operated by 21Vianet in China"}},"x-convert":{"trim":true}},"redirectUrl":{"type":"string","description":"OAuth2 redirect URI configured in the provider","example":"https://myservice.com/oauth","x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}}},"required":["name","provider","serviceClient","serviceClientEmail"]},"CreateAppResponse":{"type":"object","properties":{"id":{"type":"string","description":"OAuth2 application ID","example":"AAABhaBPHscAAAAH","maxLength":256},"created":{"type":"boolean","description":"Was the app created","default":true}},"required":["id"]},"ApplicationResponse":{"type":"object","properties":{"id":{"type":"string","description":"OAuth2 application ID","example":"AAABhaBPHscAAAAH","maxLength":256},"name":{"type":"string","description":"Display name for the app","example":"My OAuth2 App","maxLength":256},"description":{"type":"string","description":"OAuth2 application description","example":"App description","maxLength":1024,"x-convert":{"trim":true}},"title":{"type":"string","description":"Title for the application button","example":"App title","maxLength":256,"x-convert":{"trim":true}},"provider":{"$ref":"#/components/schemas/OAuth2Provider"},"enabled":{"type":"boolean","description":"Is the application enabled","example":true},"created":{"type":"string","format":"date-time","description":"The time this entry was added","example":"2021-02-17T13:43:18.860Z"},"updated":{"type":"string","format":"date-time","description":"The time this entry was updated","example":"2021-02-17T13:43:18.860Z"},"includeInListing":{"type":"boolean","description":"Is the application listed in the hosted authentication form","example":true},"clientId":{"type":"string","description":"Client or Application ID for 3-legged OAuth2 applications","example":"4f05f488-d858-4f2c-bd12-1039062612fe"},"clientSecret":{"type":"string","description":"Client secret for 3-legged OAuth2 applications. Actual value is not revealed.","example":"******"},"authority":{"type":"string","description":"Authorization tenant value for Outlook OAuth2 applications","example":"common"},"redirectUrl":{"type":"string","description":"Redirect URL for 3-legged OAuth2 applications","example":"https://myservice.com/oauth","x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"googleProjectId":{"$ref":"#/components/schemas/GoogleProjectId"},"googleWorkspaceAccounts":{"type":"boolean","description":"Restrict OAuth2 login to Google Workspace accounts only","example":false},"googleTopicName":{"$ref":"#/components/schemas/GoogleTopicName"},"googleSubscriptionName":{"$ref":"#/components/schemas/GoogleSubscriptionName"},"serviceClientEmail":{"type":"string","description":"Service Client Email for 2-legged OAuth2 applications","example":"name@project-123.iam.gserviceaccount.com","x-format":{"email":true}},"serviceClient":{"type":"string","description":"Service client ID for 2-legged OAuth2 applications","example":"9103965568215821627203"},"serviceKey":{"type":"string","description":"PEM formatted service secret for 2-legged OAuth2 applications. Actual value is not revealed.","example":"******"},"accounts":{"type":"integer","description":"The number of accounts registered with this application","example":12},"extraScopes":{"$ref":"#/components/schemas/AppExtraScopes"},"skipScopes":{"$ref":"#/components/schemas/AppSkipScopes"},"baseScopes":{"$ref":"#/components/schemas/AppBaseScopes"},"pubSubApp":{"$ref":"#/components/schemas/AppPubSubApp"},"authMethod":{"type":"string","description":"Authentication method for Gmail service accounts","example":"serviceKey"},"cloud":{"type":"string","description":"Azure cloud type for Outlook OAuth2 applications","example":"global"},"tenant":{"type":"string","description":"Deprecated and unused directory tenant value. Use the authority field instead","example":"f8cdef31-a31e-4b4a-93e4-5f571e91255a"},"externalAccount":{"type":"string","description":"External account identifier for 2-legged OAuth2 applications. Actual value is not revealed.","example":"******"},"accessToken":{"type":"string","description":"Access token for app-based authentication. Actual value is not revealed.","example":"******"},"pubSubTopic":{"type":"string","description":"Cloud Pub/Sub topic name for Gmail change notifications","example":"projects/project-name/topics/ee-pub-12345"},"pubSubSubscription":{"type":"string","description":"Cloud Pub/Sub subscription name for Gmail change notifications","example":"projects/project-name/subscriptions/ee-sub-12345"},"pubSubIamPolicy":{"type":"boolean","description":"Whether the IAM policy for the Cloud Pub/Sub topic has been set up","example":true},"lastError":{"$ref":"#/components/schemas/AccountErrorEntry"},"pubSubError":{"$ref":"#/components/schemas/PubSubError"}},"required":["id","provider"]},"UpdateOAuth2ClientId":{"type":"string","description":"Client or Application ID for 3-legged OAuth2 applications","example":"52422112755-3uov8bjwlrullq122rdm6l8ui25ho7qf.apps.googleusercontent.com","enum":[false],"nullable":true,"maxLength":256,"x-convert":{"trim":true}},"UpdateOAuth2ExtraScopes":{"type":"array","description":"OAuth2 Extra Scopes","items":{"type":"string","example":"User.Read","maxLength":255,"x-convert":{"trim":true}}},"UpdateOAuth2SkipScopes":{"type":"array","description":"OAuth2 scopes to skip from the base set","items":{"type":"string","example":"SMTP.Send","maxLength":255,"x-convert":{"trim":true}}},"UpdateServiceClient":{"type":"string","description":"Service client ID for 2-legged OAuth2 applications","example":"7103296518315821565203","enum":[false],"nullable":true,"maxLength":256,"x-convert":{"trim":true}},"AzureCloud":{"type":"string","description":"Azure cloud type for Outlook OAuth2 applications","example":"global","x-meta":{"enumDescriptions":{"global":"The worldwide Azure cloud, used by most tenants","gcc-high":"US Government Community Cloud High","dod":"US Department of Defense cloud","china":"Azure operated by 21Vianet in China"}},"enum":["global","gcc-high","dod","china"],"x-convert":{"trim":true}},"UpdateOAuth2RedirectUrl":{"type":"string","description":"Redirect URL for 3-legged OAuth2 applications","example":"https://myservice.com/oauth","enum":[false],"nullable":true,"x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"UpdateOAuthApp":{"type":"object","properties":{"name":{"type":"string","description":"Application name","example":"My Gmail App","maxLength":256,"x-convert":{"trim":true}},"description":{"type":"string","description":"Application description","example":"My cool app","maxLength":1024,"x-convert":{"trim":true}},"title":{"type":"string","description":"Title for the application button","example":"App title","maxLength":256,"x-convert":{"trim":true}},"enabled":{"type":"boolean","description":"Enable this app","example":true},"clientId":{"$ref":"#/components/schemas/UpdateOAuth2ClientId"},"clientSecret":{"type":"string","description":"Client secret for 3-legged OAuth2 applications","example":"boT7Q~dUljnfFdVuqpC11g8nGMjO8kpRAv-ZB","maxLength":256,"x-convert":{"trim":true}},"pubSubApp":{"type":"string","description":"Cloud Pub/Sub app for Gmail API webhooks","example":"AAAAAQAACnA","maxLength":512},"extraScopes":{"$ref":"#/components/schemas/UpdateOAuth2ExtraScopes"},"skipScopes":{"$ref":"#/components/schemas/UpdateOAuth2SkipScopes"},"serviceClient":{"$ref":"#/components/schemas/UpdateServiceClient"},"googleProjectId":{"$ref":"#/components/schemas/GoogleProjectId"},"googleWorkspaceAccounts":{"type":"boolean","description":"Restrict OAuth2 login to Google Workspace accounts only","example":false},"googleTopicName":{"$ref":"#/components/schemas/GoogleTopicName"},"googleSubscriptionName":{"$ref":"#/components/schemas/GoogleSubscriptionName"},"serviceClientEmail":{"type":"string","description":"Service Client Email for 2-legged OAuth2 applications","example":"name@project-123.iam.gserviceaccount.com","x-format":{"email":true}},"serviceKey":{"type":"string","description":"PEM formatted service secret for 2-legged OAuth2 applications","example":"-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgk...","maxLength":102400,"x-convert":{"trim":true}},"authority":{"type":"string","description":"Authorization tenant value for Outlook OAuth2 applications","example":"common","maxLength":1024,"x-convert":{"trim":true}},"cloud":{"$ref":"#/components/schemas/AzureCloud"},"tenant":{"type":"string","example":"f8cdef31-a31e-4b4a-93e4-5f571e91255a","maxLength":1024,"x-convert":{"trim":true}},"redirectUrl":{"$ref":"#/components/schemas/UpdateOAuth2RedirectUrl"}}},"UpdateOAuthAppResponse":{"type":"object","properties":{"id":{"type":"string","description":"OAuth2 app ID","example":"example","maxLength":256},"updated":{"type":"boolean","description":"Was the application updated","example":true}},"required":["id"]},"DeleteAppRequestResponse":{"type":"object","properties":{"id":{"type":"string","description":"OAuth2 application ID","example":"AAABhaBPHscAAAAH","maxLength":256},"deleted":{"type":"boolean","description":"Was the OAuth2 application deleted","default":true},"accounts":{"type":"integer","description":"The number of accounts registered with this application","example":12}},"required":["id"]},"VerifyOAuth2AppRequest":{"type":"object","properties":{"account":{"type":"string","description":"Mailbox address used to verify domain-wide delegation and live mailbox access","example":"user@example.com","maxLength":256,"x-convert":{"trim":true}},"testConnection":{"type":"boolean","description":"Perform the live IMAP/API connection step when an access token is obtained","default":true}}},"status2":{"type":"string","description":"Step outcome","example":"ok","enum":["ok","fail","skip"]},"OAuth2VerifyStep":{"type":"object","properties":{"id":{"type":"string","description":"Step identifier","example":"signJwt"},"label":{"type":"string","description":"Human readable step name","example":"Sign assertion (signJwt)"},"status":{"$ref":"#/components/schemas/status2"},"message":{"type":"string","description":"Outcome detail","example":"Assertion signed via IAM signJwt","nullable":true},"hint":{"type":"string","description":"How to fix a failed step","example":"Grant roles/iam.serviceAccountTokenCreator to the workload principal"}}},"OAuth2VerifySteps":{"type":"array","items":{"$ref":"#/components/schemas/OAuth2VerifyStep"}},"VerifyOAuth2AppResponse":{"type":"object","properties":{"app":{"type":"string","description":"OAuth2 application ID","example":"AAABhaBPHscAAAAH","maxLength":256},"provider":{"type":"string","description":"Provider type","example":"gmailService"},"authMethod":{"type":"string","description":"Authentication method for service-account apps","example":"externalAccount","nullable":true},"account":{"type":"string","description":"Mailbox used for the delegation/mailbox checks","example":"user@example.com","nullable":true},"ok":{"type":"boolean","description":"True when no verification step failed","example":true},"steps":{"$ref":"#/components/schemas/OAuth2VerifySteps"}},"required":["app"]},"OutboxSource":{"type":"string","description":"How this message entered the queue","example":"smtp","x-meta":{"enumDescriptions":{"smtp":"Submitted through the built-in SMTP server","api":"Submitted through the REST API","test":"Generated by a deliverability test","ui":"Sent from the admin interface"}},"enum":["smtp","api","test","ui"]},"OutboxEnvelopeTo":{"type":"array","items":{"type":"string","example":"recipient@example.com","x-format":{"email":true}}},"OutboxEnvelope":{"type":"object","description":"SMTP envelope information","properties":{"from":{"type":"string","example":"sender@example.com","x-format":{"email":true}},"to":{"$ref":"#/components/schemas/OutboxEnvelopeTo"}}},"nextAttempt":{"type":"string","format":"date-time","description":"Next delivery attempt time (approximate, computed from the retry backoff without jitter). False when all delivery attempts have been used up","example":"2021-02-17T13:43:18.860Z","enum":[false]},"OutboxStatus":{"type":"string","description":"Current delivery status","example":"queued","x-meta":{"enumDescriptions":{"queued":"Accepted and waiting for a delivery attempt","processing":"A submit worker has picked the message up","smtp-starting":"Opening the SMTP connection to the destination","smtp-completed":"The SMTP transaction finished and the message was handed over","submitted":"Delivered to the receiving server. Later bounces arrive as webhooks","error":"Delivery failed. See the error field for the reason and whether it will be retried"}},"enum":["queued","processing","smtp-starting","smtp-completed","submitted","error"]},"OutboxErrorNetworkRouting":{"type":"object","description":"Network routing information for the failed delivery attempt","example":{"localAddress":"198.51.100.24","name":"relay.example.com"},"nullable":true},"OutboxListProgressError":{"type":"object","description":"Error details (when status is \"error\")","properties":{"message":{"type":"string","description":"Error description","example":"Authentication failed"},"code":{"type":"string","description":"Error code","example":"EAUTH"},"statusCode":{"type":"integer","description":"SMTP response code","example":502},"networkRouting":{"$ref":"#/components/schemas/OutboxErrorNetworkRouting"}}},"OutboxEntryProgress":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/OutboxStatus"},"response":{"type":"string","description":"SMTP server response (when status is \"submitted\" or \"smtp-completed\")","example":"250 Message Accepted"},"messageId":{"type":"string","description":"Message-ID header value of the sent message (when status is \"smtp-completed\")","example":"<test123@example.com>"},"originalMessageId":{"type":"string","description":"Original Message-ID header value if the server assigned a new one (when status is \"smtp-completed\")","example":"<test123@example.com>"},"error":{"$ref":"#/components/schemas/OutboxListProgressError"}}},"OutboxEntry":{"type":"object","properties":{"queueId":{"type":"string","description":"Unique queue entry identifier","example":"1869c5692565f756b33"},"account":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"source":{"$ref":"#/components/schemas/OutboxSource"},"messageId":{"type":"string","description":"Message-ID header value","example":"<test123@example.com>","maxLength":996},"envelope":{"$ref":"#/components/schemas/OutboxEnvelope"},"subject":{"type":"string","description":"Email subject line","example":"What a wonderful message","nullable":true,"maxLength":10240},"gateway":{"type":"string","description":"Gateway ID used for delivery, or null when no gateway is set","example":"example","nullable":true,"maxLength":256},"proxy":{"type":"string","description":"Proxy URL used for delivery, or null when no proxy is set","example":"socks5://proxy.example.com:1080","nullable":true},"localAddress":{"type":"string","description":"Local IP address used for delivery, or null when not set","example":"198.51.100.24","nullable":true},"idempotencyKey":{"type":"string","description":"Idempotency key provided when the message was submitted","example":"submit-12345","nullable":true,"maxLength":1024},"useStructuredFormat":{"type":"boolean","description":"Whether delivery errors for this message are reported in a structured format"},"created":{"type":"string","format":"date-time","description":"When this message was added to the queue","example":"2021-02-17T13:43:18.860Z"},"scheduled":{"type":"string","format":"date-time","description":"Scheduled delivery time","example":"2021-02-17T13:43:18.860Z"},"nextAttempt":{"$ref":"#/components/schemas/nextAttempt"},"attemptsMade":{"type":"integer","description":"Number of delivery attempts made","example":3},"attempts":{"type":"integer","description":"Maximum delivery attempts before marking as failed","example":3},"progress":{"$ref":"#/components/schemas/OutboxEntryProgress"}},"required":["account"]},"OutboxListEntries":{"type":"array","items":{"$ref":"#/components/schemas/OutboxEntry"}},"OutboxListResponse":{"type":"object","properties":{"total":{"type":"integer","description":"How many matching entries","example":120},"page":{"type":"integer","description":"Current page (0-based index)","example":0},"pages":{"type":"integer","description":"Total page count","example":24},"messages":{"$ref":"#/components/schemas/OutboxListEntries"}}},"DeleteOutboxEntryResponse":{"type":"object","properties":{"deleted":{"type":"boolean","description":"Was the message deleted","default":true}}},"PubSubSetupError":{"type":"object","description":"Last Pub/Sub related error for this app - either a setup error or an OAuth2 token renewal failure","nullable":true,"properties":{"response":{"type":"string","description":"Error message","example":"Enable the Cloud Pub/Sub API"}}},"PubSubAppStatus":{"type":"object","properties":{"id":{"type":"string","description":"OAuth2 application ID","example":"AAABhaBPHscAAAAH","maxLength":256},"name":{"type":"string","description":"Display name for the app","example":"My Gmail App","nullable":true,"maxLength":256},"lastError":{"$ref":"#/components/schemas/PubSubSetupError"},"pubSubError":{"$ref":"#/components/schemas/PubSubError"}},"required":["id"]},"PubSubAppStatusList":{"type":"array","items":{"$ref":"#/components/schemas/PubSubAppStatus"}},"PubSubStatusResponse":{"type":"object","properties":{"total":{"type":"integer","description":"How many matching entries","example":120},"page":{"type":"integer","description":"Current page (0-based index)","example":0},"pages":{"type":"integer","description":"Total page count","example":24},"apps":{"$ref":"#/components/schemas/PubSubAppStatusList"}}},"webhookEventsResponse":{"type":"array","description":"List of event types that will trigger webhook notifications","nullable":true,"items":{"type":"string","example":"messageNew","maxLength":256}},"webhooksCustomHeadersResponse":{"type":"array","description":"Additional HTTP headers to include with every webhook request for authentication or tracking","nullable":true,"items":{"$ref":"#/components/schemas/WebhooksCustomHeader"}},"notifyHeadersResponse":{"type":"array","description":"Email headers to include in webhook payloads for additional context","nullable":true,"items":{"type":"string","example":"List-ID","maxLength":256}},"imapIndexerResponse":{"type":"string","description":"How much of a mailbox EmailEngine tracks on each sync","example":"full","x-meta":{"enumDescriptions":{"full":"Track every change, including deletions. Slower but complete","fast":"Detect new messages only. Cheaper, but deletions and flag changes are missed"},"usage":"Leave this unset to follow the instance-wide setting, and only override it for accounts whose mailboxes behave differently from the rest of your fleet. A very large mailbox that nothing else writes to is the usual reason."},"enum":["full","fast"],"nullable":true,"x-convert":{"trim":true}},"logsResponse":{"type":"object","nullable":true,"properties":{"all":{"type":"boolean","description":"Enable detailed logging for all email accounts","example":false,"default":false},"maxLogLines":{"type":"integer","description":"Maximum number of log entries to retain per account","example":10000,"default":10000,"minimum":0,"maximum":1000000}}},"imapStrategyResponse":{"type":"string","description":"IP address selection strategy for outbound IMAP connections when multiple local addresses are available","x-meta":{"enumDescriptions":{"default":"Let the operating system pick the source address","dedicated":"Reuse the same local address for an account, so the remote server sees a stable IP","random":"Pick a random local address for every connection"}},"enum":["default","dedicated","random"],"nullable":true},"smtpStrategyResponse":{"type":"string","description":"IP address selection strategy for outbound SMTP connections when multiple local addresses are available","x-meta":{"enumDescriptions":{"default":"Let the operating system pick the source address","dedicated":"Reuse the same local address for an account, so the remote server sees a stable IP","random":"Pick a random local address for every connection"}},"enum":["default","dedicated","random"],"nullable":true},"localAddressesResponse":{"type":"array","description":"List of local IP addresses to use for outbound connections (requires appropriate network configuration)","nullable":true,"x-constraint":{"single":true},"items":{"type":"string","example":"198.51.100.24","x-format":{"ip":{"cidr":"forbidden","version":["ipv4","ipv6"]}}}},"localeResponse":{"type":"string","description":"Default language/locale for the user interface","example":"fr","enum":["en","et","fr","de","pl","ja","nl"],"nullable":true,"maxLength":100},"EventTypesList":{"type":"array","description":"Supported webhook event types","items":{"type":"string","example":"messageNew"}},"SettingsQueryResponse":{"type":"object","properties":{"webhooksEnabled":{"type":"boolean","description":"Enable or disable webhook delivery for all accounts","nullable":true},"webhooks":{"type":"string","description":"Target URL that will receive webhook notifications via POST requests","example":"https://api.example.com/email/webhooks","nullable":true,"x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"webhookEvents":{"$ref":"#/components/schemas/webhookEventsResponse"},"webhooksCustomHeaders":{"$ref":"#/components/schemas/webhooksCustomHeadersResponse"},"notifyHeaders":{"$ref":"#/components/schemas/notifyHeadersResponse"},"serviceUrl":{"type":"string","description":"Base URL of this EmailEngine instance (used for generating public URLs, path component is ignored)","example":"https://emailengine.example.com","nullable":true,"x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"notificationBaseUrl":{"type":"string","description":"Public callback URL for external OAuth providers. Falls back to serviceUrl if not set","example":"https://emailengine.example.com/notifications","nullable":true,"x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"trackClicks":{"type":"boolean","description":"Rewrite links in outgoing HTML emails to track click-through rates","nullable":true},"trackOpens":{"type":"boolean","description":"Insert a tracking pixel in outgoing HTML emails to detect when messages are opened","nullable":true},"imapIndexer":{"$ref":"#/components/schemas/imapIndexerResponse"},"resolveGmailCategories":{"type":"boolean","description":"Automatically detect and categorize Gmail tabs (Primary, Social, Promotions, etc.) for IMAP connections","nullable":true},"ignoreMailCertErrors":{"type":"boolean","description":"Allow connections to mail servers with self-signed or invalid TLS certificates (not recommended for production)","nullable":true},"generateEmailSummary":{"type":"boolean","description":"Generate AI-powered summaries for incoming emails using OpenAI","nullable":true},"openAiAPIKey":{"type":"boolean","description":"Whether a value is set for this setting. Secret values are never returned, only a boolean marker","example":true,"nullable":true},"openAiModel":{"type":"string","description":"OpenAI model to use for text generation","example":"gpt-5-mini","nullable":true},"openAiAPIUrl":{"type":"string","description":"Base URL for the OpenAI API","example":"https://api.openai.com","x-meta":{"usage":"Set this only for an OpenAI-compatible service that is not OpenAI itself, and include whatever path prefix that service mounts its API under. For Azure OpenAI that means `https://<your-resource>.openai.azure.com/openai/v1`, not the bare host."},"nullable":true,"x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"openAiTemperature":{"type":"number","description":"Controls randomness in AI responses (0 = deterministic, 2 = very creative)","example":0.8,"nullable":true,"minimum":0,"maximum":2},"openAiTopP":{"type":"number","description":"Nucleus sampling parameter for AI text generation (0-1, lower = more focused)","example":0.1,"nullable":true,"minimum":0,"maximum":1},"openAiMaxTokens":{"type":"number","description":"Maximum tokens limit for OpenAI API requests (defaults: GPT-5: 18000, GPT-4: 6500, GPT-3.5: 3000)","example":3000,"nullable":true,"minimum":0},"openAiPrompt":{"type":"string","description":"Custom system prompt to guide AI behavior when processing emails","example":"You are an assistant scanning incoming emails…","nullable":true,"maxLength":1048576},"openAiGenerateEmbeddings":{"type":"boolean","description":"Generate vector embeddings for semantic search and similarity matching","nullable":true},"inboxNewOnly":{"type":"boolean","description":"Trigger \"messageNew\" webhooks only for messages arriving in the Inbox folder","nullable":true},"serviceSecret":{"type":"boolean","description":"Whether a value is set for this setting. Secret values are never returned, only a boolean marker","example":true,"nullable":true},"authServer":{"type":"string","description":"External authentication service URL for retrieving mailbox credentials dynamically","example":"https://api.example.com/email/auth","nullable":true,"x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"tokenAuditLog":{"type":"boolean","description":"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","example":false,"nullable":true},"proxyEnabled":{"type":"boolean","description":"Route outbound connections through a proxy server","nullable":true},"proxyUrl":{"type":"string","description":"Proxy server URL for outbound connections","example":"socks5://proxy.example.com:1080","nullable":true,"x-format":{"uri":{"scheme":["http","https","socks","socks4","socks4a","socks5"],"allowRelative":false}}},"httpProxyEnabled":{"type":"boolean","description":"Route outbound HTTP/HTTPS requests (webhooks, OAuth, API calls) through an HTTP proxy","nullable":true},"httpProxyUrl":{"type":"string","description":"HTTP proxy URL for outbound HTTP/HTTPS requests","example":"http://proxy.example.com:8080","nullable":true,"x-format":{"uri":{"scheme":["http","https","socks","socks4","socks4a","socks5"],"allowRelative":false}}},"smtpEhloName":{"type":"string","description":"Hostname to use in SMTP EHLO/HELO commands (defaults to system hostname)","example":"relay.example.com","nullable":true,"x-format":{"hostname":true}},"notifyText":{"type":"boolean","description":"Include plain text message content in webhook payloads","nullable":true},"notifyWebSafeHtml":{"type":"boolean","description":"Sanitize HTML content to remove potentially dangerous elements before including in webhooks, and fold quoted thread history into a collapsed block","nullable":true},"notifyTextSize":{"type":"integer","description":"Maximum size (in bytes) of text content to include in webhook payloads","example":1048576,"nullable":true,"minimum":0},"notifyAttachments":{"type":"boolean","description":"Include attachment data in webhook payloads","nullable":true},"notifyAttachmentSize":{"type":"integer","description":"Maximum size (in bytes) per attachment to include in webhook payloads","example":5242880,"nullable":true,"minimum":0},"notifyCalendarEvents":{"type":"boolean","description":"Include parsed calendar event data in webhook payloads","nullable":true},"documentStorePassword":{"type":"boolean","description":"Whether a value is set for this setting. Secret values are never returned, only a boolean marker","example":true,"nullable":true},"logs":{"$ref":"#/components/schemas/logsResponse"},"sentryEnabled":{"type":"boolean","description":"Send unhandled error reports to a Sentry server. Applied at runtime, no restart needed. Ignored when the SENTRY_DSN environment variable is set","example":false,"nullable":true},"sentryDsn":{"type":"string","description":"Sentry DSN to send error reports to. If empty, reports go to the Sentry instance run by the EmailEngine developers","example":"https://public-key@sentry.example.com/1","nullable":true,"x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"imapStrategy":{"$ref":"#/components/schemas/imapStrategyResponse"},"smtpStrategy":{"$ref":"#/components/schemas/smtpStrategyResponse"},"localAddresses":{"$ref":"#/components/schemas/localAddressesResponse"},"smtpServerEnabled":{"type":"boolean","description":"Enable the built-in SMTP server for receiving emails","nullable":true},"smtpServerPort":{"type":"integer","description":"Port number for the built-in SMTP server","example":2525,"nullable":true,"minimum":0,"maximum":65535},"smtpServerHost":{"type":"string","description":"IP address to bind the SMTP server to (empty = all interfaces)","example":"0.0.0.0","nullable":true,"x-format":{"ip":{"cidr":"forbidden","version":["ipv4","ipv6"]}}},"smtpServerProxy":{"type":"boolean","description":"Enable PROXY protocol support for the SMTP server","nullable":true},"smtpServerAuthEnabled":{"type":"boolean","description":"Require SMTP authentication for incoming connections","nullable":true},"smtpServerPassword":{"type":"boolean","description":"Whether a value is set for this setting. Secret values are never returned, only a boolean marker","example":true,"nullable":true},"smtpServerTLSEnabled":{"type":"boolean","description":"Enable TLS/STARTTLS support for the SMTP server","nullable":true},"imapProxyServerEnabled":{"type":"boolean","description":"Enable the IMAP proxy server","nullable":true},"imapProxyServerPort":{"type":"integer","description":"Port number for the IMAP proxy server","example":9993,"nullable":true,"minimum":0,"maximum":65535},"imapProxyServerHost":{"type":"string","description":"IP address to bind the IMAP proxy to (empty = all interfaces)","example":"0.0.0.0","nullable":true,"x-format":{"ip":{"cidr":"forbidden","version":["ipv4","ipv6"]}}},"imapProxyServerProxy":{"type":"boolean","description":"Enable PROXY protocol support for the IMAP proxy","nullable":true},"imapProxyServerPassword":{"type":"boolean","description":"Whether a value is set for this setting. Secret values are never returned, only a boolean marker","example":true,"nullable":true},"imapProxyServerTLSEnabled":{"type":"boolean","description":"Enable TLS support for the IMAP proxy","nullable":true},"queueKeep":{"type":"integer","description":"Number of completed and failed queue entries to retain for debugging","example":50,"nullable":true,"minimum":0},"deliveryAttempts":{"type":"integer","description":"Maximum number of delivery attempts before marking a message as permanently failed","example":10,"nullable":true,"minimum":0},"gmailSubscriptionTtl":{"type":"integer","description":"Gmail Pub/Sub subscription inactivity expiration in days. Empty for Google default (31 days), 0 for no expiration.","example":31,"nullable":true,"minimum":0,"maximum":365},"templateHeader":{"type":"string","description":"Custom HTML to inject at the top of hosted pages (e.g., for branding)","example":"<div class=\"brand-bar\">Acme Mail</div>","nullable":true,"maxLength":1048576,"x-convert":{"trim":true}},"templateHtmlHead":{"type":"string","description":"Custom HTML to inject into the <head> section of hosted pages (e.g., for analytics)","example":"<link rel=\"stylesheet\" href=\"https://example.com/brand.css\">","nullable":true,"maxLength":1048576,"x-convert":{"trim":true}},"scriptEnv":{"type":"string","description":"JSON object containing environment variables available to pre-processing scripts","example":"{\"key\":\"value\"}","nullable":true,"maxLength":1048576,"x-convert":{"trim":true}},"enableApiProxy":{"type":"boolean","description":"Trust X-Forwarded-* headers when behind a reverse proxy","nullable":true},"locale":{"$ref":"#/components/schemas/localeResponse"},"timezone":{"type":"string","description":"Default timezone for date/time display (IANA timezone identifier)","example":"Europe/Tallinn","nullable":true,"maxLength":100},"pageBrandName":{"type":"string","description":"Brand name displayed in page titles","example":"EmailEngine","nullable":true,"maxLength":1024},"openAiPreProcessingFn":{"type":"string","description":"JavaScript function to filter emails before AI processing (return true to process, false to skip)","example":"return true; // pass every email","nullable":true,"maxLength":524288},"imapClientName":{"type":"string","description":"Client name advertised via IMAP ID extension","example":"EmailEngine","nullable":true,"maxLength":1024},"imapClientVersion":{"type":"string","description":"Client version advertised via IMAP ID extension","example":"1.3.45","nullable":true,"maxLength":1024},"imapClientVendor":{"type":"string","description":"Vendor name advertised via IMAP ID extension","example":"Postal Systems","nullable":true,"maxLength":1024},"imapClientSupportUrl":{"type":"string","description":"Support URL advertised via IMAP ID extension","example":"https://github.com/postalsys/emailengine/issues","nullable":true,"x-format":{"uri":{"scheme":["http","https","mailto"],"allowRelative":false}}},"exportMaxConcurrent":{"type":"integer","description":"Maximum concurrent exports per account","example":2,"nullable":true,"minimum":1,"maximum":100},"exportMaxGlobalConcurrent":{"type":"integer","description":"Maximum concurrent exports system-wide across all accounts","example":8,"nullable":true,"minimum":1,"maximum":100},"gmailExportBatchSize":{"type":"integer","description":"Number of parallel message fetch requests for Gmail export operations (default: 10, max: 50)","example":10,"nullable":true,"minimum":1,"maximum":50},"outlookExportBatchSize":{"type":"integer","description":"Number of messages per batch request for Outlook export operations (default: 20, max: 20 - MS Graph API limit)","example":20,"nullable":true,"minimum":1,"maximum":20},"exportMaxMessages":{"type":"integer","description":"Maximum number of messages per export (default: 500000)","example":500000,"nullable":true,"minimum":1,"maximum":10000000},"exportMaxSize":{"type":"integer","description":"Maximum export file size in bytes (default: 10GB)","example":10737418240,"nullable":true,"minimum":1},"eventTypes":{"$ref":"#/components/schemas/EventTypesList"}}},"WebhookEvents":{"type":"array","description":"List of event types that will trigger webhook notifications","items":{"type":"string","example":"messageNew","maxLength":256}},"WebhooksCustomHeaders":{"type":"array","description":"Additional HTTP headers to include with every webhook request for authentication or tracking","items":{"$ref":"#/components/schemas/WebhooksCustomHeader"}},"NotifyHeaders":{"type":"array","description":"Email headers to include in webhook payloads for additional context","items":{"type":"string","example":"List-ID","maxLength":256}},"ImapIndexer":{"type":"string","description":"How much of a mailbox EmailEngine tracks on each sync","example":"full","x-meta":{"enumDescriptions":{"full":"Track every change, including deletions. Slower but complete","fast":"Detect new messages only. Cheaper, but deletions and flag changes are missed"},"usage":"Leave this unset to follow the instance-wide setting, and only override it for accounts whose mailboxes behave differently from the rest of your fleet. A very large mailbox that nothing else writes to is the usual reason."},"enum":["full","fast"],"x-convert":{"trim":true}},"LogSettings":{"type":"object","properties":{"all":{"type":"boolean","description":"Enable detailed logging for all email accounts","example":false,"default":false},"maxLogLines":{"type":"integer","description":"Maximum number of log entries to retain per account","example":10000,"default":10000,"minimum":0,"maximum":1000000}}},"ImapStrategy":{"type":"string","description":"IP address selection strategy for outbound IMAP connections when multiple local addresses are available","x-meta":{"enumDescriptions":{"default":"Let the operating system pick the source address","dedicated":"Reuse the same local address for an account, so the remote server sees a stable IP","random":"Pick a random local address for every connection"}},"enum":["default","dedicated","random"]},"SmtpStrategy":{"type":"string","description":"IP address selection strategy for outbound SMTP connections when multiple local addresses are available","x-meta":{"enumDescriptions":{"default":"Let the operating system pick the source address","dedicated":"Reuse the same local address for an account, so the remote server sees a stable IP","random":"Pick a random local address for every connection"}},"enum":["default","dedicated","random"]},"LocalAddresses":{"type":"array","description":"List of local IP addresses to use for outbound connections (requires appropriate network configuration)","x-constraint":{"single":true},"items":{"type":"string","example":"198.51.100.24","x-format":{"ip":{"cidr":"forbidden","version":["ipv4","ipv6"]}}}},"SettingsLocale":{"type":"string","description":"Default language/locale for the user interface","example":"fr","enum":["en","et","fr","de","pl","ja","nl"],"maxLength":100},"Settings":{"type":"object","properties":{"webhooksEnabled":{"type":"boolean","description":"Enable or disable webhook delivery for all accounts"},"webhooks":{"type":"string","description":"Target URL that will receive webhook notifications via POST requests","example":"https://api.example.com/email/webhooks","x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"webhookEvents":{"$ref":"#/components/schemas/WebhookEvents"},"webhooksCustomHeaders":{"$ref":"#/components/schemas/WebhooksCustomHeaders"},"notifyHeaders":{"$ref":"#/components/schemas/NotifyHeaders"},"serviceUrl":{"type":"string","description":"Base URL of this EmailEngine instance (used for generating public URLs, path component is ignored)","example":"https://emailengine.example.com","x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"notificationBaseUrl":{"type":"string","description":"Public callback URL for external OAuth providers. Falls back to serviceUrl if not set","example":"https://emailengine.example.com/notifications","nullable":true,"x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"trackClicks":{"type":"boolean","description":"Rewrite links in outgoing HTML emails to track click-through rates"},"trackOpens":{"type":"boolean","description":"Insert a tracking pixel in outgoing HTML emails to detect when messages are opened"},"imapIndexer":{"$ref":"#/components/schemas/ImapIndexer"},"resolveGmailCategories":{"type":"boolean","description":"Automatically detect and categorize Gmail tabs (Primary, Social, Promotions, etc.) for IMAP connections"},"ignoreMailCertErrors":{"type":"boolean","description":"Allow connections to mail servers with self-signed or invalid TLS certificates (not recommended for production)"},"generateEmailSummary":{"type":"boolean","description":"Generate AI-powered summaries for incoming emails using OpenAI"},"openAiAPIKey":{"type":"string","description":"Your OpenAI API key for AI features","example":"sk-…"},"openAiModel":{"type":"string","description":"OpenAI model to use for text generation","example":"gpt-5-mini"},"openAiAPIUrl":{"type":"string","description":"Base URL for the OpenAI API","example":"https://api.openai.com","x-meta":{"usage":"Set this only for an OpenAI-compatible service that is not OpenAI itself, and include whatever path prefix that service mounts its API under. For Azure OpenAI that means `https://<your-resource>.openai.azure.com/openai/v1`, not the bare host."},"x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"openAiTemperature":{"type":"number","description":"Controls randomness in AI responses (0 = deterministic, 2 = very creative)","example":0.8,"minimum":0,"maximum":2},"openAiTopP":{"type":"number","description":"Nucleus sampling parameter for AI text generation (0-1, lower = more focused)","example":0.1,"minimum":0,"maximum":1},"openAiMaxTokens":{"type":"number","description":"Maximum tokens limit for OpenAI API requests (defaults: GPT-5: 18000, GPT-4: 6500, GPT-3.5: 3000)","example":3000,"minimum":0},"openAiPrompt":{"type":"string","description":"Custom system prompt to guide AI behavior when processing emails","example":"You are an assistant scanning incoming emails…","maxLength":1048576},"openAiGenerateEmbeddings":{"type":"boolean","description":"Generate vector embeddings for semantic search and similarity matching"},"inboxNewOnly":{"type":"boolean","description":"Trigger \"messageNew\" webhooks only for messages arriving in the Inbox folder"},"serviceSecret":{"type":"string","description":"HMAC secret for signing API requests and validating webhooks","example":"verysecret"},"authServer":{"type":"string","description":"External authentication service URL for retrieving mailbox credentials dynamically","example":"https://api.example.com/email/auth","x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"tokenAuditLog":{"type":"boolean","description":"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","example":false},"proxyEnabled":{"type":"boolean","description":"Route outbound connections through a proxy server"},"proxyUrl":{"type":"string","description":"Proxy server URL for outbound connections","example":"socks5://proxy.example.com:1080","x-format":{"uri":{"scheme":["http","https","socks","socks4","socks4a","socks5"],"allowRelative":false}}},"httpProxyEnabled":{"type":"boolean","description":"Route outbound HTTP/HTTPS requests (webhooks, OAuth, API calls) through an HTTP proxy"},"httpProxyUrl":{"type":"string","description":"HTTP proxy URL for outbound HTTP/HTTPS requests","example":"http://proxy.example.com:8080","x-format":{"uri":{"scheme":["http","https","socks","socks4","socks4a","socks5"],"allowRelative":false}}},"smtpEhloName":{"type":"string","description":"Hostname to use in SMTP EHLO/HELO commands (defaults to system hostname)","example":"relay.example.com","nullable":true,"x-format":{"hostname":true}},"notifyText":{"type":"boolean","description":"Include plain text message content in webhook payloads"},"notifyWebSafeHtml":{"type":"boolean","description":"Sanitize HTML content to remove potentially dangerous elements before including in webhooks, and fold quoted thread history into a collapsed block"},"notifyTextSize":{"type":"integer","description":"Maximum size (in bytes) of text content to include in webhook payloads","example":1048576,"minimum":0},"notifyAttachments":{"type":"boolean","description":"Include attachment data in webhook payloads"},"notifyAttachmentSize":{"type":"integer","description":"Maximum size (in bytes) per attachment to include in webhook payloads","example":5242880,"minimum":0},"notifyCalendarEvents":{"type":"boolean","description":"Include parsed calendar event data in webhook payloads"},"logs":{"$ref":"#/components/schemas/LogSettings"},"sentryEnabled":{"type":"boolean","description":"Send unhandled error reports to a Sentry server. Applied at runtime, no restart needed. Ignored when the SENTRY_DSN environment variable is set","example":false},"sentryDsn":{"type":"string","description":"Sentry DSN to send error reports to. If empty, reports go to the Sentry instance run by the EmailEngine developers","example":"https://public-key@sentry.example.com/1","nullable":true,"x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"imapStrategy":{"$ref":"#/components/schemas/ImapStrategy"},"smtpStrategy":{"$ref":"#/components/schemas/SmtpStrategy"},"localAddresses":{"$ref":"#/components/schemas/LocalAddresses"},"smtpServerEnabled":{"type":"boolean","description":"Enable the built-in SMTP server for receiving emails"},"smtpServerPort":{"type":"integer","description":"Port number for the built-in SMTP server","example":2525,"minimum":0,"maximum":65535},"smtpServerHost":{"type":"string","description":"IP address to bind the SMTP server to (empty = all interfaces)","example":"0.0.0.0","x-format":{"ip":{"cidr":"forbidden","version":["ipv4","ipv6"]}}},"smtpServerProxy":{"type":"boolean","description":"Enable PROXY protocol support for the SMTP server"},"smtpServerAuthEnabled":{"type":"boolean","description":"Require SMTP authentication for incoming connections"},"smtpServerPassword":{"type":"string","description":"Password for SMTP authentication (null = disable authentication)","example":"verysecret","nullable":true,"maxLength":1024},"smtpServerTLSEnabled":{"type":"boolean","description":"Enable TLS/STARTTLS support for the SMTP server"},"imapProxyServerEnabled":{"type":"boolean","description":"Enable the IMAP proxy server"},"imapProxyServerPort":{"type":"integer","description":"Port number for the IMAP proxy server","example":9993,"minimum":0,"maximum":65535},"imapProxyServerHost":{"type":"string","description":"IP address to bind the IMAP proxy to (empty = all interfaces)","example":"0.0.0.0","x-format":{"ip":{"cidr":"forbidden","version":["ipv4","ipv6"]}}},"imapProxyServerProxy":{"type":"boolean","description":"Enable PROXY protocol support for the IMAP proxy"},"imapProxyServerPassword":{"type":"string","description":"Password for IMAP proxy authentication (null = disable authentication)","example":"verysecret","nullable":true,"maxLength":1024},"imapProxyServerTLSEnabled":{"type":"boolean","description":"Enable TLS support for the IMAP proxy"},"queueKeep":{"type":"integer","description":"Number of completed and failed queue entries to retain for debugging","example":50,"minimum":0},"deliveryAttempts":{"type":"integer","description":"Maximum number of delivery attempts before marking a message as permanently failed","example":10,"minimum":0},"gmailSubscriptionTtl":{"type":"integer","description":"Gmail Pub/Sub subscription inactivity expiration in days. Empty for Google default (31 days), 0 for no expiration.","example":31,"minimum":0,"maximum":365},"templateHeader":{"type":"string","description":"Custom HTML to inject at the top of hosted pages (e.g., for branding)","example":"<div class=\"brand-bar\">Acme Mail</div>","maxLength":1048576,"x-convert":{"trim":true}},"templateHtmlHead":{"type":"string","description":"Custom HTML to inject into the <head> section of hosted pages (e.g., for analytics)","example":"<link rel=\"stylesheet\" href=\"https://example.com/brand.css\">","maxLength":1048576,"x-convert":{"trim":true}},"scriptEnv":{"type":"string","description":"JSON object containing environment variables available to pre-processing scripts","example":"{\"key\":\"value\"}","maxLength":1048576,"x-convert":{"trim":true}},"enableApiProxy":{"type":"boolean","description":"Trust X-Forwarded-* headers when behind a reverse proxy"},"locale":{"$ref":"#/components/schemas/SettingsLocale"},"timezone":{"type":"string","description":"Default timezone for date/time display (IANA timezone identifier)","example":"Europe/Tallinn","maxLength":100},"pageBrandName":{"type":"string","description":"Brand name displayed in page titles","example":"EmailEngine","nullable":true,"maxLength":1024},"openAiPreProcessingFn":{"type":"string","description":"JavaScript function to filter emails before AI processing (return true to process, false to skip)","example":"return true; // pass every email","maxLength":524288},"imapClientName":{"type":"string","description":"Client name advertised via IMAP ID extension","example":"EmailEngine","maxLength":1024},"imapClientVersion":{"type":"string","description":"Client version advertised via IMAP ID extension","example":"1.3.45","maxLength":1024},"imapClientVendor":{"type":"string","description":"Vendor name advertised via IMAP ID extension","example":"Postal Systems","maxLength":1024},"imapClientSupportUrl":{"type":"string","description":"Support URL advertised via IMAP ID extension","example":"https://github.com/postalsys/emailengine/issues","x-format":{"uri":{"scheme":["http","https","mailto"],"allowRelative":false}}},"exportMaxConcurrent":{"type":"integer","description":"Maximum concurrent exports per account","example":2,"minimum":1,"maximum":100},"exportMaxGlobalConcurrent":{"type":"integer","description":"Maximum concurrent exports system-wide across all accounts","example":8,"minimum":1,"maximum":100},"gmailExportBatchSize":{"type":"integer","description":"Number of parallel message fetch requests for Gmail export operations (default: 10, max: 50)","example":10,"minimum":1,"maximum":50},"outlookExportBatchSize":{"type":"integer","description":"Number of messages per batch request for Outlook export operations (default: 20, max: 20 - MS Graph API limit)","example":20,"minimum":1,"maximum":20},"exportMaxMessages":{"type":"integer","description":"Maximum number of messages per export (default: 500000)","example":500000,"minimum":1,"maximum":10000000},"exportMaxSize":{"type":"integer","description":"Maximum export file size in bytes (default: 10GB)","example":10737418240,"minimum":1}}},"UpdatedSettings":{"type":"array","description":"List of updated setting keys","items":{"type":"string","example":"notifyHeaders"}},"SettingsUpdatedResponse":{"type":"object","properties":{"updated":{"$ref":"#/components/schemas/UpdatedSettings"}}},"QueueIdResponse":{"type":"string","description":"Queue ID","example":"notify","x-meta":{"enumDescriptions":{"notify":"Webhook delivery queue","submit":"Outbound email delivery queue","documents":"Document Store indexing queue (deprecated feature)"}},"enum":["notify","submit","documents"],"x-convert":{"trim":true}},"QueueJobs":{"type":"object","properties":{"active":{"type":"integer","description":"Jobs that are currently being processed","example":123},"delayed":{"type":"integer","description":"Jobs that are processed in the future","example":123},"paused":{"type":"integer","description":"Always 0. BullMQ 6 no longer parks jobs in a separate paused list, so jobs held by a paused queue are counted as waiting. Kept so existing clients still see the key","example":0},"waiting":{"type":"integer","description":"Jobs that should be processed, but are waiting until there are any free handlers","example":123}}},"SettingsQueueResponse":{"type":"object","properties":{"queue":{"$ref":"#/components/schemas/QueueIdResponse"},"jobs":{"$ref":"#/components/schemas/QueueJobs"},"paused":{"type":"boolean","description":"Is the queue paused or not","example":false}},"required":["queue"]},"SettingsPutQueuePayload":{"type":"object","properties":{"paused":{"type":"boolean","description":"Set queue state to paused","example":false}}},"QueueIdPutResponse":{"type":"string","description":"Queue ID","example":"notify","enum":["notify","submit","documents"],"x-convert":{"trim":true}},"SettingsPutQueueResponse":{"type":"object","properties":{"queue":{"$ref":"#/components/schemas/QueueIdPutResponse"},"paused":{"type":"boolean","description":"Is the queue paused or not","example":false}},"required":["queue"]},"details":{"type":"array","description":"Warning details","items":{"type":"string","example":"maxmemory-policy is allkeys-lru"}},"RedisWarningEntry":{"type":"object","properties":{"key":{"type":"string","description":"Warning identifier","example":"maxmemory-policy"},"color":{"type":"string","description":"Severity indicator","example":"warning"},"title":{"type":"string","description":"Warning title","example":"Unsafe Redis eviction policy"},"details":{"$ref":"#/components/schemas/details"}}},"RedisWarnings":{"type":"array","description":"Warnings about the Redis configuration","items":{"$ref":"#/components/schemas/RedisWarningEntry"}},"BuildInfo":{"type":"object","description":"Build information for the running EmailEngine instance"},"QueueStats":{"type":"object","description":"Job counters for the notify, submit, and documents queues"},"ConnectionsStats":{"type":"object","description":"Counts of accounts in different connection states","properties":{"init":{"type":"integer","description":"Accounts not yet initialized","example":2},"connected":{"type":"integer","description":"Successfully connected accounts","example":8},"connecting":{"type":"integer","description":"Connection is being established","example":7},"syncing":{"type":"integer","description":"Accounts that are currently syncing","example":1},"authenticationError":{"type":"integer","description":"Authentication failed","example":3},"connectError":{"type":"integer","description":"Connection failed due to technical error","example":5},"unset":{"type":"integer","description":"Accounts without valid IMAP settings","example":0},"disconnected":{"type":"integer","description":"IMAP connection was closed","example":1},"paused":{"type":"integer","description":"Accounts that are paused","example":0},"unassigned":{"type":"integer","description":"Accounts not assigned to any worker","example":0}}},"CounterStats":{"type":"object"},"StatsResponse":{"type":"object","properties":{"version":{"type":"string","description":"EmailEngine version number","example":"2.79.0"},"license":{"type":"string","description":"EmailEngine license","example":"LICENSE_EMAILENGINE"},"accounts":{"type":"integer","description":"Number of registered accounts","example":26},"node":{"type":"string","description":"Node.js Version","example":"16.10.0"},"redis":{"type":"string","description":"Redis version. Can include the server software in parentheses, or an error message if the version lookup failed","example":"6.2.4"},"redisSoftware":{"type":"string","description":"Redis-compatible server software name","example":"redis"},"redisCluster":{"type":"boolean","description":"Whether Redis is running in cluster mode","example":false},"redisWarnings":{"$ref":"#/components/schemas/RedisWarnings"},"redisPing":{"type":"number","description":"Redis latency in milliseconds","example":1.2},"imapflow":{"type":"string","description":"ImapFlow version","example":"1.0.188"},"bullmq":{"type":"string","description":"BullMQ version","example":"5.0.0"},"arch":{"type":"string","description":"CPU architecture of the host","example":"arm64"},"build":{"$ref":"#/components/schemas/BuildInfo"},"queues":{"$ref":"#/components/schemas/QueueStats"},"connections":{"$ref":"#/components/schemas/ConnectionsStats"},"counters":{"$ref":"#/components/schemas/CounterStats"}}},"TemplateListFormat":{"type":"string","description":"Markup language for HTML (\"html\" or \"markdown\")","default":"html","enum":["html","markdown"]},"AccountTemplate":{"type":"object","properties":{"id":{"type":"string","description":"Template ID","example":"AAABgS-UcAYAAAABAA","maxLength":256},"name":{"type":"string","description":"Name of the template","example":"Transaction receipt","maxLength":256},"description":{"type":"string","description":"Optional description of the template","example":"Something about the template","maxLength":1024},"format":{"$ref":"#/components/schemas/TemplateListFormat"},"created":{"type":"string","format":"date-time","description":"The time this template was created","example":"2021-02-17T13:43:18.860Z"},"updated":{"type":"string","format":"date-time","description":"The time this template was last updated","example":"2021-02-17T13:43:18.860Z"}},"required":["id","name"]},"AccountTemplatesList":{"type":"array","items":{"$ref":"#/components/schemas/AccountTemplate"}},"AccountTemplatesResponse":{"type":"object","properties":{"account":{"type":"string","description":"Account ID. Null for public templates","example":"user123","nullable":true,"maxLength":256,"x-convert":{"trim":true}},"total":{"type":"integer","description":"How many matching entries","example":120},"page":{"type":"integer","description":"Current page (0-based index)","example":0},"pages":{"type":"integer","description":"Total page count","example":24},"templates":{"$ref":"#/components/schemas/AccountTemplatesList"}},"required":["account"]},"FlushTemplatesResponse":{"type":"object","properties":{"flushed":{"type":"boolean","description":"Were the templates flushed","default":true},"account":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}}},"required":["account"]},"TemplateFormat":{"type":"string","description":"Markup language for HTML (\"html\" or \"markdown\")","default":"html","enum":["html","markdown"]},"CreateTemplateContent":{"type":"object","properties":{"subject":{"type":"string","description":"Email subject line","example":"What a wonderful message","maxLength":10240,"x-convert":{"trim":true}},"text":{"type":"string","description":"Plain text message content","example":"Hello from myself!","maxLength":52428800,"x-convert":{"trim":true}},"html":{"type":"string","description":"HTML message content","example":"<p>Hello from myself!</p>","maxLength":52428800,"x-convert":{"trim":true}},"previewText":{"type":"string","description":"Preview text shown in email clients after the subject line","example":"Welcome to our newsletter!","maxLength":1024}}},"CreateTemplate":{"type":"object","properties":{"account":{"type":"string","description":"Account ID. Use `null` for public templates.","example":"example","nullable":true,"maxLength":256,"x-convert":{"trim":true}},"name":{"type":"string","description":"Name of the template","example":"Transaction receipt","maxLength":256},"description":{"type":"string","description":"Optional description of the template","example":"Something about the template","maxLength":1024},"format":{"$ref":"#/components/schemas/TemplateFormat"},"content":{"$ref":"#/components/schemas/CreateTemplateContent"}},"required":["account","name","content"]},"CreateTemplateResponse":{"type":"object","properties":{"created":{"type":"boolean","description":"Was the template created or not"},"account":{"type":"string","description":"Account ID. Null for public templates","example":"user123","nullable":true,"maxLength":256,"x-convert":{"trim":true}},"id":{"type":"string","description":"Template ID","example":"example","maxLength":256}},"required":["account","id"]},"TemplateResponseFormat":{"type":"string","description":"Markup language for HTML (\"html\" or \"markdown\")","default":"html","enum":["html","markdown"]},"RequestTemplateContent":{"type":"object","properties":{"subject":{"type":"string","description":"Email subject line","example":"What a wonderful message","maxLength":10240,"x-convert":{"trim":true}},"text":{"type":"string","description":"Plain text message content","example":"Hello from myself!","maxLength":52428800,"x-convert":{"trim":true}},"html":{"type":"string","description":"HTML message content","example":"<p>Hello from myself!</p>","maxLength":52428800,"x-convert":{"trim":true}},"previewText":{"type":"string","description":"Preview text shown in email clients after the subject line","example":"Welcome to our newsletter!","maxLength":1024}}},"AccountTemplateResponse":{"type":"object","properties":{"account":{"type":"string","description":"Account ID. Null for public templates","example":"user123","nullable":true,"maxLength":256,"x-convert":{"trim":true}},"id":{"type":"string","description":"Template ID","example":"AAABgS-UcAYAAAABAA","maxLength":256},"name":{"type":"string","description":"Name of the template","example":"Transaction receipt","maxLength":256},"description":{"type":"string","description":"Optional description of the template","example":"Something about the template","maxLength":1024},"format":{"$ref":"#/components/schemas/TemplateResponseFormat"},"created":{"type":"string","format":"date-time","description":"The time this template was created","example":"2021-02-17T13:43:18.860Z"},"updated":{"type":"string","format":"date-time","description":"The time this template was last updated","example":"2021-02-17T13:43:18.860Z"},"content":{"$ref":"#/components/schemas/RequestTemplateContent"}},"required":["account","id","name"]},"TemplateUpdateFormat":{"type":"string","description":"Markup language for HTML (\"html\" or \"markdown\")","default":"html","enum":["html","markdown"]},"UpdateTemplateContent":{"type":"object","properties":{"subject":{"type":"string","description":"Email subject line","example":"What a wonderful message","maxLength":10240,"x-convert":{"trim":true}},"text":{"type":"string","description":"Plain text message content","example":"Hello from myself!","maxLength":52428800,"x-convert":{"trim":true}},"html":{"type":"string","description":"HTML message content","example":"<p>Hello from myself!</p>","maxLength":52428800,"x-convert":{"trim":true}},"previewText":{"type":"string","description":"Preview text shown in email clients after the subject line","example":"Welcome to our newsletter!","maxLength":1024}}},"UpdateTemplate":{"type":"object","properties":{"name":{"type":"string","description":"Name of the template","example":"Transaction receipt","maxLength":256},"description":{"type":"string","description":"Optional description of the template","example":"Something about the template","maxLength":1024},"format":{"$ref":"#/components/schemas/TemplateUpdateFormat"},"content":{"$ref":"#/components/schemas/UpdateTemplateContent"}}},"UpdateTemplateResponse":{"type":"object","properties":{"updated":{"type":"boolean","description":"Was the template updated or not"},"account":{"type":"string","description":"Account ID. Null for public templates","example":"user123","nullable":true,"maxLength":256,"x-convert":{"trim":true}},"id":{"type":"string","description":"Template ID","example":"example","maxLength":256}},"required":["account","id"]},"DeleteTemplateResponse":{"type":"object","properties":{"deleted":{"type":"boolean","description":"Was the template deleted","default":true},"account":{"type":"string","description":"Account ID. Null for public templates","example":"user123","nullable":true,"maxLength":256,"x-convert":{"trim":true}},"id":{"type":"string","description":"Template ID","example":"AAABgS-UcAYAAAABAA","maxLength":256}},"required":["account","id"]},"TokenScopes":{"type":"array","description":"Scopes this token is valid for","items":{"type":"string","example":"api"}},"ReferrerAllowlist":{"type":"array","description":"HTTP referrer patterns that are allowed to use this token (wildcards supported)","example":["*web.domain.org/*","*.domain.org/*","https://domain.org/*"],"default":null,"nullable":true,"x-constraint":{"single":true},"items":{"type":"string"}},"AddressAllowlist":{"type":"array","description":"IP addresses or CIDR ranges allowed to use this token","example":["1.2.3.4","5.6.7.8","127.0.0.0/8"],"default":null,"nullable":true,"x-constraint":{"single":true},"items":{"type":"string","x-format":{"ip":{"cidr":"optional","version":["ipv4","ipv6"]}}}},"AddressRateLimit":{"type":"object","description":"Rate limiting configuration for this token","example":{"maxRequests":20,"timeWindow":2},"default":null,"nullable":true,"properties":{"maxRequests":{"type":"integer","description":"Maximum requests allowed in the time window","example":20,"minimum":1},"timeWindow":{"type":"integer","description":"Time window duration in seconds","example":2,"minimum":1}}},"TokenRestrictions":{"type":"object","description":"Security restrictions for API token usage","nullable":true,"properties":{"referrers":{"$ref":"#/components/schemas/ReferrerAllowlist"},"addresses":{"$ref":"#/components/schemas/AddressAllowlist"},"rateLimit":{"$ref":"#/components/schemas/AddressRateLimit"}}},"TokenAction":{"type":"string","x-meta":{"enumDescriptions":{"read":"Read data without changing anything","write":"Create or modify data","send":"Hand a message to a mail server, so it reaches real recipients","destructive":"Call the endpoints that remove data. Deleting a message is a move to Trash, which a write grant can perform directly, so withholding this narrows the endpoints rather than the outcome for mail"}},"enum":["read","write","send","destructive"]},"TokenActions":{"type":"array","description":"Which kinds of operation this token may perform. Omit to allow all of them","example":["read","write"],"minItems":1,"x-constraint":{"single":true},"items":{"$ref":"#/components/schemas/TokenAction"}},"TokenGroup":{"type":"string","x-meta":{"enumDescriptions":{"account":"Manage email accounts and their connection state","mailbox":"Create, rename, delete and list mailbox folders","message":"Read, modify, move and delete messages, including bulk actions and search","submit":"Send email, including scheduled sends and the delivery test. A send may reference a stored message to forward it, so this also reads the message it names","outbox":"Inspect and cancel queued outbound messages","export":"Bulk export an account. One call archives every folder, so this is separate from message access","template":"Manage stored email templates","blocklist":"Manage suppression lists","webhook":"Read webhook route definitions","gateway":"Manage SMTP gateways, which hold outbound SMTP credentials","events":"Subscribe to the instance-wide change stream, which covers every account","diagnostics":"Read statistics and service status","logs":"Read the per-account connection log. Entries are the raw protocol trace, so they include folder names and message subjects"}},"enum":["account","mailbox","message","submit","outbox","export","template","blocklist","webhook","gateway","events","diagnostics","logs"]},"TokenGroups":{"type":"array","description":"Which parts of the API this token may reach. Omit to allow all of them","example":["message","mailbox"],"minItems":1,"x-constraint":{"single":true},"items":{"$ref":"#/components/schemas/TokenGroup"}},"TokenPermissions":{"type":"object","description":"Restricts a token below its scope. Each axis is an allowlist that only narrows, and both apply together, so an operation must match the actions AND the groups. Endpoints that hand out credentials or change instance configuration can never be reached by a token that sets this field, whatever it lists","example":{"actions":["read"],"groups":["message","mailbox"]},"nullable":true,"minProperties":1,"properties":{"actions":{"$ref":"#/components/schemas/TokenActions"},"groups":{"$ref":"#/components/schemas/TokenGroups"}}},"TokenAccess":{"type":"object","description":"Token usage information","properties":{"time":{"type":"string","format":"date-time","description":"Last time this token was used. Null if the token has never been used","example":"2021-02-17T13:43:18.860Z","nullable":true},"ip":{"type":"string","description":"IP address of the last request that used this token. Null if the address was not available","example":"127.0.0.1","nullable":true,"x-format":{"ip":{"cidr":"forbidden","version":["ipv4","ipv6"]}},"x-convert":{"trim":true}}}},"TokensItem":{"type":"object","properties":{"account":{"type":"string","description":"Account this token is bound to, or null for an instance-wide token","example":"user123","nullable":true,"maxLength":256,"x-convert":{"trim":true}},"description":{"type":"string","description":"Token description","example":"Token description","maxLength":1024,"x-convert":{"trim":true}},"metadata":{"type":"string","description":"Related metadata in JSON format","example":"{\"example\": \"value\"}","maxLength":1048576},"ip":{"type":"string","description":"IP address of the requester","example":"127.0.0.1","x-format":{"ip":{"cidr":"forbidden","version":["ipv4","ipv6"]}},"x-convert":{"trim":true}},"remoteAddress":{"type":"string","description":"IP address of the client that created the token","example":"127.0.0.1","x-format":{"ip":{"cidr":"forbidden","version":["ipv4","ipv6"]}},"x-convert":{"trim":true}},"scopes":{"$ref":"#/components/schemas/TokenScopes"},"restrictions":{"$ref":"#/components/schemas/TokenRestrictions"},"permissions":{"$ref":"#/components/schemas/TokenPermissions"},"created":{"type":"string","format":"date-time","description":"The time this token was created","example":"2021-02-17T13:43:18.860Z"},"expires":{"type":"string","format":"date-time","description":"The time this token stops working. Absent for tokens that never expire","example":"2021-02-17T14:43:18.860Z"},"access":{"$ref":"#/components/schemas/TokenAccess"},"id":{"type":"string","description":"Token identifier (SHA-256 hash of the token)","example":"1bc12baf7f0d5e51fe0a4e0eda06e1be5b8d6cc2c66b95dc0fbe4d2e9f5d5e1a","x-constraint":{"length":64},"x-format":{"hex":{"byteAligned":false,"prefix":false}}}}},"TokensEntries":{"type":"array","items":{"$ref":"#/components/schemas/TokensItem"}},"TokensResponse":{"type":"object","properties":{"account":{"type":"string","description":"The account filter that was applied, or null when every token was listed","example":"user123","nullable":true,"maxLength":256,"x-convert":{"trim":true}},"total":{"type":"integer","description":"How many tokens match","example":12},"page":{"type":"integer","description":"Current page (zero indexed)","example":0},"pages":{"type":"integer","description":"Total page count","example":1},"tokens":{"$ref":"#/components/schemas/TokensEntries"}}},"TokenScope":{"type":"string","x-meta":{"enumDescriptions":{"api":"Call the REST API","smtp":"Authenticate against the built-in SMTP submission server","imap-proxy":"Authenticate against the built-in IMAP proxy"}},"enum":["api","smtp","imap-proxy"]},"Scopes":{"type":"array","description":"Token permission scopes: \"api\" for REST API access, \"smtp\" for SMTP submission, \"imap-proxy\" for IMAP proxy authentication","default":["api"],"x-constraint":{"single":true},"items":{"$ref":"#/components/schemas/TokenScope"}},"CreateToken":{"type":"object","properties":{"account":{"type":"string","description":"Bind the token to one account. Omit for an instance-wide token, which then has to set `permissions`","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":{"type":"string","description":"Token description","example":"Token description","maxLength":1024,"x-convert":{"trim":true}},"scopes":{"$ref":"#/components/schemas/Scopes"},"metadata":{"type":"string","description":"Related metadata in JSON format","example":"{\"example\": \"value\"}","maxLength":1048576},"restrictions":{"$ref":"#/components/schemas/TokenRestrictions"},"permissions":{"$ref":"#/components/schemas/TokenPermissions"},"expires":{"type":"string","format":"date-time","description":"Optional time when this token stops working. Omit for a token that never expires","example":"2021-02-17T14:43:18.860Z"},"ip":{"type":"string","description":"IP address of the requester","example":"127.0.0.1","x-format":{"ip":{"cidr":"forbidden","version":["ipv4","ipv6"]}},"x-convert":{"trim":true}}},"required":["description","scopes"]},"CreateTokenResponse":{"type":"object","properties":{"token":{"type":"string","description":"The access token. This is the only time it is returned - store it now","example":"123456","x-constraint":{"length":64},"x-format":{"hex":{"byteAligned":false,"prefix":false}}},"id":{"type":"string","description":"Identifier for this token, as reported by the token listings","example":"1bc12baf7f0d5e51fe0a4e0eda06e1be5b8d6cc2c66b95dc0fbe4d2e9f5d5e1a","x-constraint":{"length":64},"x-format":{"hex":{"byteAligned":false,"prefix":false}}}},"required":["token","id"]},"TokenResponse":{"type":"object","properties":{"account":{"type":"string","description":"Account this token is bound to, or null for an instance-wide token","example":"user123","nullable":true,"maxLength":256,"x-convert":{"trim":true}},"description":{"type":"string","description":"Token description","example":"Token description","maxLength":1024,"x-convert":{"trim":true}},"metadata":{"type":"string","description":"Related metadata in JSON format","example":"{\"example\": \"value\"}","maxLength":1048576},"ip":{"type":"string","description":"IP address of the requester","example":"127.0.0.1","x-format":{"ip":{"cidr":"forbidden","version":["ipv4","ipv6"]}},"x-convert":{"trim":true}},"remoteAddress":{"type":"string","description":"IP address of the client that created the token","example":"127.0.0.1","x-format":{"ip":{"cidr":"forbidden","version":["ipv4","ipv6"]}},"x-convert":{"trim":true}},"scopes":{"$ref":"#/components/schemas/TokenScopes"},"restrictions":{"$ref":"#/components/schemas/TokenRestrictions"},"permissions":{"$ref":"#/components/schemas/TokenPermissions"},"created":{"type":"string","format":"date-time","description":"The time this token was created","example":"2021-02-17T13:43:18.860Z"},"expires":{"type":"string","format":"date-time","description":"The time this token stops working. Absent for tokens that never expire","example":"2021-02-17T14:43:18.860Z"},"access":{"$ref":"#/components/schemas/TokenAccess"},"id":{"type":"string","description":"Token identifier (SHA-256 hash of the token)","example":"1bc12baf7f0d5e51fe0a4e0eda06e1be5b8d6cc2c66b95dc0fbe4d2e9f5d5e1a","x-constraint":{"length":64},"x-format":{"hex":{"byteAligned":false,"prefix":false}}}}},"DeleteTokenRequestResponse":{"type":"object","properties":{"deleted":{"type":"boolean","description":"Was the token deleted","default":true}}},"TokenLogStatus":{"type":"string","description":"Whether the request was served","example":"allowed","enum":["allowed","denied"]},"TokenLogEntry":{"type":"object","properties":{"time":{"type":"string","format":"date-time","description":"When the request was made","example":"2021-02-17T13:43:18.860Z"},"ip":{"type":"string","description":"Address the request came from","example":"127.0.0.1","nullable":true,"x-format":{"ip":{"cidr":"forbidden","version":["ipv4","ipv6"]}},"x-convert":{"trim":true}},"method":{"type":"string","description":"HTTP method, or the surface name for SMTP and the IMAP proxy","example":"get","nullable":true},"path":{"type":"string","description":"Route that was called","example":"/v1/account/{account}/messages","nullable":true},"action":{"type":"string","description":"Permission action the operation required","example":"read","nullable":true},"group":{"type":"string","description":"Permission group the operation belongs to","example":"message","nullable":true},"account":{"type":"string","description":"Account the request addressed","example":"user123","nullable":true,"maxLength":256,"x-convert":{"trim":true}},"status":{"$ref":"#/components/schemas/TokenLogStatus"},"reason":{"type":"string","description":"Why it was refused. Null when it was allowed","example":"group","nullable":true}}},"TokenLogEntries":{"type":"array","items":{"$ref":"#/components/schemas/TokenLogEntry"}},"TokenLogResponse":{"type":"object","properties":{"token":{"type":"string","description":"Token identifier (SHA-256 hash of the token)","example":"1bc12baf7f0d5e51fe0a4e0eda06e1be5b8d6cc2c66b95dc0fbe4d2e9f5d5e1a","x-constraint":{"length":64},"x-format":{"hex":{"byteAligned":false,"prefix":false}}},"total":{"type":"integer","description":"How many entries are stored for this token","example":120},"page":{"type":"integer","description":"Current page (zero indexed)","example":0},"pages":{"type":"integer","description":"Total page count","example":6},"entries":{"$ref":"#/components/schemas/TokenLogEntries"}}},"VerifyAccount":{"type":"object","properties":{"mailboxes":{"type":"boolean","description":"Include mailbox listing in response","example":false,"default":false},"imap":{"$ref":"#/components/schemas/ImapConfiguration"},"smtp":{"$ref":"#/components/schemas/SmtpConfiguration"},"proxy":{"type":"string","description":"Proxy server URL for outbound connections","example":"socks5://proxy.example.com:1080","x-format":{"uri":{"scheme":["http","https","socks","socks4","socks4a","socks5"],"allowRelative":false}}},"smtpEhloName":{"type":"string","description":"Hostname to use in SMTP EHLO/HELO commands (defaults to system hostname)","example":"relay.example.com","nullable":true,"x-format":{"hostname":true}}}},"VerifyImapResult":{"type":"object","properties":{"success":{"type":"boolean","description":"Was IMAP account verified","example":true},"error":{"type":"string","description":"Error messages for IMAP verification. Only present if success=false","example":"Something went wrong"},"code":{"type":"string","description":"Error code. Only present if success=false","example":"ERR_SSL_WRONG_VERSION_NUMBER"},"statusCode":{"type":"integer","description":"HTTP-style status code for the error. Only present if success=false","example":500},"responseText":{"type":"string","description":"Server response for the failed verification. Only present if success=false","example":"NO [AUTHENTICATIONFAILED] Invalid credentials"}}},"VerifySmtpResult":{"type":"object","properties":{"success":{"type":"boolean","description":"Was SMTP account verified","example":true},"error":{"type":"string","description":"Error messages for SMTP verification. Only present if success=false","example":"Something went wrong"},"code":{"type":"string","description":"Error code. Only present if success=false","example":"ERR_SSL_WRONG_VERSION_NUMBER"},"statusCode":{"type":"integer","description":"HTTP-style status code for the error. Only present if success=false","example":500},"responseText":{"type":"string","description":"Server response for the failed verification. Only present if success=false","example":"535 Authentication failed"}}},"MailboxShortResponseItem":{"type":"object","properties":{"path":{"type":"string","description":"Full path to the mailbox","example":"Kalender/S&APw-nnip&AOQ-evad"},"delimiter":{"type":"string","description":"Hierarchy delimiter character used in paths (can be null when the server uses a NIL delimiter)","example":"/","nullable":true},"parentPath":{"type":"string","description":"Path to the parent mailbox. Not set (or empty) for root level mailboxes","example":"Kalender"},"name":{"type":"string","description":"Display name of the mailbox","example":"Sünnipäevad"},"listed":{"type":"boolean","description":"Whether this mailbox appears in LIST command results","example":true},"subscribed":{"type":"boolean","description":"Whether the user is subscribed to this mailbox","example":true},"specialUse":{"$ref":"#/components/schemas/MailboxSpecialUse"},"specialUseSource":{"$ref":"#/components/schemas/MailboxSpecialUseSource"},"noInferiors":{"type":"boolean","description":"Whether this mailbox can contain child mailboxes","example":false}},"required":["path","name"]},"ShortMailboxes":{"type":"array","items":{"$ref":"#/components/schemas/MailboxShortResponseItem"}},"VerifyAccountResponse":{"type":"object","properties":{"imap":{"$ref":"#/components/schemas/VerifyImapResult"},"smtp":{"$ref":"#/components/schemas/VerifySmtpResult"},"mailboxes":{"$ref":"#/components/schemas/ShortMailboxes"}}},"WebhookRouteErrorFlag":{"type":"object","description":"Information about the last webhook delivery error. Null if no errors have been registered","nullable":true,"properties":{"message":{"type":"string","description":"Error message from the last failed delivery","example":"Request failed with status 500"}}},"WebhookRouteCustomHeaders":{"type":"array","description":"Custom HTTP headers added to webhook requests for this route","items":{"$ref":"#/components/schemas/WebhooksCustomHeader"}},"WebhookRoutesListEntry":{"type":"object","properties":{"id":{"type":"string","description":"Webhook ID","example":"AAABgS-UcAYAAAABAA","maxLength":256},"name":{"type":"string","description":"Name of the route","example":"Send to Slack","maxLength":256},"description":{"type":"string","description":"Optional description of the webhook route","example":"Something about the route","maxLength":1024},"created":{"type":"string","format":"date-time","description":"The time this route was created","example":"2021-02-17T13:43:18.860Z"},"updated":{"type":"string","format":"date-time","description":"The time this route was last updated","example":"2021-02-17T13:43:18.860Z"},"enabled":{"type":"boolean","description":"Is the route enabled","example":true},"targetUrl":{"type":"string","description":"Target URL that will receive webhook notifications via POST requests","example":"https://api.example.com/email/webhooks","x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"tcount":{"type":"integer","description":"How many times this route has been applied","example":123},"webhookErrorFlag":{"$ref":"#/components/schemas/WebhookRouteErrorFlag"},"customHeaders":{"$ref":"#/components/schemas/WebhookRouteCustomHeaders"}},"required":["id","name"]},"WebhookRoutesList":{"type":"array","items":{"$ref":"#/components/schemas/WebhookRoutesListEntry"}},"WebhookRoutesListResponse":{"type":"object","properties":{"total":{"type":"integer","description":"How many matching entries","example":120},"page":{"type":"integer","description":"Current page (0-based index)","example":0},"pages":{"type":"integer","description":"Total page count","example":24},"webhooks":{"$ref":"#/components/schemas/WebhookRoutesList"}}},"WebhookRouteContent":{"type":"object","properties":{"fn":{"type":"string","description":"Filter function. Null if not set","example":"return true;","nullable":true},"map":{"type":"string","description":"Mapping function. Null if not set","example":"payload.ts = Date.now(); return payload;","nullable":true}}},"WebhookRouteResponse":{"type":"object","properties":{"id":{"type":"string","description":"Webhook ID","example":"AAABgS-UcAYAAAABAA","maxLength":256},"name":{"type":"string","description":"Name of the route","example":"Send to Slack","maxLength":256},"description":{"type":"string","description":"Optional description of the webhook route","example":"Something about the route","maxLength":1024},"created":{"type":"string","format":"date-time","description":"The time this route was created","example":"2021-02-17T13:43:18.860Z"},"updated":{"type":"string","format":"date-time","description":"The time this route was last updated","example":"2021-02-17T13:43:18.860Z"},"enabled":{"type":"boolean","description":"Is the route enabled","example":true},"targetUrl":{"type":"string","description":"Target URL that will receive webhook notifications via POST requests","example":"https://api.example.com/email/webhooks","x-format":{"uri":{"scheme":["http","https"],"allowRelative":false}}},"tcount":{"type":"integer","description":"How many times this route has been applied","example":123},"v":{"type":"integer","description":"Internal version counter, increased on every update","example":1},"webhookErrorFlag":{"$ref":"#/components/schemas/WebhookRouteErrorFlag"},"customHeaders":{"$ref":"#/components/schemas/WebhookRouteCustomHeaders"},"content":{"$ref":"#/components/schemas/WebhookRouteContent"}},"required":["id","name"]}}},"paths":{"/v1/account":{"post":{"summary":"Register new account","operationId":"postV1Account","description":"Registers new IMAP account to be synced<br/><br/>Credentials are not verified while handling this request. The account connects afterwards, and an authentication failure surfaces as an authenticationError state rather than an error here. Use the account verification endpoint to test credentials up front.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"}],"tags":["Account"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAccount"}}}},"responses":{"200":{"description":"Returns the registered account, including the generated account ID when one was not supplied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAccountResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-behavior":["Credentials are not verified while handling this request. The account connects afterwards, and an authentication failure surfaces as an authenticationError state rather than an error here. Use the account verification endpoint to test credentials up front."],"x-ee-action":"write","x-ee-group":"admin"}},"/v1/account/{account}":{"get":{"summary":"Get account info","operationId":"getV1AccountAccount","description":"Returns stored information about the account. Credentials are masked: stored passwords, the credentials in any proxy or webhook URL, and the values of custom webhook headers all read back as \"******\". A masked value is not the stored one - leave the field out of an update rather than writing it back, otherwise the mask replaces the credential.<br/><br/>Quota reporting is not available for Gmail API or MS Graph accounts; the quota field is omitted for those.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"quota","in":"query","schema":{"type":"boolean","description":"If true, then include quota information in the response","default":false},"description":"If true, then include quota information in the response"}],"tags":["Account"],"responses":{"200":{"description":"Returns the account configuration, connection state and sync status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-behavior":["Quota reporting is not available for Gmail API or MS Graph accounts; the quota field is omitted for those."],"x-ee-action":"read","x-ee-group":"account"},"put":{"summary":"Update account info","operationId":"putV1AccountAccount","description":"Updates account information<br/><br/>Credentials are not verified while handling this request. The account connects afterwards, and an authentication failure surfaces as an authenticationError state rather than an error here. Use the account verification endpoint to test credentials up front.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true}],"tags":["Account"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAccount"}}}},"responses":{"200":{"description":"Returns the account ID. Changed credentials take effect on the next connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAccountResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-behavior":["Credentials are not verified while handling this request. The account connects afterwards, and an authentication failure surfaces as an authenticationError state rather than an error here. Use the account verification endpoint to test credentials up front."],"x-ee-action":"write","x-ee-group":"admin"},"delete":{"summary":"Remove account","operationId":"deleteV1AccountAccount","description":"Stop processing and clear the account's cache. Pass revoke=true to also attempt revocation of the upstream OAuth2 grant at the provider before the account is removed.<br/><br/>Removes the account, its credentials, its cached data and any messages still queued for delivery. Webhook events generated before the deletion are never delivered afterwards and are discarded once the queue reaches them. Records of deliveries that had already failed permanently are not removed here; they expire on the queue retention window, seven days by default.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"revoke","in":"query","schema":{"type":"boolean","description":"Revoke the upstream OAuth2 grant at the provider before deleting the account","x-meta":{"usage":"Set this when deleting an account should also cut EmailEngine off at the provider, for example because a user asked for their data to be disconnected rather than just removed here.\n\nIt currently works for individual Gmail OAuth2 grants. Gmail Workspace service-account integrations, Outlook and non-OAuth2 accounts ignore it. A failed revocation is logged and never blocks the deletion."},"default":false},"description":"Revoke the upstream OAuth2 grant at the provider before deleting the account"}],"tags":["Account"],"responses":{"200":{"description":"Returns a deletion marker. The account stops syncing immediately; stored data is removed in the background.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteAccountResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-impact":"destructive","x-ee-behavior":["Removes the account, its credentials, its cached data and any messages still queued for delivery. Webhook events generated before the deletion are never delivered afterwards and are discarded once the queue reaches them. Records of deliveries that had already failed permanently are not removed here; they expire on the queue retention window, seven days by default."],"x-ee-action":"destructive","x-ee-group":"account"}},"/v1/account/{account}/attachment/{attachment}":{"get":{"summary":"Download attachment","operationId":"getV1AccountAccountAttachmentAttachment","description":"Fetches attachment file as a binary stream","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"attachment","in":"path","schema":{"type":"string","description":"Attachment ID","example":"AAAAAQAACnAcde","maxLength":2048},"description":"Attachment ID","required":true}],"tags":["Message"],"responses":{"200":{"description":"Returns the attachment content as a binary stream.","content":{"application/octet-stream":{"schema":{"type":"string"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"503":{"description":"Service unavailable - the worker processing this account is not available, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"message"}},"/v1/account/{account}/export":{"post":{"summary":"Create export","operationId":"postV1AccountAccountExport","description":"Creates a new bulk message export job. The export runs asynchronously and notifies via webhook when complete.<br/><br/>Runs as a background job. Follow it either by polling the status endpoint or by waiting for the completion webhook.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true}],"tags":["Export (Beta)"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportRequest"}}}},"responses":{"200":{"description":"Returns the ID of the started export. Poll the status endpoint until it completes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateExportResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-behavior":["Runs as a background job. Follow it either by polling the status endpoint or by waiting for the completion webhook."],"x-ee-action":"write","x-ee-group":"export"}},"/v1/account/{account}/export/{exportId}":{"get":{"summary":"Get export status","operationId":"getV1AccountAccountExportExportid","description":"Returns the status and progress of an export job.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"exportId","in":"path","schema":{"type":"string","description":"Export job identifier","example":"exp_abc123def456abc123def456","pattern":"^exp_[a-f0-9]{24}$"},"description":"Export job identifier","required":true}],"tags":["Export (Beta)"],"responses":{"200":{"description":"Returns the export progress, and the download size once it has completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportStatus"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"export"},"delete":{"summary":"Delete export","operationId":"deleteV1AccountAccountExportExportid","description":"Cancels a pending export or deletes a completed export. Removes both Redis data and the export file.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"exportId","in":"path","schema":{"type":"string","description":"Export job identifier","example":"exp_abc123def456abc123def456","pattern":"^exp_[a-f0-9]{24}$"},"description":"Export job identifier","required":true}],"tags":["Export (Beta)"],"responses":{"200":{"description":"Returns a deletion marker. Any partially written export file is removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteExportResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-impact":"destructive","x-ee-action":"destructive","x-ee-group":"export"}},"/v1/account/{account}/export/{exportId}/download":{"get":{"summary":"Download export file","operationId":"getV1AccountAccountExportExportidDownload","description":"Downloads the completed export file as gzip-compressed NDJSON.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"exportId","in":"path","schema":{"type":"string","description":"Export job identifier","example":"exp_abc123def456abc123def456","pattern":"^exp_[a-f0-9]{24}$"},"description":"Export job identifier","required":true}],"tags":["Export (Beta)"],"responses":{"200":{"description":"Returns the export archive as gzip-compressed NDJSON.","content":{"application/gzip":{"schema":{"type":"string"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"503":{"description":"Service unavailable - the worker processing this account is not available, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"export"}},"/v1/account/{account}/exports":{"get":{"summary":"List exports","operationId":"getV1AccountAccountExports","description":"Lists all exports for an account with pagination.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"page","in":"query","schema":{"type":"integer","description":"Page number (zero indexed)","example":0,"default":0,"minimum":0,"maximum":1048576},"description":"Page number (zero indexed)"},{"name":"pageSize","in":"query","schema":{"type":"integer","description":"How many entries per page","example":20,"default":20,"minimum":1,"maximum":1000},"description":"How many entries per page"}],"tags":["Export (Beta)"],"responses":{"200":{"description":"Returns the exports for the account with their progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportList"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"export"}},"/v1/account/{account}/flush":{"put":{"summary":"Request account flush","operationId":"putV1AccountAccountFlush","description":"Deletes all email indexes from Redis and ElasticSearch and re-creates the index for that account. You can only run a single flush operation at a time, so you must wait until the previous flush has finished before initiating a new one.<br/><br/>The request only schedules the work and returns before it finishes. Watch the account state, or the accountInitialized and authenticationError webhooks, for the result.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true}],"tags":["Account"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestFlush"}}}},"responses":{"200":{"description":"Returns an acknowledgement. Cached message indexes are cleared and rebuilt in the background.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestFlushResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-impact":"destructive","x-ee-behavior":["The request only schedules the work and returns before it finishes. Watch the account state, or the accountInitialized and authenticationError webhooks, for the result."],"x-ee-action":"destructive","x-ee-group":"account"}},"/v1/account/{account}/mailbox":{"post":{"summary":"Create mailbox","operationId":"postV1AccountAccountMailbox","description":"Create new mailbox folder","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true}],"tags":["Mailbox"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMailbox"}}}},"responses":{"200":{"description":"Returns the created folder and its path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMailboxResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"503":{"description":"Service unavailable - the worker processing this account is not available, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponse"}}}}},"x-ee-action":"write","x-ee-group":"mailbox"},"put":{"summary":"Modify mailbox","operationId":"putV1AccountAccountMailbox","description":"Modify an existing mailbox folder (rename or change subscription status)","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true}],"tags":["Mailbox"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModifyMailbox"}}}},"responses":{"200":{"description":"Returns the renamed folder with its old and new paths.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModifyMailboxResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"503":{"description":"Service unavailable - the worker processing this account is not available, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponse"}}}}},"x-ee-action":"write","x-ee-group":"mailbox"},"delete":{"summary":"Delete mailbox","operationId":"deleteV1AccountAccountMailbox","description":"Delete existing mailbox folder","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"path","in":"query","schema":{"type":"string","description":"Mailbox folder path to delete","example":"My Outdated Mail"},"description":"Mailbox folder path to delete","required":true}],"tags":["Mailbox"],"responses":{"200":{"description":"Returns the deleted folder path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteMailboxResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"503":{"description":"Service unavailable - the worker processing this account is not available, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponse"}}}}},"x-ee-impact":"destructive","x-ee-action":"destructive","x-ee-group":"mailbox"}},"/v1/account/{account}/mailboxes":{"get":{"summary":"List mailboxes","operationId":"getV1AccountAccountMailboxes","description":"Lists all available mailboxes","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"counters","in":"query","schema":{"type":"boolean","description":"If true, then includes message counters in the response","default":false},"description":"If true, then includes message counters in the response"}],"tags":["Mailbox"],"responses":{"200":{"description":"Returns the account folder tree, including special-use designations and message counts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxesFilterResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"503":{"description":"Service unavailable - the worker processing this account is not available, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"mailbox"}},"/v1/account/{account}/message":{"post":{"summary":"Upload message","operationId":"postV1AccountAccountMessage","description":"Upload a message structure, compile it into an EML file and store it into selected mailbox.<br/><br/>For MS Graph accounts only drafts can be uploaded, and the draft flag cannot be changed afterwards.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true}],"tags":["Message"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageUpload"}}}},"responses":{"200":{"description":"Returns the uploaded message with the identifiers the provider assigned to it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageUploadResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"503":{"description":"Service unavailable - the worker processing this account is not available, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponse"}}}}},"x-ee-behavior":["For MS Graph accounts only drafts can be uploaded, and the draft flag cannot be changed afterwards."],"x-ee-action":"write","x-ee-group":"message"}},"/v1/account/{account}/message/{message}":{"get":{"summary":"Get message information","operationId":"getV1AccountAccountMessageMessage","description":"Returns details of a specific message. By default text content is not included, use textType value to force retrieving text","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"message","in":"path","schema":{"type":"string","description":"Message ID","example":"AAAAAQAACnA","maxLength":256},"description":"Message ID","required":true},{"name":"maxBytes","in":"query","schema":{"type":"integer","description":"Max length of text content","example":5248000,"minimum":0,"maximum":1073741824},"description":"Max length of text content"},{"name":"textType","in":"query","schema":{"type":"string","description":"Which text content to return, use * for all. By default text content is not returned.","example":"*","enum":["html","plain","*"],"x-convert":{"case":"lower"}},"description":"Which text content to return, use * for all. By default text content is not returned."},{"name":"webSafeHtml","in":"query","schema":{"type":"boolean","description":"Shorthand option to fetch and preprocess HTML and inline images","x-meta":{"usage":"Turn this on when you are rendering the message in your own UI and want EmailEngine to do the sanitising. It is a shorthand that overrides `textType`, `preProcessHtml` and `embedAttachedImages`.\n\nQuoted thread history is folded into one collapsed `<details class=\"ee-collapsed-thread\">` element so you can hide it behind a single control. Its `<summary>` is deliberately empty, so supply your own label."},"default":false},"description":"Shorthand option to fetch and preprocess HTML and inline images"},{"name":"embedAttachedImages","in":"query","schema":{"type":"boolean","description":"If true, then fetches attached images and embeds these in the HTML as data URIs","default":false},"description":"If true, then fetches attached images and embeds these in the HTML as data URIs"},{"name":"preProcessHtml","in":"query","schema":{"type":"boolean","description":"If true, then pre-processes HTML for compatibility","default":false},"description":"If true, then pre-processes HTML for compatibility"},{"name":"markAsSeen","in":"query","schema":{"type":"boolean","description":"If true, then marks unseen email as seen while returning the message","default":false},"description":"If true, then marks unseen email as seen while returning the message"}],"tags":["Message"],"responses":{"200":{"description":"Returns the message envelope and structure. Text content is only included when requested.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDetails"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"503":{"description":"Service unavailable - the worker processing this account is not available, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"message"},"put":{"summary":"Update message","operationId":"putV1AccountAccountMessageMessage","description":"Update message information. Mainly this means changing message flag values<br/><br/>For Gmail API accounts the entire label set cannot be replaced in one call. Add and remove labels individually instead of using the set operation.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"message","in":"path","schema":{"type":"string","description":"Message ID","example":"AAAAAQAACnA","maxLength":256},"description":"Message ID","required":true}],"tags":["Message"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageUpdate"}}}},"responses":{"200":{"description":"Returns which flag and label changes were applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageUpdateResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"503":{"description":"Service unavailable - the worker processing this account is not available, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponse"}}}}},"x-ee-behavior":["For Gmail API accounts the entire label set cannot be replaced in one call. Add and remove labels individually instead of using the set operation."],"x-ee-action":"write","x-ee-group":"message"},"delete":{"summary":"Delete message","operationId":"deleteV1AccountAccountMessageMessage","description":"Move message to Trash or delete it if already in Trash<br/><br/>For Gmail API accounts the message is always moved to Trash. The force option, which permanently deletes on IMAP accounts, has no effect.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"message","in":"path","schema":{"type":"string","description":"Message ID","example":"AAAAAQAACnA","maxLength":256},"description":"Message ID","required":true},{"name":"force","in":"query","schema":{"type":"boolean","description":"Delete message even if not in Trash. Not supported for Gmail API accounts.","default":false},"description":"Delete message even if not in Trash. Not supported for Gmail API accounts."}],"tags":["Message"],"responses":{"200":{"description":"Returns whether the message was moved to Trash or permanently deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDeleteResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"503":{"description":"Service unavailable - the worker processing this account is not available, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponse"}}}}},"x-ee-impact":"destructive","x-ee-behavior":["For Gmail API accounts the message is always moved to Trash. The force option, which permanently deletes on IMAP accounts, has no effect."],"x-ee-action":"destructive","x-ee-group":"message"}},"/v1/account/{account}/message/{message}/move":{"put":{"summary":"Move a message to a specified folder","operationId":"putV1AccountAccountMessageMessageMove","description":"Moves a message to a target folder","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"message","in":"path","schema":{"type":"string","description":"Message ID","example":"AAAAAQAACnA","maxLength":256},"description":"Message ID","required":true}],"tags":["Message"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageMove"}}}},"responses":{"200":{"description":"Returns the message identifiers in the target folder.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageMoveResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"503":{"description":"Service unavailable - the worker processing this account is not available, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponse"}}}}},"x-ee-action":"write","x-ee-group":"message"}},"/v1/account/{account}/message/{message}/source":{"get":{"summary":"Download raw message","operationId":"getV1AccountAccountMessageMessageSource","description":"Fetches raw message as a stream","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"message","in":"path","schema":{"type":"string","description":"Message ID","example":"AAAAAQAACnA","maxLength":256},"description":"Message ID","required":true}],"tags":["Message"],"responses":{"200":{"description":"Returns the raw RFC822 message source.","content":{"message/rfc822":{"schema":{"type":"string"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"503":{"description":"Service unavailable - the worker processing this account is not available, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"message"}},"/v1/account/{account}/message/{message}/submit":{"post":{"summary":"Submit a stored draft for delivery","operationId":"postV1AccountAccountMessageMessageSubmit","description":"Sends an existing draft message. The message must be a draft: stored in the Drafts folder or flagged as a draft (IMAP), carrying the DRAFT label (Gmail), or a draft message (MS Graph). Gmail and MS Graph accounts use the native draft-send call of the provider, which also files the message into the Sent Mail folder and removes the draft. For IMAP accounts the draft is downloaded, sent over SMTP, copied to the Sent Mail folder (unless disabled), and then removed from the Drafts folder.<br/><br/>Delivery is asynchronous. A 2xx means the message was queued, not that it was sent. Failed attempts are retried with exponential backoff up to the configured deliveryAttempts; follow the outcome through the Outbox endpoints or the messageSent, messageDeliveryError and messageFailed webhooks.<br/><br/>For SMTP accounts EmailEngine uploads the sent message to the Sent Mail folder after delivery. Gmail API and MS Graph accounts file sent messages themselves, so no upload is performed.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"idempotency-key","in":"header","schema":{"type":"string","description":"Unique key to prevent duplicate processing of the same request","example":"submit-12345","minLength":0,"maxLength":1024,"x-convert":{"trim":true}},"description":"Unique key to prevent duplicate processing of the same request"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"message","in":"path","schema":{"type":"string","description":"Message ID of the draft","example":"AAAAAQAACnA","maxLength":256},"description":"Message ID of the draft","required":true}],"tags":["Submit"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitDraft"}}}},"responses":{"200":{"description":"Returns the queue ID the stored draft was accepted under. Delivery happens asynchronously - a 200 means queued, not sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitDraftResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"503":{"description":"Service unavailable - the worker processing this account is not available, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponse"}}}}},"x-ee-impact":"sends","x-ee-behavior":["Delivery is asynchronous. A 2xx means the message was queued, not that it was sent. Failed attempts are retried with exponential backoff up to the configured deliveryAttempts; follow the outcome through the Outbox endpoints or the messageSent, messageDeliveryError and messageFailed webhooks.","For SMTP accounts EmailEngine uploads the sent message to the Sent Mail folder after delivery. Gmail API and MS Graph accounts file sent messages themselves, so no upload is performed."],"x-codeSamples":[{"lang":"bash","label":"Minimal","source":"curl -X POST \"$EMAILENGINE_URL/v1/account/example/message/AAAAAQAACnA/submit\" \\\n    -H \"Authorization: Bearer $EMAILENGINE_TOKEN\" \\\n    -H \"Content-Type: application/json\" \\\n    -d '{}'"}],"x-ee-action":"send","x-ee-group":"submit"}},"/v1/account/{account}/messages":{"get":{"summary":"List messages in a folder","operationId":"getV1AccountAccountMessages","description":"Lists messages in a mailbox folder","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"path","in":"query","schema":{"type":"string","description":"Mailbox folder path. Can use special use labels like \"\\Sent\". Special value \"\\All\" is available for Gmail IMAP, Gmail API, MS Graph API accounts.","example":"INBOX"},"description":"Mailbox folder path. Can use special use labels like \"\\Sent\". Special value \"\\All\" is available for Gmail IMAP, Gmail API, MS Graph API accounts.","required":true},{"name":"cursor","in":"query","schema":{"type":"string","description":"Paging cursor from `nextPageCursor` or `prevPageCursor` value","example":"imap_kcQIji3UobDDTxc","maxLength":1048576,"x-convert":{"trim":true}},"description":"Paging cursor from `nextPageCursor` or `prevPageCursor` value"},{"name":"page","in":"query","schema":{"type":"integer","description":"Page number (zero-indexed, so use 0 for the first page). Only supported for IMAP accounts","example":0,"x-meta":{"usage":"Prefer the paging cursor. This exists for IMAP accounts and for callers written before cursors, and it is ignored entirely when a cursor is also supplied."},"default":0,"minimum":0,"maximum":1048576},"description":"Page number (zero-indexed, so use 0 for the first page). Only supported for IMAP accounts"},{"name":"pageSize","in":"query","schema":{"type":"integer","description":"How many entries per page","example":20,"default":20,"minimum":1,"maximum":1000},"description":"How many entries per page"}],"tags":["Message"],"responses":{"200":{"description":"Returns a page of messages from the folder, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageList"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"503":{"description":"Service unavailable - the worker processing this account is not available, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"message"},"put":{"summary":"Update messages","operationId":"putV1AccountAccountMessages","description":"Update message information for matching emails<br/><br/>For Gmail API accounts the entire label set cannot be replaced in one call. Add and remove labels individually instead of using the set operation.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"path","in":"query","schema":{"type":"string","description":"Mailbox folder path. Can use special use labels like \"\\Sent\". Special value \"\\All\" is available for Gmail IMAP, Gmail API, MS Graph API accounts.","example":"INBOX"},"description":"Mailbox folder path. Can use special use labels like \"\\Sent\". Special value \"\\All\" is available for Gmail IMAP, Gmail API, MS Graph API accounts.","required":true}],"tags":["Multi Message Actions"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessagesUpdateRequest"}}}},"responses":{"200":{"description":"Returns which flag and label changes were applied to the matching messages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkMessageUpdateResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"503":{"description":"Service unavailable - the worker processing this account is not available, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponse"}}}}},"x-ee-behavior":["For Gmail API accounts the entire label set cannot be replaced in one call. Add and remove labels individually instead of using the set operation."],"x-ee-action":"write","x-ee-group":"message"}},"/v1/account/{account}/messages/delete":{"put":{"summary":"Delete messages","operationId":"putV1AccountAccountMessagesDelete","description":"Move messages to Trash or delete these if already in Trash<br/><br/>For Gmail API accounts the message is always moved to Trash. The force option, which permanently deletes on IMAP accounts, has no effect.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"path","in":"query","schema":{"type":"string","description":"Mailbox folder path. Can use special use labels like \"\\Sent\". Special value \"\\All\" is available for Gmail IMAP, Gmail API, MS Graph API accounts.","example":"INBOX"},"description":"Mailbox folder path. Can use special use labels like \"\\Sent\". Special value \"\\All\" is available for Gmail IMAP, Gmail API, MS Graph API accounts.","required":true},{"name":"force","in":"query","schema":{"type":"boolean","description":"Delete messages even if not in Trash. Not supported for Gmail API accounts (messages are always moved to Trash)","default":false},"description":"Delete messages even if not in Trash. Not supported for Gmail API accounts (messages are always moved to Trash)"}],"tags":["Multi Message Actions"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessagesDeleteRequest"}}}},"responses":{"200":{"description":"Returns the number of messages deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessagesDeleteResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"503":{"description":"Service unavailable - the worker processing this account is not available, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponse"}}}}},"x-ee-impact":"destructive","x-ee-behavior":["For Gmail API accounts the message is always moved to Trash. The force option, which permanently deletes on IMAP accounts, has no effect."],"x-ee-action":"destructive","x-ee-group":"message"}},"/v1/account/{account}/messages/move":{"put":{"summary":"Move messages","operationId":"putV1AccountAccountMessagesMove","description":"Move messages matching to a search query to another folder","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"path","in":"query","schema":{"type":"string","description":"Mailbox folder path. Can use special use labels like \"\\Sent\". Special value \"\\All\" is available for Gmail IMAP, Gmail API, MS Graph API accounts.","example":"INBOX"},"description":"Mailbox folder path. Can use special use labels like \"\\Sent\". Special value \"\\All\" is available for Gmail IMAP, Gmail API, MS Graph API accounts.","required":true}],"tags":["Multi Message Actions"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessagesMoveRequest"}}}},"responses":{"200":{"description":"Returns the number of messages moved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessagesMoveResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"503":{"description":"Service unavailable - the worker processing this account is not available, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponse"}}}}},"x-ee-action":"write","x-ee-group":"message"}},"/v1/account/{account}/oauth-token":{"get":{"summary":"Get OAuth2 access token","operationId":"getV1AccountAccountOauthtoken","description":"Get the active OAuth2 access token for an account. NB! This endpoint is disabled by default and needs activation on the Service configuration page.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true}],"tags":["Account"],"responses":{"200":{"description":"Returns a valid OAuth2 access token for the account, refreshing it first if it had expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountTokenResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"admin"}},"/v1/account/{account}/reconnect":{"put":{"summary":"Request reconnect","operationId":"putV1AccountAccountReconnect","description":"Requests connection to be reconnected<br/><br/>The request only schedules the work and returns before it finishes. Watch the account state, or the accountInitialized and authenticationError webhooks, for the result.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true}],"tags":["Account"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestReconnect"}}}},"responses":{"200":{"description":"Returns an acknowledgement. The reconnect is requested, not completed - watch the account state for the result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestReconnectResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-behavior":["The request only schedules the work and returns before it finishes. Watch the account state, or the accountInitialized and authenticationError webhooks, for the result."],"x-ee-action":"write","x-ee-group":"account"}},"/v1/account/{account}/search":{"post":{"summary":"Search for messages","operationId":"postV1AccountAccountSearch","description":"Filter messages from a mailbox folder by search options. Search is performed against a specific folder and not for the entire account.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"cursor","in":"query","schema":{"type":"string","description":"Paging cursor from `nextPageCursor` or `prevPageCursor` value","example":"imap_kcQIji3UobDDTxc","maxLength":1048576,"x-convert":{"trim":true}},"description":"Paging cursor from `nextPageCursor` or `prevPageCursor` value"},{"name":"page","in":"query","schema":{"type":"integer","description":"Page number (zero-indexed, so use 0 for the first page). Only supported for IMAP accounts","example":0,"x-meta":{"usage":"Prefer the paging cursor. This exists for IMAP accounts and for callers written before cursors, and it is ignored entirely when a cursor is also supplied."},"default":0,"minimum":0,"maximum":1048576},"description":"Page number (zero-indexed, so use 0 for the first page). Only supported for IMAP accounts"},{"name":"pageSize","in":"query","schema":{"type":"integer","description":"How many entries per page","example":20,"default":20,"minimum":1,"maximum":1000},"description":"How many entries per page"},{"name":"useOutlookSearch","in":"query","schema":{"type":"boolean","description":"MS Graph only. Use the $search parameter for search queries instead of $filter","x-meta":{"usage":"Turn this on for MS Graph accounts when you need to search fields that the default `$filter` mode cannot reach: `to`, `cc`, `bcc`, `larger`, `smaller`, `body`, `before`, `sentBefore`, `since` and `sentSince`.\n\nWhat you give up is worth checking first. `$search` returns at most 1,000 results, reports neither a total nor a page count, and orders by relevance rather than by date. The `labels` filter is unavailable in this mode, so leave it off when you need to filter by category."}},"description":"MS Graph only. Use the $search parameter for search queries instead of $filter"},{"name":"path","in":"query","schema":{"type":"string","description":"Mailbox folder path. Can use special use labels like \"\\Sent\". Special value \"\\All\" is available for Gmail IMAP, Gmail API, MS Graph API accounts.","example":"INBOX"},"description":"Mailbox folder path. Can use special use labels like \"\\Sent\". Special value \"\\All\" is available for Gmail IMAP, Gmail API, MS Graph API accounts."}],"tags":["Message"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageSearchPayload"}}}},"responses":{"200":{"description":"Returns a page of matching messages, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageList"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"422":{"description":"Unprocessable request - the request is well-formed, but the email server cannot perform the requested operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"503":{"description":"Service unavailable - the worker processing this account is not available, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponse"}}}}},"x-ee-impact":"readonly","x-ee-action":"read","x-ee-group":"message"}},"/v1/account/{account}/server-signatures":{"get":{"summary":"List Account Signatures","operationId":"getV1AccountAccountServersignatures","description":"Returns signatures associated with the account. Currently only Gmail is supported, and only \"new message\" signatures from the \"sendAs\" list are returned.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true}],"tags":["Account"],"responses":{"200":{"description":"Returns the signatures configured on the account, as reported by the provider.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountSignaturesResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"account"}},"/v1/account/{account}/submit":{"post":{"summary":"Submit message for delivery","operationId":"postV1AccountAccountSubmit","description":"Submit message for delivery. If reference message ID is provided then EmailEngine adds all headers and flags required for a reply/forward automatically.<br/><br/>Delivery is asynchronous. A 2xx means the message was queued, not that it was sent. Failed attempts are retried with exponential backoff up to the configured deliveryAttempts; follow the outcome through the Outbox endpoints or the messageSent, messageDeliveryError and messageFailed webhooks.<br/><br/>For SMTP accounts EmailEngine uploads the sent message to the Sent Mail folder after delivery. Gmail API and MS Graph accounts file sent messages themselves, so no upload is performed.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"idempotency-key","in":"header","schema":{"type":"string","description":"Unique key to prevent duplicate processing of the same request","example":"submit-12345","minLength":0,"maxLength":1024,"x-convert":{"trim":true}},"description":"Unique key to prevent duplicate processing of the same request"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"documentStore","in":"query","schema":{"type":"boolean","description":"If enabled then fetch email used as a reference template from the Document Store","default":false},"description":"If enabled then fetch email used as a reference template from the Document Store"},{"name":"useStructuredFormat","in":"query","schema":{"type":"boolean","description":"For MS Graph accounts: send as structured JSON instead of raw MIME","x-meta":{"usage":"Turn this on for MS Graph accounts sending from a shared mailbox, because it is the only mode that respects the `from` address.\n\nThe cost is fidelity: structured JSON breaks calendar invites and other special MIME types. The default, raw MIME, preserves them but ignores `from`."},"default":false},"description":"For MS Graph accounts: send as structured JSON instead of raw MIME"}],"tags":["Submit"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitMessage"}}}},"responses":{"200":{"description":"Returns the queue ID the message was accepted under. Delivery happens asynchronously - a 200 means queued, not sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitMessageResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"503":{"description":"Service unavailable - the worker processing this account is not available, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponse"}}}}},"x-ee-impact":"sends","x-ee-behavior":["Delivery is asynchronous. A 2xx means the message was queued, not that it was sent. Failed attempts are retried with exponential backoff up to the configured deliveryAttempts; follow the outcome through the Outbox endpoints or the messageSent, messageDeliveryError and messageFailed webhooks.","For SMTP accounts EmailEngine uploads the sent message to the Sent Mail folder after delivery. Gmail API and MS Graph accounts file sent messages themselves, so no upload is performed."],"x-ee-action":"send","x-ee-group":"submit"}},"/v1/account/{account}/sync":{"put":{"summary":"Request syncing","operationId":"putV1AccountAccountSync","description":"Immediately trigger account syncing for IMAP accounts<br/><br/>The request only schedules the work and returns before it finishes. Watch the account state, or the accountInitialized and authenticationError webhooks, for the result.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true}],"tags":["Account"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestSync"}}}},"responses":{"200":{"description":"Returns an acknowledgement. A full mailbox sync is scheduled and runs in the background.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestSyncResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-behavior":["The request only schedules the work and returns before it finishes. Watch the account state, or the accountInitialized and authenticationError webhooks, for the result."],"x-ee-action":"write","x-ee-group":"account"}},"/v1/account/{account}/text/{text}":{"get":{"summary":"Retrieve message text","operationId":"getV1AccountAccountTextText","description":"Retrieves message text","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"text","in":"path","schema":{"type":"string","description":"Message text ID","example":"AAAAAQAACnAcdfaaN","maxLength":10240},"description":"Message text ID","required":true},{"name":"maxBytes","in":"query","schema":{"type":"integer","description":"Max length of text content. Ignored for Gmail API and MS Graph API accounts (full content is always returned)","example":52428800,"minimum":0,"maximum":1073741824},"description":"Max length of text content. Ignored for Gmail API and MS Graph API accounts (full content is always returned)"},{"name":"textType","in":"query","schema":{"type":"string","description":"Which text content to return, use * for all. By default all contents are returned.","example":"*","default":"*","enum":["html","plain","*"],"x-convert":{"case":"lower"}},"description":"Which text content to return, use * for all. By default all contents are returned."}],"tags":["Message"],"responses":{"200":{"description":"Returns the message text content in the requested formats.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TextResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"503":{"description":"Service unavailable - the worker processing this account is not available, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"message"}},"/v1/accounts":{"get":{"summary":"List accounts","operationId":"getV1Accounts","description":"Lists registered accounts","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"page","in":"query","schema":{"type":"integer","description":"Page number (zero indexed, so use 0 for first page)","example":0,"default":0,"minimum":0,"maximum":1048576},"description":"Page number (zero indexed, so use 0 for first page)"},{"name":"pageSize","in":"query","schema":{"type":"integer","description":"How many entries per page","example":20,"default":20,"minimum":1,"maximum":1000},"description":"How many entries per page"},{"name":"state","in":"query","schema":{"type":"string","description":"Filter accounts by state","example":"connected","x-meta":{"enumDescriptions":{"init":"The account was just registered and has not connected yet","connecting":"Connecting to the mail server or authorizing with the provider","syncing":"Connected and performing the initial or a periodic mailbox sync","connected":"Connected and watching for changes. This is the healthy steady state","disconnected":"The connection dropped and EmailEngine is retrying with backoff","paused":"Syncing was paused through the API. No connection is maintained","authenticationError":"The credentials were rejected. Requires re-authentication before syncing resumes","connectError":"The server could not be reached or the TLS handshake failed. Retried with backoff","unset":"No IMAP or OAuth2 configuration is set, so the account is not synced"}},"enum":["init","unset","connected","connecting","syncing","authenticationError","connectError","disconnected","paused"]},"description":"Filter accounts by state"},{"name":"query","in":"query","schema":{"type":"string","description":"Filter accounts by string match","example":"user@example.com"},"description":"Filter accounts by string match"}],"tags":["Account"],"responses":{"200":{"description":"Returns a page of accounts with their connection states.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountsFilterResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"account"}},"/v1/authentication/form":{"post":{"summary":"Generate authentication link","operationId":"postV1AuthenticationForm","description":"Generates a redirect link to the hosted authentication form<br/><br/>If `expectedEmail` is set and the user completes the form as a different identity, the setup is rejected before any credentials are stored. The user stays on EmailEngine, which names both addresses and offers to restart the setup, so the browser is never redirected to `redirectUrl`.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"}],"tags":["Account"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestAuthForm"}}}},"responses":{"200":{"description":"Returns a single-use URL for the hosted authentication form.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestAuthFormResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"write","x-ee-group":"admin"}},"/v1/autoconfig":{"get":{"summary":"Discover Email settings","operationId":"getV1Autoconfig","description":"Try to discover IMAP and SMTP settings for an email account","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"email","in":"query","schema":{"type":"string","description":"Email address to discover email settings for","example":"sender@example.com","x-format":{"email":true}},"description":"Email address to discover email settings for","required":true}],"tags":["Settings"],"responses":{"200":{"description":"Returns the discovered IMAP and SMTP settings for the address, or empty values when nothing could be resolved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoveredEmailSettings"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"diagnostics"}},"/v1/blocklist/{listId}":{"get":{"summary":"List blocklist entries","operationId":"getV1BlocklistListid","description":"List suppressed addresses for a list","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"listId","in":"path","schema":{"type":"string","description":"List ID. Must use a subdomain name format. Lists are registered ad-hoc, so a new identifier defines a new list.","example":"test-list","x-format":{"hostname":true}},"description":"List ID. Must use a subdomain name format. Lists are registered ad-hoc, so a new identifier defines a new list.","required":true},{"name":"page","in":"query","schema":{"type":"integer","description":"Page number (zero indexed, so use 0 for first page)","example":0,"default":0,"minimum":0,"maximum":1048576},"description":"Page number (zero indexed, so use 0 for first page)"},{"name":"pageSize","in":"query","schema":{"type":"integer","description":"How many entries per page","example":20,"default":20,"minimum":1,"maximum":1000},"description":"How many entries per page"}],"tags":["Blocklists"],"responses":{"200":{"description":"Returns a page of entries on the blocklist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlocklistListResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"blocklist"},"post":{"summary":"Add to blocklist","operationId":"postV1BlocklistListid","description":"Add an email address to a suppression list. Sending with this listId skips the address","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"listId","in":"path","schema":{"type":"string","description":"List ID. Must use a subdomain name format. Lists are registered ad-hoc, so a new identifier defines a new list.","example":"test-list","x-format":{"hostname":true}},"description":"List ID. Must use a subdomain name format. Lists are registered ad-hoc, so a new identifier defines a new list.","required":true}],"tags":["Blocklists"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlocklistListAddPayload"}}}},"responses":{"200":{"description":"Returns whether the address was added or was already listed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlocklistListAddResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"write","x-ee-group":"blocklist"},"delete":{"summary":"Remove from blocklist","operationId":"deleteV1BlocklistListid","description":"Remove a suppressed email address from a list","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"listId","in":"path","schema":{"type":"string","description":"List ID. Must use a subdomain name format. Lists are registered ad-hoc, so a new identifier defines a new list.","example":"test-list","x-format":{"hostname":true}},"description":"List ID. Must use a subdomain name format. Lists are registered ad-hoc, so a new identifier defines a new list.","required":true},{"name":"recipient","in":"query","schema":{"type":"string","description":"Email address to remove from the list","example":"user@example.com","x-format":{"email":true}},"description":"Email address to remove from the list","required":true}],"tags":["Blocklists"],"responses":{"200":{"description":"Returns a deletion marker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteBlocklistResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-impact":"destructive","x-ee-action":"destructive","x-ee-group":"blocklist"}},"/v1/blocklists":{"get":{"summary":"List blocklists","operationId":"getV1Blocklists","description":"List suppression lists (blocklists) with the number of blocked addresses on each","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"page","in":"query","schema":{"type":"integer","description":"Page number (zero indexed, so use 0 for first page)","example":0,"default":0,"minimum":0,"maximum":1048576},"description":"Page number (zero indexed, so use 0 for first page)"},{"name":"pageSize","in":"query","schema":{"type":"integer","description":"How many entries per page","example":20,"default":20,"minimum":1,"maximum":1000},"description":"How many entries per page"}],"tags":["Blocklists"],"responses":{"200":{"description":"Returns every blocklist with its entry count.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlocklistsResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"blocklist"}},"/v1/changes":{"get":{"summary":"Stream state changes","operationId":"getV1Changes","description":"Stream account state changes as an EventSource<br/><br/>A long-lived Server-Sent Events stream rather than a normal request and response. The connection stays open until the client closes it.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"}],"tags":["Account"],"responses":{"200":{"description":"Returns an open EventSource stream of account state changes.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-behavior":["A long-lived Server-Sent Events stream rather than a normal request and response. The connection stays open until the client closes it."],"x-ee-action":"read","x-ee-group":"events"}},"/v1/delivery-test/account/{account}":{"post":{"summary":"Create delivery test","operationId":"postV1DeliverytestAccountAccount","description":"Initiate a delivery test<br/><br/>Runs as a background job. Follow it either by polling the status endpoint or by waiting for the completion webhook.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true}],"tags":["Delivery Test"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryStartRequest"}}}},"responses":{"200":{"description":"Returns the ID of the started deliverability test. Poll the check endpoint for the result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryStartResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-impact":"sends","x-ee-behavior":["Runs as a background job. Follow it either by polling the status endpoint or by waiting for the completion webhook."],"x-ee-action":"send","x-ee-group":"submit"}},"/v1/delivery-test/check/{deliveryTest}":{"get":{"summary":"Check test status","operationId":"getV1DeliverytestCheckDeliverytest","description":"Check delivery test status","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"deliveryTest","in":"path","schema":{"type":"string","description":"Test ID","example":"6420a6ad-7f82-4e4f-8112-82a9dad1f34d","x-format":{"guid":{"version":["uuidv4","uuidv5"]}}},"description":"Test ID","required":true}],"tags":["Delivery Test"],"responses":{"200":{"description":"Returns the test result once it has completed, including SPF, DKIM and DMARC outcomes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryCheckResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"diagnostics"}},"/v1/gateway":{"post":{"summary":"Register new gateway","operationId":"postV1Gateway","description":"Registers a new SMP gateway","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"}],"tags":["SMTP Gateway"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGateway"}}}},"responses":{"200":{"description":"Returns the registered gateway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGatewayResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"write","x-ee-group":"admin"}},"/v1/gateway/{gateway}":{"get":{"summary":"Get gateway info","operationId":"getV1GatewayGateway","description":"Returns stored information about the gateway. Credentials are masked: stored passwords, the credentials in any proxy or webhook URL, and the values of custom webhook headers all read back as \"******\". A masked value is not the stored one - leave the field out of an update rather than writing it back, otherwise the mask replaces the credential.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"gateway","in":"path","schema":{"type":"string","description":"Gateway ID","example":"example","maxLength":256},"description":"Gateway ID","required":true}],"tags":["SMTP Gateway"],"responses":{"200":{"description":"Returns the gateway configuration. The password is masked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"gateway"},"delete":{"summary":"Remove SMTP gateway","operationId":"deleteV1GatewayGateway","description":"Delete SMTP gateway data","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"gateway","in":"path","schema":{"type":"string","description":"Gateway ID","example":"example","maxLength":256},"description":"Gateway ID","required":true}],"tags":["SMTP Gateway"],"responses":{"200":{"description":"Returns a deletion marker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteGatewayResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-impact":"destructive","x-ee-action":"destructive","x-ee-group":"gateway"}},"/v1/gateway/edit/{gateway}":{"put":{"summary":"Update gateway info","operationId":"putV1GatewayEditGateway","description":"Updates gateway information","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"gateway","in":"path","schema":{"type":"string","description":"Gateway ID","example":"example","maxLength":256},"description":"Gateway ID","required":true}],"tags":["SMTP Gateway"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateGateway"}}}},"responses":{"200":{"description":"Returns the updated gateway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateGatewayResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"write","x-ee-group":"admin"}},"/v1/gateways":{"get":{"summary":"List gateways","operationId":"getV1Gateways","description":"Lists registered gateways","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"page","in":"query","schema":{"type":"integer","description":"Page number (zero indexed, so use 0 for first page)","example":0,"default":0,"minimum":0,"maximum":1048576},"description":"Page number (zero indexed, so use 0 for first page)"},{"name":"pageSize","in":"query","schema":{"type":"integer","description":"How many entries per page","example":20,"default":20,"minimum":1,"maximum":1000},"description":"How many entries per page"}],"tags":["SMTP Gateway"],"responses":{"200":{"description":"Returns a page of configured SMTP gateways.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewaysFilterResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"gateway"}},"/v1/license":{"get":{"summary":"Request license info","operationId":"getV1License","description":"Get active license information","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"}],"tags":["License"],"responses":{"200":{"description":"Returns the active license and its expiry, or an empty object when unlicensed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"admin"},"post":{"summary":"Register a license","operationId":"postV1License","description":"Set up a license for EmailEngine to unlock all features","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"}],"tags":["License"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterLicense"}}}},"responses":{"200":{"description":"Returns the registered license.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"write","x-ee-group":"admin"},"delete":{"summary":"Remove license","operationId":"deleteV1License","description":"Remove registered active license","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"}],"tags":["License"],"responses":{"200":{"description":"Returns an empty license object. EmailEngine drops to limited mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyLicenseResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-impact":"destructive","x-ee-action":"destructive","x-ee-group":"admin"}},"/v1/logs/{account}":{"get":{"summary":"Return IMAP logs for an account","operationId":"getV1LogsAccount","description":"Output is a downloadable text file<br/><br/>Only available for IMAP accounts. Gmail API and MS Graph accounts have no equivalent.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true}],"tags":["Logs"],"responses":{"200":{"description":"Returns the account log as a plain text stream.","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-behavior":["Only available for IMAP accounts. Gmail API and MS Graph accounts have no equivalent."],"x-ee-action":"read","x-ee-group":"logs"}},"/v1/oauth2":{"get":{"summary":"List OAuth2 applications","operationId":"getV1Oauth2","description":"Lists registered OAuth2 applications","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"page","in":"query","schema":{"type":"integer","description":"Page number (zero indexed, so use 0 for first page)","example":0,"default":0,"minimum":0,"maximum":1048576},"description":"Page number (zero indexed, so use 0 for first page)"},{"name":"pageSize","in":"query","schema":{"type":"integer","description":"How many entries per page","example":20,"default":20,"minimum":1,"maximum":1000},"description":"How many entries per page"}],"tags":["OAuth2 Applications"],"responses":{"200":{"description":"Returns a page of OAuth2 applications.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuth2FilterResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"admin"},"post":{"summary":"Register OAuth2 application","operationId":"postV1Oauth2","description":"Registers a new OAuth2 application for a specific provider","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"}],"tags":["OAuth2 Applications"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOAuth2App"}}}},"responses":{"200":{"description":"Returns the registered OAuth2 application.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAppResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"write","x-ee-group":"admin"}},"/v1/oauth2/{app}":{"get":{"summary":"Get application info","operationId":"getV1Oauth2App","description":"Returns stored information about an OAuth2 application. Secrets are not included.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"app","in":"path","schema":{"type":"string","description":"OAuth2 application ID","example":"AAABhaBPHscAAAAH","maxLength":256},"description":"OAuth2 application ID","required":true}],"tags":["OAuth2 Applications"],"responses":{"200":{"description":"Returns the OAuth2 application. Client secrets are masked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"admin"},"put":{"summary":"Update OAuth2 application","operationId":"putV1Oauth2App","description":"Updates OAuth2 application information","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"app","in":"path","schema":{"type":"string","description":"OAuth2 application ID","example":"AAABhaBPHscAAAAH","maxLength":256},"description":"OAuth2 application ID","required":true}],"tags":["OAuth2 Applications"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOAuthApp"}}}},"responses":{"200":{"description":"Returns the updated OAuth2 application.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOAuthAppResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"write","x-ee-group":"admin"},"delete":{"summary":"Remove OAuth2 application","operationId":"deleteV1Oauth2App","description":"Delete OAuth2 application data","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"app","in":"path","schema":{"type":"string","description":"OAuth2 application ID","example":"AAABhaBPHscAAAAH","maxLength":256},"description":"OAuth2 application ID","required":true}],"tags":["OAuth2 Applications"],"responses":{"200":{"description":"Returns a deletion marker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteAppRequestResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-impact":"destructive","x-ee-action":"destructive","x-ee-group":"admin"}},"/v1/oauth2/{app}/verify":{"post":{"summary":"Verify OAuth2 application setup","operationId":"postV1Oauth2AppVerify","description":"Runs the provider authentication chain step by step and reports which steps pass or fail, with hints for fixing failures. For service-account apps an optional mailbox address enables the delegation and live mailbox checks.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"app","in":"path","schema":{"type":"string","description":"OAuth2 application ID","example":"AAABhaBPHscAAAAH","maxLength":256},"description":"OAuth2 application ID","required":true}],"tags":["OAuth2 Applications"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyOAuth2AppRequest"}}}},"responses":{"200":{"description":"Returns the outcome of the credential check against the provider.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyOAuth2AppResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-impact":"readonly","x-ee-action":"read","x-ee-group":"admin"}},"/v1/outbox":{"get":{"summary":"List queued messages","operationId":"getV1Outbox","description":"Lists messages in the Outbox. Credentials are masked: stored passwords, the credentials in any proxy or webhook URL, and the values of custom webhook headers all read back as \"******\". A masked value is not the stored one - leave the field out of an update rather than writing it back, otherwise the mask replaces the credential.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"page","in":"query","schema":{"type":"integer","description":"Page number (zero indexed, so use 0 for first page)","example":0,"default":0,"minimum":0,"maximum":1048576},"description":"Page number (zero indexed, so use 0 for first page)"},{"name":"pageSize","in":"query","schema":{"type":"integer","description":"How many entries per page","example":20,"default":20,"minimum":1,"maximum":1000},"description":"How many entries per page"}],"tags":["Outbox"],"responses":{"200":{"description":"Returns the messages currently queued for delivery.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboxListResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"outbox"}},"/v1/outbox/{queueId}":{"get":{"summary":"Get queued message","operationId":"getV1OutboxQueueid","description":"Gets a queued message in the Outbox. Credentials are masked: stored passwords, the credentials in any proxy or webhook URL, and the values of custom webhook headers all read back as \"******\". A masked value is not the stored one - leave the field out of an update rather than writing it back, otherwise the mask replaces the credential.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"queueId","in":"path","schema":{"type":"string","description":"Queue identifier for scheduled email","example":"d41f0423195f271f","maxLength":100},"description":"Queue identifier for scheduled email","required":true}],"tags":["Outbox"],"responses":{"200":{"description":"Returns the queued message, including its delivery attempts and last error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboxEntry"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"outbox"},"delete":{"summary":"Remove a message","operationId":"deleteV1OutboxQueueid","description":"Remove a message from the outbox","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"queueId","in":"path","schema":{"type":"string","description":"Queue identifier for scheduled email","example":"d41f0423195f271f","maxLength":100},"description":"Queue identifier for scheduled email","required":true}],"tags":["Outbox"],"responses":{"200":{"description":"Returns a deletion marker. A message already being delivered cannot be removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteOutboxEntryResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-impact":"destructive","x-ee-action":"destructive","x-ee-group":"outbox"}},"/v1/pubsub/status":{"get":{"summary":"List Pub/Sub status","operationId":"getV1PubsubStatus","description":"Lists Pub/Sub enabled OAuth2 applications and their subscription status","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"page","in":"query","schema":{"type":"integer","description":"Page number (zero indexed, so use 0 for first page)","example":0,"default":0,"minimum":0,"maximum":1048576},"description":"Page number (zero indexed, so use 0 for first page)"},{"name":"pageSize","in":"query","schema":{"type":"integer","description":"How many entries per page","example":20,"default":20,"minimum":1,"maximum":1000},"description":"How many entries per page"}],"tags":["OAuth2 Applications"],"responses":{"200":{"description":"Returns the Pub/Sub subscription state for each configured Gmail application.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubSubStatusResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"diagnostics"}},"/v1/settings":{"get":{"summary":"List specific settings","operationId":"getV1Settings","description":"List setting values for specific keys","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"eventTypes","in":"query","schema":{"type":"boolean","default":false}},{"name":"webhooksEnabled","in":"query","schema":{"type":"boolean","default":false}},{"name":"webhooks","in":"query","schema":{"type":"boolean","default":false}},{"name":"webhookEvents","in":"query","schema":{"type":"boolean","default":false}},{"name":"webhooksCustomHeaders","in":"query","schema":{"type":"boolean","default":false}},{"name":"notifyHeaders","in":"query","schema":{"type":"boolean","default":false}},{"name":"serviceUrl","in":"query","schema":{"type":"boolean","default":false}},{"name":"notificationBaseUrl","in":"query","schema":{"type":"boolean","default":false}},{"name":"trackSentMessages","in":"query","schema":{"type":"boolean","default":false}},{"name":"trackClicks","in":"query","schema":{"type":"boolean","default":false}},{"name":"trackOpens","in":"query","schema":{"type":"boolean","default":false}},{"name":"imapIndexer","in":"query","schema":{"type":"boolean","default":false}},{"name":"resolveGmailCategories","in":"query","schema":{"type":"boolean","default":false}},{"name":"ignoreMailCertErrors","in":"query","schema":{"type":"boolean","default":false}},{"name":"generateEmailSummary","in":"query","schema":{"type":"boolean","default":false}},{"name":"generateRiskAssessment","in":"query","schema":{"type":"boolean","default":false}},{"name":"openAiAPIKey","in":"query","schema":{"type":"boolean","default":false}},{"name":"openAiModel","in":"query","schema":{"type":"boolean","default":false}},{"name":"openAiAPIUrl","in":"query","schema":{"type":"boolean","default":false}},{"name":"documentStoreChatModel","in":"query","schema":{"type":"boolean","default":false}},{"name":"openAiTemperature","in":"query","schema":{"type":"boolean","default":false}},{"name":"openAiTopP","in":"query","schema":{"type":"boolean","default":false}},{"name":"openAiMaxTokens","in":"query","schema":{"type":"boolean","default":false}},{"name":"openAiPrompt","in":"query","schema":{"type":"boolean","default":false}},{"name":"openAiGenerateEmbeddings","in":"query","schema":{"type":"boolean","default":false}},{"name":"inboxNewOnly","in":"query","schema":{"type":"boolean","default":false}},{"name":"serviceSecret","in":"query","schema":{"type":"boolean","default":false}},{"name":"authServer","in":"query","schema":{"type":"boolean","default":false}},{"name":"tokenAuditLog","in":"query","schema":{"type":"boolean","default":false}},{"name":"proxyEnabled","in":"query","schema":{"type":"boolean","default":false}},{"name":"proxyUrl","in":"query","schema":{"type":"boolean","default":false}},{"name":"httpProxyEnabled","in":"query","schema":{"type":"boolean","default":false}},{"name":"httpProxyUrl","in":"query","schema":{"type":"boolean","default":false}},{"name":"smtpEhloName","in":"query","schema":{"type":"boolean","default":false}},{"name":"notifyText","in":"query","schema":{"type":"boolean","default":false}},{"name":"notifyWebSafeHtml","in":"query","schema":{"type":"boolean","default":false}},{"name":"notifyTextSize","in":"query","schema":{"type":"boolean","default":false}},{"name":"notifyAttachments","in":"query","schema":{"type":"boolean","default":false}},{"name":"notifyAttachmentSize","in":"query","schema":{"type":"boolean","default":false}},{"name":"notifyCalendarEvents","in":"query","schema":{"type":"boolean","default":false}},{"name":"documentStoreEnabled","in":"query","schema":{"type":"boolean","default":false}},{"name":"documentStoreUrl","in":"query","schema":{"type":"boolean","default":false}},{"name":"documentStoreIndex","in":"query","schema":{"type":"boolean","default":false}},{"name":"documentStoreAuthEnabled","in":"query","schema":{"type":"boolean","default":false}},{"name":"documentStoreUsername","in":"query","schema":{"type":"boolean","default":false}},{"name":"documentStorePassword","in":"query","schema":{"type":"boolean","default":false}},{"name":"documentStoreGenerateEmbeddings","in":"query","schema":{"type":"boolean","default":false}},{"name":"documentStorePreProcessingEnabled","in":"query","schema":{"type":"boolean","default":false}},{"name":"logs","in":"query","schema":{"type":"boolean","default":false}},{"name":"sentryEnabled","in":"query","schema":{"type":"boolean","default":false}},{"name":"sentryDsn","in":"query","schema":{"type":"boolean","default":false}},{"name":"imapStrategy","in":"query","schema":{"type":"boolean","default":false}},{"name":"smtpStrategy","in":"query","schema":{"type":"boolean","default":false}},{"name":"localAddresses","in":"query","schema":{"type":"boolean","default":false}},{"name":"smtpServerEnabled","in":"query","schema":{"type":"boolean","default":false}},{"name":"smtpServerPort","in":"query","schema":{"type":"boolean","default":false}},{"name":"smtpServerHost","in":"query","schema":{"type":"boolean","default":false}},{"name":"smtpServerProxy","in":"query","schema":{"type":"boolean","default":false}},{"name":"smtpServerAuthEnabled","in":"query","schema":{"type":"boolean","default":false}},{"name":"smtpServerPassword","in":"query","schema":{"type":"boolean","default":false}},{"name":"smtpServerTLSEnabled","in":"query","schema":{"type":"boolean","default":false}},{"name":"imapProxyServerEnabled","in":"query","schema":{"type":"boolean","default":false}},{"name":"imapProxyServerPort","in":"query","schema":{"type":"boolean","default":false}},{"name":"imapProxyServerHost","in":"query","schema":{"type":"boolean","default":false}},{"name":"imapProxyServerProxy","in":"query","schema":{"type":"boolean","default":false}},{"name":"imapProxyServerPassword","in":"query","schema":{"type":"boolean","default":false}},{"name":"imapProxyServerTLSEnabled","in":"query","schema":{"type":"boolean","default":false}},{"name":"queueKeep","in":"query","schema":{"type":"boolean","default":false}},{"name":"deliveryAttempts","in":"query","schema":{"type":"boolean","default":false}},{"name":"gmailSubscriptionTtl","in":"query","schema":{"type":"boolean","default":false}},{"name":"templateHeader","in":"query","schema":{"type":"boolean","default":false}},{"name":"templateHtmlHead","in":"query","schema":{"type":"boolean","default":false}},{"name":"scriptEnv","in":"query","schema":{"type":"boolean","default":false}},{"name":"enableApiProxy","in":"query","schema":{"type":"boolean","default":false}},{"name":"locale","in":"query","schema":{"type":"boolean","default":false}},{"name":"timezone","in":"query","schema":{"type":"boolean","default":false}},{"name":"pageBrandName","in":"query","schema":{"type":"boolean","default":false}},{"name":"openAiPreProcessingFn","in":"query","schema":{"type":"boolean","default":false}},{"name":"imapClientName","in":"query","schema":{"type":"boolean","default":false}},{"name":"imapClientVersion","in":"query","schema":{"type":"boolean","default":false}},{"name":"imapClientVendor","in":"query","schema":{"type":"boolean","default":false}},{"name":"imapClientSupportUrl","in":"query","schema":{"type":"boolean","default":false}},{"name":"exportMaxConcurrent","in":"query","schema":{"type":"boolean","default":false}},{"name":"exportMaxGlobalConcurrent","in":"query","schema":{"type":"boolean","default":false}},{"name":"gmailExportBatchSize","in":"query","schema":{"type":"boolean","default":false}},{"name":"outlookExportBatchSize","in":"query","schema":{"type":"boolean","default":false}},{"name":"exportMaxMessages","in":"query","schema":{"type":"boolean","default":false}},{"name":"exportMaxSize","in":"query","schema":{"type":"boolean","default":false}}],"tags":["Settings"],"responses":{"200":{"description":"Returns the values of the settings requested via query arguments. Secrets are masked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsQueryResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"admin"},"post":{"summary":"Set setting values","operationId":"postV1Settings","description":"Set setting values for specific keys","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"}],"tags":["Settings"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Settings"}}}},"responses":{"200":{"description":"Returns the list of setting keys that were updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsUpdatedResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"write","x-ee-group":"admin"}},"/v1/settings/queue/{queue}":{"get":{"summary":"Show queue information","operationId":"getV1SettingsQueueQueue","description":"Show queue status and current state","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"queue","in":"path","schema":{"type":"string","description":"Queue ID","example":"notify","enum":["notify","submit","documents"],"x-convert":{"trim":true}},"description":"Queue ID","required":true}],"tags":["Settings"],"responses":{"200":{"description":"Returns the job counts and paused state for the queue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsQueueResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"admin"},"put":{"summary":"Set queue settings","operationId":"putV1SettingsQueueQueue","description":"Set queue settings","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"queue","in":"path","schema":{"type":"string","description":"Queue ID","example":"notify","enum":["notify","submit","documents"],"x-convert":{"trim":true}},"description":"Queue ID","required":true}],"tags":["Settings"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsPutQueuePayload"}}}},"responses":{"200":{"description":"Returns the queue state after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsPutQueueResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"write","x-ee-group":"admin"}},"/v1/stats":{"get":{"summary":"Return server stats","operationId":"getV1Stats","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"seconds","in":"query","schema":{"type":"integer","description":"Duration for counters","example":3600,"default":3600,"minimum":0,"maximum":604800},"description":"Duration for counters"}],"tags":["Stats"],"responses":{"200":{"description":"Returns counters, connection states and process information for this instance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"diagnostics"}},"/v1/templates":{"get":{"summary":"List account templates","operationId":"getV1Templates","description":"Lists stored templates for the account","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"query","schema":{"type":"string","description":"Account ID to list the templates for","example":"example","maxLength":256},"description":"Account ID to list the templates for"},{"name":"page","in":"query","schema":{"type":"integer","description":"Page number (zero indexed, so use 0 for first page)","example":0,"default":0,"minimum":0,"maximum":1048576},"description":"Page number (zero indexed, so use 0 for first page)"},{"name":"pageSize","in":"query","schema":{"type":"integer","description":"How many entries per page","example":20,"default":20,"minimum":1,"maximum":1000},"description":"How many entries per page"}],"tags":["Templates"],"responses":{"200":{"description":"Returns a page of stored templates for the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountTemplatesResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"template"}},"/v1/templates/account/{account}":{"delete":{"summary":"Flush templates","operationId":"deleteV1TemplatesAccountAccount","description":"Delete all stored templates for an account","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"account","in":"path","schema":{"type":"string","description":"Unique identifier for the email account","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Unique identifier for the email account","required":true},{"name":"force","in":"query","schema":{"type":"boolean","description":"Must be true in order to flush templates","default":false},"description":"Must be true in order to flush templates"}],"tags":["Templates"],"responses":{"200":{"description":"Returns the number of templates removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlushTemplatesResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-impact":"destructive","x-ee-action":"destructive","x-ee-group":"template"}},"/v1/templates/template":{"post":{"summary":"Create template","operationId":"postV1TemplatesTemplate","description":"Create a new stored template. Templates can be used when sending emails as the content of the message.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"}],"tags":["Templates"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTemplate"}}}},"responses":{"200":{"description":"Returns the created template.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTemplateResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"write","x-ee-group":"template"}},"/v1/templates/template/{template}":{"get":{"summary":"Get template information","operationId":"getV1TemplatesTemplateTemplate","description":"Retrieve template content and information","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"template","in":"path","schema":{"type":"string","description":"Template ID","example":"example","maxLength":256},"description":"Template ID","required":true}],"tags":["Templates"],"responses":{"200":{"description":"Returns the template, including its content.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountTemplateResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"template"},"put":{"summary":"Update a template","operationId":"putV1TemplatesTemplateTemplate","description":"Update a stored template.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"template","in":"path","schema":{"type":"string","description":"Template ID","example":"example","maxLength":256},"description":"Template ID","required":true}],"tags":["Templates"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTemplate"}}}},"responses":{"200":{"description":"Returns the updated template.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTemplateResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"write","x-ee-group":"template"},"delete":{"summary":"Remove a template","operationId":"deleteV1TemplatesTemplateTemplate","description":"Delete a stored template","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"template","in":"path","schema":{"type":"string","description":"Template ID","example":"example","maxLength":256},"description":"Template ID","required":true}],"tags":["Templates"],"responses":{"200":{"description":"Returns a deletion marker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteTemplateResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-impact":"destructive","x-ee-action":"destructive","x-ee-group":"template"}},"/v1/tokens":{"get":{"summary":"List access tokens","operationId":"getV1Tokens","description":"Lists access tokens. Returns every token on the instance unless narrowed with the account argument. Token values are never returned - only the id each token is listed under.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"page","in":"query","schema":{"type":"integer","description":"Page number (zero indexed, so use 0 for first page)","example":0,"default":0,"minimum":0,"maximum":1048576},"description":"Page number (zero indexed, so use 0 for first page)"},{"name":"pageSize","in":"query","schema":{"type":"integer","description":"How many entries per page","example":20,"default":20,"minimum":1,"maximum":1000},"description":"How many entries per page"},{"name":"query","in":"query","schema":{"type":"string","description":"Filter by description, id or account","example":"agent","maxLength":1024,"x-convert":{"trim":true}},"description":"Filter by description, id or account"},{"name":"account","in":"query","schema":{"type":"string","description":"Only list tokens bound to this account. Omit to list every token on the instance","example":"user123","maxLength":256,"x-convert":{"trim":true}},"description":"Only list tokens bound to this account. Omit to list every token on the instance"}],"tags":["Access Tokens"],"responses":{"200":{"description":"Returns the matching access tokens. Token values are never returned after creation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokensResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"admin"},"post":{"summary":"Provision an access token","operationId":"postV1Tokens","description":"Provisions a new access token. Either bind it to an account, or set `permissions` - an instance-wide token that is not narrowed reaches every account and every endpoint, so the API declines to mint one.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"}],"tags":["Access Tokens"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateToken"}}}},"responses":{"200":{"description":"Returns the new token value. This is the only time it is shown - store it now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTokenResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"write","x-ee-group":"admin"}},"/v1/tokens/{token}":{"get":{"summary":"Get token info","operationId":"getV1TokensToken","description":"Returns stored information about a single access token. The token value itself is never returned - it is only shown once, when the token is created.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"token","in":"path","schema":{"type":"string","description":"The token id, as reported by POST /v1/tokens and the token listing","example":"123456","x-constraint":{"length":64},"x-format":{"hex":{"byteAligned":false,"prefix":false}}},"description":"The token id, as reported by POST /v1/tokens and the token listing","required":true}],"tags":["Access Tokens"],"responses":{"200":{"description":"Returns the stored token record. The token value is not included.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"admin"},"delete":{"summary":"Remove a token","operationId":"deleteV1TokensToken","description":"Delete an access token","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"token","in":"path","schema":{"type":"string","description":"The access token value, or the token id from a listing","example":"123456","x-constraint":{"length":64},"x-format":{"hex":{"byteAligned":false,"prefix":false}}},"description":"The access token value, or the token id from a listing","required":true}],"tags":["Access Tokens"],"responses":{"200":{"description":"Returns a deletion marker. The token stops working immediately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteTokenRequestResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-impact":"destructive","x-ee-action":"destructive","x-ee-group":"admin"}},"/v1/tokens/{token}/log":{"get":{"summary":"Get token audit log","operationId":"getV1TokensTokenLog","description":"Lists recent requests made with an access token, newest first. Requires the tokenAuditLog setting to be enabled; it is off by default, and entries only exist from the point it was switched on.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"token","in":"path","schema":{"type":"string","description":"The token id, as reported by POST /v1/tokens and the token listing","example":"123456","x-constraint":{"length":64},"x-format":{"hex":{"byteAligned":false,"prefix":false}}},"description":"The token id, as reported by POST /v1/tokens and the token listing","required":true},{"name":"page","in":"query","schema":{"type":"integer","description":"Page number (zero indexed, so use 0 for first page)","example":0,"default":0,"minimum":0,"maximum":1048576},"description":"Page number (zero indexed, so use 0 for first page)"},{"name":"pageSize","in":"query","schema":{"type":"integer","description":"How many entries per page","example":20,"default":20,"minimum":1,"maximum":200},"description":"How many entries per page"}],"tags":["Access Tokens"],"responses":{"200":{"description":"Returns the recorded requests for this token, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenLogResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-impact":"readonly","x-ee-action":"read","x-ee-group":"admin"}},"/v1/verifyAccount":{"post":{"summary":"Verify IMAP and SMTP settings","operationId":"postV1Verifyaccount","description":"Checks if can connect and authenticate using provided account info","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"}],"tags":["Account"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyAccount"}}}},"responses":{"200":{"description":"Returns the outcome of the IMAP and SMTP connection tests, including per-protocol errors when a test failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyAccountResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-impact":"readonly","x-ee-action":"read","x-ee-group":"admin"}},"/v1/webhookRoutes":{"get":{"summary":"List webhook routes","operationId":"getV1Webhookroutes","description":"List custom webhook routes. Credentials are masked: stored passwords, the credentials in any proxy or webhook URL, and the values of custom webhook headers all read back as \"******\". A masked value is not the stored one - leave the field out of an update rather than writing it back, otherwise the mask replaces the credential.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"page","in":"query","schema":{"type":"integer","description":"Page number (zero indexed, so use 0 for first page)","example":0,"default":0,"minimum":0,"maximum":1048576},"description":"Page number (zero indexed, so use 0 for first page)"},{"name":"pageSize","in":"query","schema":{"type":"integer","description":"How many entries per page","example":20,"default":20,"minimum":1,"maximum":1000},"description":"How many entries per page"}],"tags":["Webhooks"],"responses":{"200":{"description":"Returns a page of custom webhook routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRoutesListResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"webhook"}},"/v1/webhookRoutes/webhookRoute/{webhookRoute}":{"get":{"summary":"Get webhook route information","operationId":"getV1WebhookroutesWebhookrouteWebhookroute","description":"Retrieve webhook route content and information. Credentials are masked: stored passwords, the credentials in any proxy or webhook URL, and the values of custom webhook headers all read back as \"******\". A masked value is not the stored one - leave the field out of an update rather than writing it back, otherwise the mask replaces the credential.","parameters":[{"name":"x-ee-timeout","in":"header","schema":{"type":"integer","description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)","example":30000,"minimum":0,"maximum":7200000},"description":"Request timeout in milliseconds (overrides EENGINE_TIMEOUT environment variable)"},{"name":"webhookRoute","in":"path","schema":{"type":"string","description":"Webhook ID","example":"example","maxLength":256},"description":"Webhook ID","required":true}],"tags":["Webhooks"],"responses":{"200":{"description":"Returns the webhook route, including its filter and transform functions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRouteResponse"}}}},"400":{"description":"Invalid input - the path parameters, query arguments, or request payload did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Authentication failed - the access token is missing, invalid, or was not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorResponse"}}}},"403":{"description":"Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedErrorResponse"}}}},"404":{"description":"Not found - the requested entity (account, message, mailbox, etc.) does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"429":{"description":"Rate limit exceeded - too many requests were made with this access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error - an unexpected error occurred while processing the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"x-ee-action":"read","x-ee-group":"webhook"}}}}