Email Notify

Overview

Send an email notification after each Codex task. Use the helper script to resolve the project name and send via SMTP.

User Preparation

1) Configure environment variables

Add the following lines to ~/.bashrc (Linux) or ~/.zshrc (macOS):

export CODEX_MACHINE_NAME="Machine-name" # e.g., Macbook
export CODEX_EMAIL_SMTP_HOST="smtp.example.com"
export CODEX_EMAIL_SMTP_PORT="587"
export CODEX_EMAIL_USERNAME="user@example.com"
export CODEX_EMAIL_PASSWORD="..."
export CODEX_EMAIL_FROM="user@example.com"
export CODEX_EMAIL_TO="recipient1@example.com,recipient2@example.com"
export CODEX_EMAIL_USE_TLS="false" # true/false, default false
export CODEX_EMAIL_USE_SSL="true" # true/false, default true

If your SMTP server does not require auth, leave CODEX_EMAIL_USERNAME and CODEX_EMAIL_PASSWORD unset. Set CODEX_EMAIL_USE_SSL to true for SMTPS (typically port 465) and CODEX_EMAIL_USE_TLS to true for STARTTLS. Do not set both CODEX_EMAIL_USE_TLS and CODEX_EMAIL_USE_SSL to true.

2) Add instruction in project AGENTS.md

For example, add this instruction to AGENTS.md:

Use skill email-notify to notify users when each agent run is finished or when any notifications would be sent to users.

Workflow

1) Provide a project name source (optional)

• To override the folder name, define a project name in AGENTS.md using one of:
  • YAML frontmatter: project_name: My Project (or name:)
  • A plain line: Project Name: My Project
• If no name is found, the script uses the project folder name.

2) Send the notification at task completion

• Generate a short task title (3-8 words).
• Pick an execution status: success, failed, partial, blocked, etc.
• Write a brief result summary; avoid secrets.

Run:

python3 ~/.codex/skills/email-notify/scripts/send_email_notification.py \
  --task-title "..." \
  --status "success" \
  --summary "..." \
  --project-name "..."

Resources

• scripts/send_email_notification.py: Send the email notification and resolve the project name.