Email Agent

The email agent sends pipeline notifications via SMTP. It is a notify-only agent — you don’t put it in a phase’s agent: field. Instead, it fires when pipeline events trigger from notify blocks or the notifications configuration.

Use the email agent when your team needs notifications outside of Slack, or when stakeholders prefer email for audit trails and formal communication.

---

Sample Phase

- name: implement
  agent: cursor
  role: developer
  notify:
      on_complete:
          agent: email
          channel: team

---

Phase Configuration

The email agent cannot be used as a workflow phase agent. It has no action field, no sources, and no target_entries. It activates exclusively through notify blocks on other phases.

Notify Block Fields

Field	Type	Required	Description
agent	string	Yes	Must be "email"
channel	string	No	Channel name from settings (defaults to "default")
subject	string	No	Email subject line

Supported events: on_complete, on_escalate, on_fail.

Channel Notation

• "email" or channel: default — routes to the default recipient list
• channel: oncall — routes to the named oncall channel

---

Settings

Configure under agents.email in settings.json (via cliq setup or cliq settings):

Key	Required	Default	Description
agents.email.smtp_host	Yes	—	SMTP server hostname
agents.email.smtp_port	No	587	SMTP server port
agents.email.username	No	—	SMTP authentication username
agents.email.password	No	—	SMTP authentication password
agents.email.tls	No	true	Enable TLS encryption
agents.email.from_address	No	—	Sender email address
agents.email.from_name	No	"cliq"	Sender display name
agents.email.channels	Yes	—	Named channel map (must include at least default)
agents.email.channels.default	Yes	—	Array of default recipient email addresses
agents.email.channels.<name>	No	—	Named recipient list

Channel Map

Channels are named groups of recipients. Every email agent configuration must include at least a default channel:

{
    "agents": {
        "email": {
            "smtp_host": "smtp.example.com",
            "smtp_port": 587,
            "username": "[email protected]",
            "password": "app-password-here",
            "tls": true,
            "from_address": "[email protected]",
            "from_name": "cliq",
            "channels": {
                "default": ["[email protected]"],
                "oncall": ["[email protected]", "[email protected]"],
                "stakeholders": ["[email protected]", "[email protected]"]
            }
        }
    }
}

The default channel is used when a notify block doesn’t specify a channel name.

---

Output

The email agent does not produce handoff envelopes. It is a fire-and-forget notification delivery mechanism with no downstream data.

---

Examples

Example: Notify on pipeline completion

Send an email to the default recipients when work finishes.

phases:
    - name: implement
      agent: cursor
      notify:
          on_complete:
              agent: email
              channel: default
              subject: "Pipeline completed successfully"

    - name: finalize
      agent: git
      action: create_pr
      depends_on: [implement]

Example: Escalation to on-call team

Alert the on-call team via email when a review gate times out or is rejected.

phases:
    - name: implement
      agent: cursor

    - name: review
      type: gate
      agent: hug
      depends_on: [implement]
      review:
          reviewer: tech-lead
          timeout: 4h
      notify:
          on_escalate:
              agent: email
              channel: oncall
              subject: "Review escalated — action required"

Example: Stakeholder reporting with multiple channels

Notify different groups based on outcome — stakeholders for success, on-call for failures.

phases:
    - name: deploy
      agent: exec
      depends_on: [review]
      commands:
          - name: deploy-prod
            run: ./scripts/deploy.sh production
            escalate_on_fail: true
      notify:
          on_complete:
              agent: email
              channel: stakeholders
              subject: "Release deployed to production"
          on_fail:
              agent: email
              channel: oncall
              subject: "URGENT: Production deployment failed"

---

Setup

1. Obtain SMTP credentials from your email provider (Gmail, SendGrid, AWS SES, etc.)
2. Configure the connection settings:

cliq settings agents.email.smtp_host smtp.example.com --global
cliq settings agents.email.smtp_port 587 --global
cliq settings agents.email.username "[email protected]" --global
echo $SMTP_PASS | cliq settings agents.email.password --stdin --global
cliq settings agents.email.from_address "[email protected]" --global
cliq settings agents.email.from_name "cliq" --global

3. Add recipient channels:

cliq settings --json agents.email.channels.default '["[email protected]"]' --global
cliq settings --json agents.email.channels.oncall '["[email protected]", "[email protected]"]' --global

4. Validate:

cliq doctor agent email

Validation

cliq doctor agent email checks:

• SMTP configuration (smtp_host, channels) is set
• At least one channel (preferably default) has valid recipients
• SMTP connection can be established

---

See Also

• Agent Overview
• Slack Agent
• Notifications