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.