GitHub Action

The Digidai/mails-agent-action GitHub Action installs mails-agent into your CI/CD pipeline, configures authentication, and verifies the setup. Use it to send email notifications from workflows or run automated tests that involve email.

Quick Start

- uses: Digidai/mails-agent-action@v1
  with:
    api-key: ${{ secrets.MAILS_API_KEY }}

Inputs

InputRequiredDefaultDescription
api-keyYes-Your mails-agent API key. Store this as a GitHub secret.
versionNolatestSpecific version of mails-agent to install (e.g., 1.2.0).

What the Action Does

  1. Installs mails-agent -- runs npm install -g mails-agent (or the specified version)
  2. Configures the API key -- sets the MAILS_API_KEY environment variable for all subsequent steps
  3. Verifies the setup -- runs mails doctor to confirm the CLI can authenticate and reach the API

After the action completes, the mails CLI is available in all subsequent steps of the job.

Example Workflows

Send a notification on deploy

name: Deploy and Notify
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy
        run: ./deploy.sh

      - name: Setup mails-agent
        uses: Digidai/mails-agent-action@v1
        with:
          api-key: ${{ secrets.MAILS_API_KEY }}

      - name: Send deploy notification
        run: |
          mails send \
            --to [email protected] \
            --subject "Deploy completed: ${{ github.sha }}" \
            --body "Branch ${{ github.ref_name }} deployed successfully at $(date -u)."

E2E test with email verification

name: E2E Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup mails-agent
        uses: Digidai/mails-agent-action@v1
        with:
          api-key: ${{ secrets.MAILS_API_KEY }}

      - name: Run signup test
        run: |
          # Trigger signup with the agent's email address
          curl -X POST https://your-app.com/signup \
            -d '{"email": "[email protected]"}'

          # Wait for the verification code
          CODE=$(mails code --to [email protected] --timeout 60)

          # Complete the verification
          curl -X POST https://your-app.com/verify \
            -d "{\"code\": \"$CODE\"}"

          echo "Signup verified with code: $CODE"

Send test results via email

name: Test Suite
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run tests
        id: tests
        run: npm test 2>&1 | tee test-output.txt
        continue-on-error: true

      - name: Setup mails-agent
        uses: Digidai/mails-agent-action@v1
        with:
          api-key: ${{ secrets.MAILS_API_KEY }}

      - name: Email test results
        if: always()
        run: |
          STATUS="${{ steps.tests.outcome }}"
          mails send \
            --to [email protected] \
            --subject "Tests $STATUS: ${{ github.repository }}@${{ github.sha }}" \
            --body "$(cat test-output.txt)"

Pin a specific version

- uses: Digidai/mails-agent-action@v1
  with:
    api-key: ${{ secrets.MAILS_API_KEY }}
    version: "1.2.0"

Use Cases

Storing the API Key

Never put your API key directly in the workflow file. Store it as a GitHub repository secret:

  1. Go to your repository Settings > Secrets and variables > Actions
  2. Click "New repository secret"
  3. Name: MAILS_API_KEY
  4. Value: your mails-agent API key
  5. Reference it as ${{ secrets.MAILS_API_KEY }} in the workflow

Troubleshooting

If mails doctor fails during setup: