Email escalation allows you to re-send function calls or human contacts with increased urgency when you haven’t received a response within an acceptable timeframe. This is essential for time-sensitive operations that require human oversight.

​
When to Use Email Escalation

  • Time-critical approvals: When a function call approval is blocking critical business operations
  • No response received: When the initial contact hasn’t responded within your SLA
  • Different stakeholder needed: When you need to involve higher-level decision makers
  • Channel change required: When you need to send to a different email address for urgency

​
Types of Email Escalation

​
Basic Escalation

Add additional email recipients to the existing email channel while keeping the same contact method and subject line.

hl.escalate_email_function_call(
    call_id=call.call_id,
    escalation=Escalation(
        escalation_msg="Please review - this approval is blocking deployment",
        additional_recipients=[
            EmailRecipient(
                address="manager@company.com",
                field="cc"
            )
        ]
    )
)

​
Channel-Based Escalation

Send the escalation to a completely different email address, with optional custom subject line and recipients.

hl.escalate_email_function_call(
    call_id=call.call_id,
    escalation=Escalation(
        escalation_msg="URGENT: Production deployment blocked - need immediate approval",
        channel=ContactChannel(
            email=EmailContactChannel(
                address="ceo@company.com",
                experimental_subject_line="🚨 URGENT: Production Approval Required",
                additional_recipients=[
                    EmailRecipient(address="cto@company.com", field="cc")
                ]
            )
        )
    )
)

​
Escalation Patterns

​
Progressive Escalation

Start with adding recipients, then escalate to different email addresses:

# First escalation: Add team members
hl.escalate_email_function_call(
    call_id=call.call_id,
    escalation=Escalation(
        escalation_msg="Needs review - please take a look",
        additional_recipients=[
            EmailRecipient(address="team-lead@company.com", field="to")
        ]
    )
)

# Wait for response...
time.sleep(300)  # 5 minutes

# Second escalation: Different email with urgency
hl.escalate_email_function_call(
    call_id=call.call_id,
    escalation=Escalation(
        escalation_msg="URGENT: Still no response - escalating to management",
        channel=ContactChannel(
            email=EmailContactChannel(
                address="director@company.com",
                experimental_subject_line="🚨 URGENT: Approval Required"
            )
        )
    )
)

​
No-Channel-to-Channel Escalation

Create function calls without email channels (using project defaults), then escalate with specific email addresses:

# Create without specific email channel
call = hl.create_function_call(
    spec=FunctionCallSpec(
        fn="delete_production_data",
        kwargs={"table": "users"}
        # No channel - uses project defaults or CLI
    )
)

# Later escalate with specific high-priority email
hl.escalate_email_function_call(
    call_id=call.call_id,
    escalation=Escalation(
        escalation_msg="CRITICAL: Production data deletion requires executive approval",
        channel=ContactChannel(
            email=EmailContactChannel(
                address="ceo@company.com",
                experimental_subject_line="⚠️ CRITICAL: Production Data Deletion"
            )
        )
    )
)

​
API Methods

# Function Call Email Escalation
hl.escalate_email_function_call(call_id=call_id, escalation=escalation)

# Human Contact Email Escalation
hl.escalate_email_human_contact(call_id=call_id, escalation=escalation)

​
Escalation Object

interface Escalation {
  escalation_msg: string; // Required: Reason for escalation
  additional_recipients?: EmailRecipient[]; // Optional: Extra email recipients
  channel?: ContactChannel; // Optional: New email channel override to escalate to
}

​
Channel Priority and Recipient Handling

When both the original call and escalation have email channels:

  1. Escalation channel provided: Uses the escalation email channel as the primary recipient
  2. No escalation channel: Uses the original function call/contact email channel as primary
  3. Recipients merging: The system combines recipients from multiple sources:
    • Original channel’s additional_recipients
    • Escalation’s additional_recipients
    • Escalation channel’s additional_recipients (if channel override provided)

​
Example Implementation

See the complete email escalation examples: