flowmarkup:
  title: Email Notification Patterns
  version: 1
  description: Core mail patterns — plain text, HTML, attachments, and SMTP override.
  requires:
    MAIL: ["@example.com"]
    SECRET: [sendgrid_api_key]
    ENV: [MAIL_DOMAIN]

  vars:
    customer_email: customer@example.com
    manager_email: manager@example.com
    order_id: ORD-12345
    invoice_number: INV-2024-001
    company_logo: "iVBORw0KGgoAAAANSUhEUg..."
    raw_export_data: "id,name,amount"

  do:

    # Plain-text email
  - mail:
      _label_: Order confirmation
      to: =customer_email
      subject: "Order {{order_id}} confirmed"
      body: Your order has been placed successfully.
      timeout: 30s

    # HTML email with plain-text fallback
  - mail:
      _label_: Welcome email
      to: =customer_email
      subject: Welcome to our service
      body:
        text: Welcome! Thank you for signing up.
        html: <html><body><h1>Welcome!</h1><p>Thank you for signing up.</p></body></html>
      timeout: 30s

    # Attachments with inline image (CID)
  - mail:
      _label_: Invoice with inline branding
      to: [=manager_email]
      cc: ['audit@example.com']
      subject: "Invoice #{{invoice_number}}"
      body:
        html: '<html><body><img src="cid:logo"/><p>Please review the attached invoice.</p></body></html>'
        text: Please review the attached invoice.
      attachments:
      - invoice_pdf
      - data: =company_logo
        inline: true
        contentId: logo
      - data: =raw_export_data
        name: "export-{{order_id}}.csv"
        contentType: text/csv   # explicit: raw_export_data has no $type metadata
      retry: 3/5s/EXPONENTIAL
      timeout: 30s

    # SMTP override with secrets — use transactional provider for this step
  - mail:
      _label_: Transactional via SendGrid
      to: =customer_email
      from: "noreply@{{ENV.MAIL_DOMAIN}}"
      subject: Password reset
      body:
        html: <html><body><p>Click the link to reset your password.</p></body></html>
      smtp:
        host: smtp.sendgrid.net
        port: 587
        tls: STARTTLS
        auth:
          username: apikey
          password: =SECRET.sendgrid_api_key
      timeout: 30s
      retry: 3/2s/EXPONENTIAL
