Using in CI/CD

MailCue runs as a service in automated testing pipelines.

GitHub Actions service

# GitHub Actions example
services:
  mailcue:
    image: ghcr.io/olib-ai/mailcue
    ports:
      - 8088:80
      - 25:25
      - 143:143

steps:
  - name: Wait for MailCue
    run: |
      until curl -sf http://localhost:8088/api/v1/health; do sleep 1; done

  - name: Run email tests
    run: npm test
    env:
      SMTP_HOST: localhost
      SMTP_PORT: 25
      MAILCUE_API: http://localhost:8088/api/v1

API keys for non-interactive auth

Use API keys for non-interactive authentication:

# Create an API key
TOKEN=$(curl -s -X POST http://localhost:8088/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"mailcue"}' | jq -r .access_token)

API_KEY=$(curl -s -X POST http://localhost:8088/api/v1/auth/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-pipeline"}' | jq -r .key)

# Use the API key in subsequent requests
curl -H "X-API-Key: $API_KEY" http://localhost:8088/api/v1/emails?mailbox=admin@mailcue.local

Deliverability release gates

Create a mailbox with purpose: "deliverability", send the release candidate email to it, then score the received UID. Persisted policies can require a minimum score, block warning or failure states, require named checks, and limit regression from the selected baseline.

const report = await mailcue.emails.scoreDeliverability(uid, {
  mailbox: 'delivery-ci@example.com',
});

const policy = await mailcue.deliverability.createPolicy({
  name: 'Release email gate',
  mailbox: 'delivery-ci@example.com',
  minimumScore: 90,
  maximumRegression: 3,
  failOnStatuses: ['fail'],
  requiredCheckIds: ['spf', 'dkim', 'dmarc'],
  requiredCapabilities: ['local_analysis'],
});

const evaluation = await mailcue.deliverability.evaluatePolicy(policy.id, report.reportId!);
if (!evaluation.passed) process.exit(1);

Network, visual, placement, preview, and AI-assisted checks are separate explicit runs. Require those capabilities in a policy only when the CI deployment is configured to provide them. The base score remains deterministic and does not depend on an external AI response.

CI Platform Examples

Ready-to-use configuration files for popular CI/CD platforms:

Platform Example file
GitHub Actions examples/ci/github-actions.yml
GitLab CI examples/ci/gitlab-ci.yml
CircleCI examples/ci/circleci.yml
Jenkins examples/ci/Jenkinsfile
Bitbucket Pipelines examples/ci/bitbucket-pipelines.yml

Each example includes the full pattern: health check wait, authentication, API key creation, email injection, and verification.

See the main README for the rest of the documentation.