icewarptechnology/lapi-email-service repository overview

⁠IceWarp Email Service in Docker

Docker image for the IceWarp Email Service created by the IceWarp team.

lapi-email-service is a stateless HTTP gateway that exposes the IceWarp public email API and translates every call into one or more calls against the Mail API of a running IceWarp server⁠. It holds no database, no cache and no session store, so it can be scaled horizontally and restarted freely.

It serves the public email REST surface — mail listing and reading, compose / send / reply / forward, bulk operations, folders (CRUD, search, sync), tags, attachments, snooze, summary, blacklist / whitelist and shared folders (/email, /email_folder, /shared, …) — maps upstream errors onto proper HTTP status codes, and builds direct attachment download links. Endpoints owned by other services answer with a uniform HTTP 501.

⁠Quick Start

services:
  email-service:
    image: icewarptechnology/lapi-email-service:${EMAIL_SERVICE_IMAGE:-latest}
    restart: unless-stopped
    environment:
      - EMAIL_SERVICE_UPSTREAM_BASE_URL
      - EMAIL_SERVICE_TICKET_BASE_URL
      - EMAIL_SERVICE_LOGGER_LEVEL
      - EMAIL_SERVICE_LOGGER_ENV
    ports:
      - "8080:8080/tcp" # HTTP
    depends_on:
      - icewarp

# .env

EMAIL_SERVICE_UPSTREAM_BASE_URL=http://icewarp:80/mailapi
EMAIL_SERVICE_TICKET_BASE_URL=https://webmail.example.com/mailapi

EMAIL_SERVICE_LOGGER_LEVEL=info
EMAIL_SERVICE_LOGGER_ENV=production

Or as a single command:

docker run --detach --publish 8080:8080 \
  --env EMAIL_SERVICE_UPSTREAM_BASE_URL=http://icewarp:80/mailapi \
  --env EMAIL_SERVICE_TICKET_BASE_URL=https://webmail.example.com/mailapi \
  icewarptechnology/lapi-email-service

• EMAIL_SERVICE_UPSTREAM_BASE_URL must point at the Mail API of a running IceWarp server⁠. When both containers share a Docker network and the server container is named icewarp, http://icewarp:80/mailapi works out of the box.
• EMAIL_SERVICE_TICKET_BASE_URL is the Mail API base used to build attachment download links. Those links are fetched by the end client (browser / app) directly, so this must be the publicly reachable server hostname — usually not the internal address the gateway itself calls. When left empty it falls back to the upstream URL.

⁠Authentication

Every API request must carry an Authorization: Bearer <credential> header. The credential may be either an api-service wrapper JWT — the upstream token is read from its token claim, the caller identity from identityId — or the raw IceWarp (TC) token, which is forwarded upstream verbatim. The JWT is decoded locally without signature verification; token validity is enforced by the IceWarp server, not by this image. A missing or empty Bearer value is answered with HTTP 401.

⁠Environment variables

• EMAIL_SERVICE_UPSTREAM_BASE_URL - required - Base URL of the IceWarp Mail API the gateway calls
• EMAIL_SERVICE_UPSTREAM_TIMEOUT - Per-request timeout for upstream calls (default 30s)
• EMAIL_SERVICE_TICKET_BASE_URL - Client-reachable Mail API base URL used to build attachment download links; falls back to the upstream URL when empty
• EMAIL_SERVICE_SERVICE_ADDR - Listen address host:port (default :8080)
• EMAIL_SERVICE_SERVICE_TIMEOUT_READ - HTTP read timeout (default 10s)
• EMAIL_SERVICE_SERVICE_TIMEOUT_WRITE - HTTP write timeout (default 30s)
• EMAIL_SERVICE_LOGGER_LEVEL - trace/debug/info/warn/error (default info)
• EMAIL_SERVICE_LOGGER_ENV - Deployment environment label attached to log entries (default development)
• EMAIL_SERVICE_LOGGER_SENTRY_DSN - Sentry DSN; set empty to disable Sentry
• EMAIL_SERVICE_LOGGER_SENTRY_LEVEL - Minimum level forwarded to Sentry (default error)
• EMAIL_SERVICE_PROMETHEUS_ENABLED - 0/1 - Enable the Prometheus metrics endpoint (default enabled)
• EMAIL_SERVICE_PROMETHEUS_PATH - Path where metrics are exposed (default /metrics)

⁠Further configuration

Configuration is resolved in three layers, each overriding the previous one: built-in defaults, a YAML config file, then EMAIL_SERVICE_* environment variables. In most deployments the environment variables above are all you need.

There's a default configuration file stored at /etc/email-service/config.yaml. You can copy it out of the image to your home directory:

sudo docker run --rm -v ~:/cfg icewarptechnology/lapi-email-service cp /etc/email-service/config.yaml /cfg

Edit it and then run the container with the modified config mounted over the default one:

docker run --detach --publish 8080:8080 --volume ~/config.yaml:/etc/email-service/config.yaml:ro icewarptechnology/lapi-email-service

To review the configuration the container would actually use, without starting the server:

docker run --rm icewarptechnology/lapi-email-service config -c /etc/email-service/config.yaml --format yaml

⁠Ports, health and observability

• Port 8080 serves the whole HTTP surface — the public API and /metrics.
• The image ships a healthcheck that verifies the service process is alive; orchestrators can additionally probe /metrics.
• Metrics are exposed in Prometheus format at /metrics.
• Logs go to stdout, one structured entry per request with method, path, status, latency, client IP, user agent and response size. 5xx is logged at error level, 4xx at warn, everything else at info.

⁠Troubleshooting

If you encounter any issues with this image, please refer to our Knowledge Base⁠ or reach out to our Support Team⁠ for assistance.