Guide

Send Email from GitLab CI Pipelines

GitLab's built-in pipeline emails are coarse, and wiring an SMTP relay into CI means storing credentials that break the moment a provider tightens auth. A cleaner path: install the Nylas CLI in a job and send over API. One command emails the right people when a deploy fails, authenticated by a masked CI variable, with no SMTP host and no mail daemon. This guide adds email to a GitLab pipeline and scopes it to the failures you actually want to hear about.

Written by Caleb Geene Director, Site Reliability Engineering

Verified — CLI 3.1.16 · Gmail, Outlook · last tested June 8, 2026

Command references used in this guide: nylas email send, nylas auth config, and nylas auth whoami.

How do you send email from GitLab CI?

You send email from GitLab CI by adding a job that installs the Nylas CLI and runs nylas email send. The CLI installs from a shell script in a couple of seconds on the runner, authenticates with an API key, and sends over HTTPS — so the job needs no SMTP server, no port 587, and no mail package. One script block turns a pipeline stage into a notifier.

This sidesteps the usual CI email pain. GitLab's native notifications are limited to a few event types, and a custom SMTP integration means storing a mailbox password that breaks when a provider tightens authentication. The CLI sends over API with an API key you store as a masked variable, per GitLab's CI/CD variables documentation.

# .gitlab-ci.yml — a notify job
notify:
  stage: .post
  image: ubuntu:24.04
  before_script:
    - apt-get update && apt-get install -y curl
    - curl -fsSL https://cli.nylas.com/install.sh | bash
    - export PATH="$HOME/.config/nylas/bin:$PATH"
    - nylas auth config --api-key "$NYLAS_API_KEY"
  script:
    - nylas email send --to team@example.com
      --subject "Pipeline $CI_PIPELINE_ID finished"
      --body "Project $CI_PROJECT_NAME, ref $CI_COMMIT_REF_NAME." --yes

How do you authenticate the CLI in CI?

Authenticate with nylas auth config --api-key "$NYLAS_API_KEY", reading the key from a masked, protected CI/CD variable. This is the headless auth path — no browser, no OAuth redirect — which is exactly what a runner needs. Store the key in Settings → CI/CD → Variables, mark it Masked and Protected, and it never appears in job logs.

Treat the key like any deployment secret: never hard-code it in .gitlab-ci.yml, and scope it to protected branches so merge requests from forks can't read it. Confirm auth succeeded in the job with nylas auth whoami if you want a sanity check before sending. The key authorizes sending from the connected account, so rotate it if it ever leaks into a log.

How do you email only on pipeline failure?

Email only on failure by gating the job with when: on_failure or a rules clause, so it runs when an earlier stage fails and stays silent on green pipelines. That's the difference between useful alerting and inbox noise — nobody wants a “build passed” email on every commit. Put the notify job in a late stage so it sees the outcome of the build and test stages.

Enrich the message with the predefined CI variables GitLab injects — $CI_PIPELINE_URL, $CI_COMMIT_SHA, $CI_JOB_NAME — so the recipient can jump straight to the failing pipeline. A good failure email answers “what broke and where” in the subject line, with the pipeline URL one click away in the body.

notify_failure:
  stage: .post
  image: ubuntu:24.04
  when: on_failure          # only when an earlier stage failed
  before_script:
    - apt-get update && apt-get install -y curl
    - curl -fsSL https://cli.nylas.com/install.sh | bash
    - export PATH="$HOME/.config/nylas/bin:$PATH"
    - nylas auth config --api-key "$NYLAS_API_KEY"
  script:
    - nylas email send --to oncall@example.com
      --subject "FAILED: $CI_PROJECT_NAME pipeline $CI_PIPELINE_ID"
      --body "Ref $CI_COMMIT_REF_NAME ($CI_COMMIT_SHA). See $CI_PIPELINE_URL" --yes

Next steps