AGENTS.md Template: Email Delivery Architecture

Overview

The template defines an operating model where a planner designs the delivery plan, one or more agents execute the plan, and a supervisor or orchestrator coordinates handoffs, preserves the source of truth, and validates outcomes. It also specifies how to scale from a single agent to multi-agent workflows while keeping a clear boundary between planning, execution, testing, and governance.

When to Use This AGENTS.md Template

• When building or evolving an email delivery architecture that handles marketing and transactional emails.
• When you need explicit agent handoffs between planner, implementer, tester, and reviewer.
• When you require tool governance over SMTP credentials, API keys, and secrets with restricted access.
• When security, compliance, and post-delivery validation matter for your workflow.
• When you want a copyable template that can be pasted into an AGENTS.md file to enforce operating context.

Copyable AGENTS.md Template

# AGENTS.md

Project role: Email Infra Lead
Agent roster and responsibilities:
- PlannerAgent: designs delivery plan, sequencing, and success criteria.
- DeliverAgent: executes SMTP/API-based delivery, handles templating, and payload composition.
- TemplateAgent: stores and reuses email templates; enforces templating rules.
- BounceAgent: captures bounce events, parses diagnostics, and updates reputation metrics.
- ComplianceAgent: ensures DKIM/SPF alignment, rate limits, and privacy controls.
- ReviewerAgent: reviews changes before deployment and ensures risk controls.

Supervisor or orchestrator behavior:
- The PlannerAgent acts as the orchestrator, emitting tasks to other agents and integrating results.
- Agents communicate results, errors, and status back to the PlannerAgent and the central memory store.
- Handoff rules:
  - Planner to DeliverAgent when delivery plan is ready for execution.
  - DeliverAgent to BounceAgent and ComplianceAgent for validation checks during/after delivery.
  - After execution, results go to ReviewerAgent for approval and to data store for analytics.

Context, memory, and source-of-truth rules:
- All decisions must reference a single source of truth: delivery_config.json, templates.json, and event logs stored in the memory store.
- Memory is scoped per delivery cycle and can be purged after archival.
- Source-of-truth: templates, policy, and configuration files are read-only for agents except designated editors.

Tool access and permission rules:
- Access to SMTP credentials, API keys, and secrets is restricted to DeliverAgent and ComplianceAgent via a secrets vault.
- All actions are auditable; use of external services requires approval gates and logging.

Architecture rules:
- Use a modular pipeline: planning, templating, delivery, bounce handling, and validation.
- Each agent has a defined input/output schema and strictly typed contracts.

File structure rules:
- Place delivery_config.json, templates.json, and policy.json at the repo root under config/.
- Store email templates under templates/.
- Store logs and analytics under data/.

Data, API, or integration rules:
- All API calls must go through a central gateway with rate limiting.
- Delivery results must include status, message_id, and timestamp.

Validation rules:
- Validate email format, headers, and required fields before sending.
- Validate DKIM/SPF alignment and domain reputation before delivery.
- Validate success criteria: status OK, delivery_id non-empty, and event logs captured.

Security rules:
- Secrets must be stored in a vault; no plaintext secrets in code.
- Access is role-based and time-bound.
- All endpoints require authentication and TLS.

Testing rules:
- Unit tests for template rendering and header construction.
- Integration tests for delivery path with mock SMTP provider.
- End-to-end tests for bounce handling and retries.

Deployment rules:
- Require a green CI suite and a formal review before deployment.
- Canary deployments with synthetic delivery events and alerting on failures.

Human review and escalation rules:
- All changes to the email delivery pipeline must pass human review in PRs.
- Escalate to security engineer if secrets or external endpoints are touched.

Failure handling and rollback rules:
- If delivery fails beyond retry policy, revert to previous configuration and alert stakeholders.
- Maintain an audit log of failed deliveries and rollbacks.

Things Agents must not do:
- Do not bypass secrets vault or expose credentials.
- Do not modify production config without review.
- Do not perform unsupervised rollouts.

Recommended Agent Operating Model

Recommended Project Structure

email-delivery-architecture/
  orchestrator/
  planner/
  implementer/
  tester/
  reviewer/
  researcher/
  domain-specialist/
  templates/
  configs/
  pipelines/
  data/
  docs/
  tests/

Core Operating Principles

• Single source of truth and immutable configuration.
• Idempotent delivery attempts and deterministic outcomes.
• Clear ownership and explicit handoffs.
• Auditable decisions with full traceability.
• Secure by default with least privilege.

Agent Handoff and Collaboration Rules

• Planner to Implementer: handoff plan and contracts.
• Implementer to Reviewer: deliver and request approval.
• Researcher to Domain Specialist: validate domain-specific constraints.
• Domain Specialist to Planner: policy updates.
• Handoff timing rules, error propagation, and delta reporting are required for all transitions.

Tool Governance and Permission Rules

• Tools: SMTP gateway, email templates service, and analytics endpoint via authenticated gateway.
• Secrets vault access restricted to specific roles.
• All tool calls are logged and auditable.
• No direct production system edits without approval gates.

Code Construction Rules

• Use typed interfaces for message and event payloads.
• Validate templates before rendering.
• Avoid global mutable state.
• Prefer functional style for transformations.

Security and Production Rules

• Secrets management, TLS, and domain authentication.
• Production changes require review and canary rollout.
• Rollback with audit trails.

Testing Checklist

• Unit tests for template rendering.
• Integration tests with mock SMTP.
• End-to-end tests for retries and bounce handling.
• Monitoring and health checks.

Common Mistakes to Avoid

• Bypassing secrets vault.
• Skipping review.
• Ignoring bounce handling.
• Not validating DKIM/SPF.
• Overly complex flows.

Related implementation resources: AI Use Case for Rental Applications and Document Checks and AI Use Case for Travel Bloggers Using Google Analytics To See Which Destination Guides Generate The Longest Read Times.

FAQ

What is the purpose of this AGENTS.md Template for email delivery architecture?

This AGENTS.md Template defines roles, rules, and handoffs for building a reliable email delivery system using AI coding agents and multi-agent orchestration.

How does multi-agent orchestration improve email delivery reliability?

Multiple agents coordinate planning, templating, delivery, and validation to reduce single points of failure and enable safer rollouts.

What are the key handoff rules between planner and implementer?

The planner generates a concrete plan; the implementer executes with strict contracts and reports back with status and results to the planner.

How is security managed in this template?

Secrets are stored in a vault, access is role-based, and all inter-agent communications occur over TLS with auditable logs.

How do you validate changes before deployment?

Validation includes unit tests, integration tests with mock services, end-to-end tests for risk controls, and a human-reviewed PR before production deployment.