이메일 알림

이메일 알림 (Email Notifications)

특정 이벤트에 대해 LiteLLM 프록시 사용자에게 이메일을 보내요.

출처: 문서

본문

개요 (Overview)

카테고리 세부
지원되는 이벤트 • LiteLLM 프록시에 사용자로 추가됨
• 사용자용 프록시 API 키 생성
• 사용자용 프록시 API 키 회전
• 가상 키가 예산에 근접하거나 초과
지원되는 이메일 통합 • Resend API
• SendGrid API
• SMTP

사용법 (Usage)

1. 이메일 통합 구성

SMTP

SMTP 자격 증명을 얻어 설정하세요.

proxy_config.yaml:

litellm_settings:
  callbacks: ["smtp_email"]

프록시 환경에 다음을 추가하세요:

SMTP_HOST="smtp.resend.com"
SMTP_TLS="True"
SMTP_PORT="587"
SMTP_USERNAME="resend"
SMTP_SENDER_EMAIL="[email protected]"
SMTP_PASSWORD="xxxxx"

Resend API

litellm_settings 아래의 프록시 config.yaml에 resend_email을 추가하세요. 다음 환경 변수를 설정하세요:

RESEND_API_KEY="re_1234"

proxy_config.yaml:

litellm_settings:
  callbacks: ["resend_email"]

SendGrid API

litellm_settings 아래의 프록시 config.yaml에 sendgrid_email을 추가하세요. 다음 환경 변수를 설정하세요:

SENDGRID_API_KEY="SG.1234"
SENDGRID_SENDER_EMAIL="[email protected]"

proxy_config.yaml:

litellm_settings:
  callbacks: ["sendgrid_email"]

2. 새 사용자 만들기

LiteLLM 프록시 UI에서 users > create a new user로 가세요.

새 사용자를 만든 후, 사용자를 만들 때 지정한 이메일로 이메일 초대를 받게 돼요.

3. 예산 알림 구성 (선택) (Configure Budget Alerts)

프록시 구성의 alerting 목록에 "email"을 추가해 예산 알림 이메일을 활성화하세요:

proxy_config.yaml:

general_settings:
  alerting: ["email"]

예산 알림 유형 (Budget Alert Types):

  • 소프트 예산 알림 (Soft Budget Alerts): 키가 소프트 예산 한도를 초과하면 자동으로 트리거돼요. 이 알림은 임계값에 도달하기 전에 지출을 모니터링하는 데 도움을 줘요.
  • 최대 예산 알림 (Max Budget Alerts): 키가 최대 예산의 지정된 백분율(기본: 80%)에 도달하면 자동으로 트리거돼요. 예산 소진에 근접하고 있음을 경고해요.

두 알림 유형 모두 스팸을 방지하기 위해 24시간마다 최대 한 통의 이메일을 보내요.

키별 임계값과 수신자 (Per-key thresholds and recipients)

기본적으로 최대 예산 알림은 하나의 임계값에서 발동하고 키를 소유한 사용자의 이메일로만 가므로, 소유자 이메일이 없는 키는 아무것도 보내지 않아요. 자체 임계값을 선택하고 추가 인원에게 알리려면 키의 메타데이터에 max_budget_alert_emails를 설정하세요. 각 항목은 지출이 그 백분율을 넘으면 알림 받을 수신자들에게 그 키의 max_budget의 백분율을 매핑해요.

curl -X POST 'http://0.0.0.0:4000/key/generate' \
  -H "Authorization: Bearer ***" \
  -H 'Content-Type: application/json' \
  -d '{
    "max_budget": 100,
    "metadata": {
      "max_budget_alert_emails": {
        "50": ["[email protected]"],
        "75": ["[email protected]", "[email protected]"],
        "100": ["[email protected]"]
      }
    }
  }'

위 키로 지출이 $50면 소유자에게, $75면 소유자와 finance에게, $100면 on-call에게 이메일이 가요. 수신자는 목록 또는 쉼표 구분 문자열일 수 있으며, 키 소유자의 이메일은 구성한 사람과 함께 항상 포함돼요. 각 임계값은 키당 EMAIL_BUDGET_ALERT_TTL마다 최대 한 통의 이메일을 보내요. 100% 임계값은 알림 검사가 요청이 거부되기 전에 실행되므로, 예산을 소진하는 요청에도 여전히 발동해요.

키에 max_budget_alert_emails를 구성하면 그 키의 기본 80% 알림을 대체해요. 기존 키의 임계값을 바꾸려면 같은 메타데이터 블록을 /key/update로 보내세요.

이에 대한 UI 필드는 아직 없으므로 /key/generate 또는 /key/update로 설정하세요.

모든 키의 기본 임계값 (Default thresholds for every key)

default_key_max_budget_alert_emails를 설정해 모든 키에 기준선을 적용하세요. 키별 항목은 한 번에 하나의 임계값씩 전역 콘피그와 병합되므로, 키는 임계값에 대한 전역 수신자를 상속하고 그것을 덮어쓰는 대신 자체 것을 위에 추가해요.

proxy_config.yaml:

general_settings:
  alerting: ["email"]
litellm_settings:
  default_key_max_budget_alert_emails:
    "80": ["[email protected]"]

구성 옵션 (Configuration Options)

다음 환경 변수로 예산 알림 동작을 사용자 지정하세요:

.env:

# Percentage of max budget that triggers alerts (as decimal: 0.8 = 80%)
# Only applies to keys without max_budget_alert_emails configured
EMAIL_BUDGET_ALERT_MAX_SPEND_ALERT_PERCENTAGE=0.8
# Time-to-live for alert deduplication in seconds (default: 24 hours)
EMAIL_BUDGET_ALERT_TTL=86400

이메일 템플릿 (Email Templates)

1. LiteLLM 프록시에 사용자로 추가됨 (User added as a user on LiteLLM Proxy)

이 이메일은 LiteLLM 프록시에서 새 사용자를 만들 때 전송돼요.

이벤트 트리거 방법: LiteLLM 프록시 UI에서 Users > Create User > 사용자 이메일 주소 입력 > Create User.

2. 사용자용 프록시 API 키 생성됨 (Proxy API Key created for user)

이 이메일은 LiteLLM 프록시에서 사용자용 새 API 키를 만들 때 전송돼요.

이벤트 트리거 방법: LiteLLM 프록시 UI에서 Virtual Keys > Create API Key > User ID 선택.

Create Key 모달에서 Advanced Settings > Send Email을 True로 설정.

3. 사용자용 프록시 API 키 회전됨 (Proxy API Key Rotated for User)

이 이메일은 LiteLLM 프록시에서 사용자용 API 키를 회전할 때 전송돼요.

이벤트 트리거 방법: LiteLLM 프록시 UI에서 Virtual Keys > 키 클릭 > "Regenerate Key" 클릭.

info

키에 user_id가 연결되어 있는지 확인하세요. 키 생성 시 설정됐을 거예요.

키를 재생성한 후 사용자는 다음이 포함된 이메일 알림을 받아요:

  • 회전에 대한 보안 중심 메시지
  • 새 API 키 (또는 EMAIL_INCLUDE_API_KEY=false면 플레이스홀더)
  • 애플리케이션 업데이트 지침
  • 보안 모범 사례

이메일 사용자 지정 (Email Customization)

Enterprise 기능

이메일 브랜딩 사용자 지정에는 LiteLLM Enterprise 라이선스가 필요해요. 무료 30일 체험판을 시작하거나 데모를 예약하세요. Enterprise에 포함된 것 보기.

LiteLLM은 이메일 알림의 다양한 측면을 사용자 지정할 수 있게 해줘요. 아래는 사용자 지정 가능한 모든 필드의 완전한 참조예요:

필드 환경 변수 타입 기본값 예시 설명
로고 URL EMAIL_LOGO_URL string LiteLLM 로고 "https://your-company.com/logo.png" 회사 로고의 공개 URL
지원 연락처 EMAIL_SUPPORT_CONTACT string [email protected] "[email protected]" 사용자 지원 이메일 주소
이메일 서명 EMAIL_SIGNATURE string (HTML) 표준 LiteLLM 푸터 "

Best regards,
Your Team

Visit us

"		 모든 이메일의 HTML 형식 푸터
초대 제목 EMAIL_SUBJECT_INVITATION string "LiteLLM: New User Invitation" "Welcome to Your Company!" 초대 이메일 제목줄
키 생성 제목 EMAIL_SUBJECT_KEY_CREATED string "LiteLLM: API Key Created" "Your New API Key is Ready" 키 생성 이메일 제목줄
키 회전 제목 EMAIL_SUBJECT_KEY_ROTATED string "LiteLLM: API Key Rotated" "Your API Key Has Been Rotated" 키 회전 이메일 제목줄
API 키 포함 EMAIL_INCLUDE_API_KEY boolean true "false" 이메일에 실제 API 키 포함 여부 (보안 강화를 위해 false로 설정)
프록시 Base URL PROXY_BASE_URL string http://0.0.0.0:4000 "https://proxy.your-company.com" LiteLLM 프록시의 Base URL (이메일 링크에 사용)

이메일 서명의 HTML 지원 (HTML Support in Email Signature)

EMAIL_SIGNATURE 필드는 풍부하고 브랜드화된 이메일 푸터를 위한 HTML 포맷팅을 지원해요. 포함할 수 있는 예시:

<p>Best regards,<br/>The LiteLLM Team</p>
<p>
  <a href='https://docs.litellm.ai'>Documentation</a> |
  <a href='https://github.com/BerriAI/litellm'>GitHub</a>
</p>
<p style='font-size: 12px; color: #666;'>
  This is an automated message from LiteLLM Proxy
</p>

지원되는 HTML 기능:

  • 텍스트 포맷팅 (굵게, 기울임 등)
  • 줄바꿈 (<br/>)
  • 링크 (<a href='...'>)
  • 문단 (<p>)
  • 기본 인라인 스타일링
  • 회사 정보 및 소셜 미디어 링크
  • 법적 면책 조항 또는 서비스 약관 링크

환경 변수 (Environment Variables)

다음 환경 변수로 이메일의 측면을 사용자 지정할 수 있어요:

# Email Branding
EMAIL_LOGO_URL="https://your-company.com/logo.png"  # Custom logo URL
EMAIL_SUPPORT_CONTACT="[email protected]"     # Support contact email
EMAIL_SIGNATURE="<p>Best regards,<br/>Your Company Team</p><p><a href='https://your-company.com'>Visit our website</a></p>"  # Custom HTML footer/signature

# Email Subject Lines
EMAIL_SUBJECT_INVITATION="Welcome to Your Company!"  # Subject for invitation emails
EMAIL_SUBJECT_KEY_CREATED="Your API Key is Ready"    # Subject for key creation emails
EMAIL_SUBJECT_KEY_ROTATED="Your API Key Has Been Rotated"  # Subject for key rotation emails

# Security Settings
EMAIL_INCLUDE_API_KEY="false"  # Set to false to hide API keys in emails (default: true)

# Proxy Configuration
PROXY_BASE_URL="https://proxy.your-company.com"      # Base URL for the LiteLLM Proxy (used in email links)

보안: 이메일에서 API 키 숨기기 (Security: Hiding API Keys in Emails)

보안 강화를 위해 LiteLLM이 이메일 알림에 실제 API 키를 포함하지 않도록 구성할 수 있어요. 다음 경우에 유용해요:

  • 이메일 가로채기를 통한 키 노출 위험을 줄이고 싶을 때
  • 보안 정책이 키를 보안 대시보드에서만 검색하도록 요구할 때
  • 이메일 전달 또는 저장 보안이 걱정될 때

비활성화하면 이메일에 실제 API 키 대신 [Key hidden for security - retrieve from dashboard]가 표시돼요.

구성:

# Hide API keys in emails (enhanced security)
EMAIL_INCLUDE_API_KEY="false"
# Include API keys in emails (default behavior)
EMAIL_INCLUDE_API_KEY="true"  # or omit this variable

동작:

설정 키 생성 이메일 키 회전 이메일
true (기본) 실제 sk-xxxxx 키 표시 실제 sk-xxxxx 키 표시
false 플레이스홀더 메시지 표시 플레이스홀더 메시지 표시

사용자는 항상 LiteLLM 프록시 대시보드에서 키를 검색할 수 있어요.

이메일 서명의 HTML 지원 (HTML Support in Email Signature)

EMAIL_SIGNATURE 환경 변수는 HTML 포맷팅을 지원해 풍부하고 브랜드화된 이메일 푸터를 만들 수 있어요. 포함할 수 있는 것:

  • 텍스트 포맷팅 (굵게, 기울임 등)
  • <br/>로 줄바꿈
  • <a href='...'>로 링크
  • <p>로 문단
  • 회사 정보 및 소셜 미디어 링크
  • 법적 면책 조항 또는 서비스 약관 링크

예시 HTML 서명:

<p>Best regards,<br/>The LiteLLM Team</p>
<p>
  <a href='https://docs.litellm.ai'>Documentation</a> |
  <a href='https://github.com/BerriAI/litellm'>GitHub</a>
</p>
<p style='font-size: 12px; color: #666;'>
  This is an automated message from LiteLLM Proxy
</p>

기본 템플릿 (Default Templates)

환경 변수가 설정되지 않으면 LiteLLM은 기본 템플릿을 사용해요:

  • 기본 로고: LiteLLM 로고
  • 기본 지원 연락처: [email protected]
  • 기본 서명: 표준 LiteLLM 푸터
  • 기본 제목: "LiteLLM: {event_message}" (실제 이벤트 메시지로 교체)

템플릿 변수 (Template Variables)

커스텀 이메일 제목을 설정할 때 유일하게 지원되는 템플릿 변수는 {event_message}이며, 이것은 이벤트 메시지로 교체돼요 (예: "Welcome to LiteLLM Proxy" 또는 "API Key Created"). {company_name} 같은 다른 플레이스홀더는 이메일이 빌드될 때 KeyError를 일으키고 이메일이 전송되지 않아요. 그 외에는 일반 텍스트를 사용하세요:

# Examples of template variable usage
EMAIL_SUBJECT_INVITATION="Welcome to Acme! {event_message}"
EMAIL_SUBJECT_KEY_CREATED="Your Acme API Key"

FAQ

이메일 링크에 "http://0.0.0.0:4000"이 보이는 이유는?

PROXY_BASE_URL 환경 변수가 이메일 링크를 구성하는 데 사용돼요. 로컬 환경에서 LiteLLM 프록시를 사용하면 이메일 링크에 "http://0.0.0.0:4000"이 보여요.

프로덕션 환경에서 LiteLLM 프록시를 사용하면 LiteLLM 프록시의 실제 base URL이 보여요.

PROXY_BASE_URL 환경 변수를 LiteLLM 프록시의 실제 base URL로 설정할 수 있어요.

PROXY_BASE_URL="https://proxy.your-company.com"