Letterflow는 단계를 하나의 전송 경로로 연결합니다.
Letterflow는 API 요청, 값, 판단을 비동기 실행으로 연결합니다. 시각적 빌더에서 구성 요소를 배치하고 연결하여 이전 단계의 결과를 다음 단계로 전달하세요.
초안 작성, 검증, 배달
미완성 그래프를 초안으로 저장할 수 있습니다. Validate를 눌러 필수 필드, 표현식, 현재 의존성을 확인하세요. 경고는 해당 컴포넌트를 표시하며 준비될 때까지 Run을 사용할 수 없습니다. 편집하면 이전 검증 결과가 지워집니다.
그래프와 Value/Condition 결과를 저장할 Coordinator 지역을 선택하세요. Tinkerer에서는 모든 Letter가 해당 지역을 사용합니다. 유료 요금제는 여러 지역에서 Letter를 실행할 수 있습니다. 각 Letter에서 지역과 배달 정책을 선택하세요.
Letterflow의 동작 방식
Letterflow는 방향 그래프입니다. Start에서 실행이 시작되고 각 경로가 다음 작업을 결정합니다. 각 컴포넌트의 결과는 Step ID로 참조할 수 있어 인증, 데이터 준비, 분기, 후속 요청에 유용합니다.
시각적 캔버스에서 만들기
컴포넌트 추가
팔레트 컴포넌트를 클릭하거나 탭하면 다음 위치에 배치됩니다. 정확한 위치에 놓으려면 팔레트에서 드래그하세요.
포트 연결
컴포넌트 아래쪽 출력 포트를 다음 컴포넌트 위쪽 입력 포트에 연결하세요. 터치 기기에서는 출력 포트를 먼저 탭한 다음 대상 입력 포트를 탭하세요.
이동하기
캔버스는 위에서 아래로 흐릅니다. 빈 공간을 드래그하면 캔버스가 이동하고 컴포넌트 본체를 드래그하면 해당 컴포넌트만 재배치됩니다.
설정
새 컴포넌트는 자동으로 선택됩니다. 나중에 컴포넌트를 선택해도 Properties Panel에서 설정을 편집할 수 있습니다.
사용 가능한 컴포넌트
시작
필수 시작 지점입니다. 설정이 필요 없으며 실행은 항상 여기서 시작합니다.
편지
구성 요소 안에서 설정한 요청을 실행합니다. 상태 코드, 헤더, 본문, 파싱된 JSON을 이후 단계에서 사용할 수 있습니다.
이메일
이전 단계의 값을 사용해 수신자 한 명에게 알림 한 통을 보냅니다. 여러 이메일 컴포넌트를 추가할 수 있으며 실행 경로에서 도달한 단계만 할당량을 사용합니다. 유료 요금제에서 사용할 수 있습니다.
밸류
리터럴, 변수 및 보간 함수가 포함된 텍스트를 평가합니다. 이후 컴포넌트는 단계 ID로 출력을 참조할 수 있습니다. 마지막에 배치하면 레터박스에 단일 값이 저장됩니다.
조건
조건문을 평가하여 true이면 Output 1, false이면 Output 2로 실행을 보냅니다.
Letter 컴포넌트 설정
- 요청을 설정하세요.
컴포넌트에서 메서드, URL, 헤더, 본문을 직접 설정하세요. 이 필드들은 이전 단계의 값을 사용할 수 있습니다.
- Step ID 지정하기
login이나 fetch_data처럼 짧고 고유한 식별자를 사용하세요. 이후 컴포넌트는 이 이름으로 응답을 참조할 수 있습니다.
- 리디렉션 따라가기
구성 요소의 최대 리디렉션 횟수를 선택하세요. 도달한 각 홉은 시간당 사용량에 포함됩니다.
- 플로우 세션 사용
로그인 Letter와 해당 쿠키가 필요한 후속 HTTP/HTTPS Letter에서 플로우 세션 사용을 활성화하세요. 선택한 Letter는 쿠키를 전송하고 저장하며, 선택하지 않은 Letter는 세션을 변경하지 않습니다. 실행할 때마다 빈 세션으로 시작합니다.
이메일 컴포넌트 설정
To, 제목, 본문과 선택 사항인 Reply-To를 설정합니다. 네 필드 모두 이전 단계의 변수와 보간 함수를 사용할 수 있습니다. Hato가 검증된 발신 주소를 제공합니다. To와 Reply-To는 각각 하나만 지원하며 주소 목록, CC/BCC, 첨부 파일, 사용자 지정 헤더, 발신자 재정의는 지원하지 않습니다.
일반 텍스트 또는 HTML을 선택합니다. 변수 치환 후 본문은 UTF-8 64 KiB, 제목은 255바이트까지이며 인코딩된 전체 메시지는 256 KiB까지입니다. HTML 변수 값은 이스케이프되고 실행 가능한 콘텐츠와 이미지는 제거됩니다. 기본 서식, 표, 안전한 링크는 유지됩니다. HTML 이스케이프 해제는 지원하지 않습니다. Letterbox는 HTML을 실행하지 않고 소스로 표시합니다.
To: {{ lookup.json.email }} · Subject: Result {{ lookup.status_code }}
Aspiring은 월 1,000통과 최근 1시간 20통, Coder는 월 3,000통과 최근 1시간 60통을 제공합니다. 모든 플로우와 리전에서 한도를 공유하며 매월 1일 00:00 UTC에 월간 할당량이 초기화됩니다. Hub 사용량 패널에서 사용, 예약, 잔여량을 확인할 수 있습니다.
접수되었거나 결과가 불확실한 발송은 할당량에 포함됩니다. 명확히 거부된 발송의 예약은 해제되며, 입력 오류나 할당량 초과로 차단된 발송은 포함되지 않습니다. 나중에 반송되어도 사용량은 유지됩니다. 기록 삭제나 요금제 변경으로 사용량이 초기화되지 않습니다. 서비스 전체 발송 한도에 의해 차단될 수도 있습니다.
Step ID 또는 prev.output으로 success, status, error_code, error, message_id를 참조할 수 있습니다. status는 accepted, simulated, failed, unknown입니다. accepted는 공급자가 요청을 접수했다는 뜻이며 받은편지함 도착을 보장하지 않습니다. 이후 SES 배달, 반송, 신고 이벤트는 배달 기록을 갱신하지만 이미 실행된 경로는 바꾸지 않습니다. 개발 기본값은 시뮬레이션이며 SendPulse SMTP는 접수만 기록합니다.
오류 발생 시 동작 선택
이메일과 Letter에는 오류 시 중지/계속 설정이 있으며 기본값은 중지입니다. 이메일 할당량 소진, 치환된 입력 오류, 발송 실패에는 이 설정이 즉시 적용됩니다. 결과가 불확실한 발송은 자동으로 재전송하지 않습니다.
Letter에서는 HTTP 4xx, HTTP 5xx, 연결 실패(DNS, TLS, 시간 초과 포함)를 오류로 처리할지 선택할 수 있습니다. 기본적으로 모두 선택됩니다. Delivery Policy의 재시도와 리디렉션이 끝난 최종 결과로 판정합니다. 선택하지 않은 결과는 일반 출력으로 계속 진행하며 연결 실패에는 상태 코드가 없습니다. 기타 컴포넌트 오류는 오류 시 설정을 따르지만 취소와 실행 무결성 오류는 항상 중지합니다.
계속을 선택하면 실패한 단계와 오류 정보를 보존하고 일반 출력 경로로 진행합니다. 후속 조건과 이메일에서 실패 결과를 참조할 수 있습니다. 경로를 끝까지 실행하면 경고와 함께 완료됩니다. Letter에서 선택하지 않은 오류 분류는 경고에 포함되지 않습니다.
{{ fetch.error_code }} · {{ notice.status }}
밸류 컴포넌트 테스트
Input 필드는 Letterflow 출력을 정의합니다. 별도의 Test 필드는 Coordinator에서 리터럴과 정적 Value/Condition 참조를 평가합니다. Letter를 전송하거나 미리보기 결과를 저장하지 않습니다. 실제 Letter 출력은 Letterflow 실행 중에만 사용할 수 있습니다.
{{ "hello world" | upper }}
이 테스트는 HELLO WORLD를 출력합니다. 식은 최대 64 KiB이며 출력은 최대 1 MiB입니다. 평가에 실패하면 Letterflow가 중지되며 Condition의 false 결과와 구분됩니다.
표현식이나 캔버스 빌더에서 to_text, to_json, to_xml, to_header를 사용하세요. 원본은 유지됩니다. to_header는 모든 최상위 키를 사용하며 null과 중첩 객체를 포함한 전체 값을 텍스트로 변환합니다. 유형을 유지하려면 Value에서 Headers 출력을 선택하세요.
JSON 및 XML 편집
캔버스 오른쪽 위의 표현식 빌더에서 변수와 호환 함수 및 인수를 선택한 후 생성된 표현식을 복사해 붙여넣으세요. 유형 변경으로 이후 함수를 제거하기 전에 확인합니다. 초안은 이 페이지에만 유지되며 컴포넌트를 수정하지 않습니다. Value는 JSON/XML 출력을 계속 지원합니다.
Step ID와 변수 사용
캔버스의 표현식 빌더에서 변수를 선택하고 표현식을 복사해 컴포넌트 필드에 붙여넣으세요. 유형 표시는 내용을 읽지 않고 참조를 식별합니다. 다른 화면의 Directory 변경 사항은 새로고침하면 반영됩니다.
각 구성 요소는 Step ID를 키로 Letterflow 컨텍스트에 결과를 저장합니다. URL, 헤더, 본문, Email 필드, Value 입력, Condition에서 이중 중괄호로 이전 값을 참조하세요.
| 참조 대상 | 예시 | 용도 |
|---|---|---|
| 밸류 | {{ my_value }} | 평가된 텍스트를 삽입합니다. |
| Letter 상태 | {{ login.status_code }} | Condition(조건 분기)에서 응답 상태를 확인합니다. |
| Letter JSON | {{ login.json.token }} | 파싱된 JSON 값을 후속 요청에 전달합니다. |
| 직전 컴포넌트 | {{ prev.output }} | Step ID를 지정하지 않고 바로 이전 결과를 사용합니다. |
Letter의 경우 직전 컴포넌트 출력에서 응답 헤더, 요청과 응답 본문, URL, 메서드, 상태 코드도 사용할 수 있습니다.
보간 함수
보간 함수는 왼쪽 값을 변환합니다. URL, 헤더, 본문, 이메일 필드, 값 입력, 조건에서 파이프로 연결합니다. Jinja의 필터와 같은 개념입니다.
{{ login.json.token | default "no-token" | trim | urlenc }}
인수는 Grafana 방식의 공백 구분 문법을 사용합니다. 여러 인수를 사용하는 함수에서는 기본 Jinja 괄호 문법도 지원합니다.
| 함수 | 예시 | 목적 |
|---|---|---|
default | {{ value | default "fallback" }} | 값이 없거나 비어 있으면 대체 값을 반환합니다. |
upper, lower | {{ name | upper }} | 영문 대소문자를 변환합니다. |
b64enc, b64dec | {{ token | b64enc }} | UTF-8 텍스트를 Base64로 인코딩하거나 디코딩합니다. |
printf | {{ name | printf "Hello, %s" }} | printf 형식 문자열로 값을 서식화합니다. |
replace | {{ text | replace "old" "new" }} | 일치하는 모든 항목을 바꿉니다. 세 번째 인수로 바꾸는 횟수를 제한할 수 있습니다. |
urlenc, urldec | {{ value | urlenc }} | 텍스트를 URL 쿼리 형식으로 인코딩하거나 디코딩합니다. |
re_replace | {{ text | re_replace "[0-9]+" "#" }} | 정규식과 일치하는 모든 항목을 바꿉니다. |
substr | {{ text | substr 5 }}{{ text | substr 2 5 }} | 인수가 하나면 처음 n자를 유지합니다. 둘이면 시작 위치를 포함하고 끝 위치는 제외한 범위의 문자를 유지합니다. |
trim, ltrim, rtrim | {{ text | trim }} | 양쪽, 왼쪽, 오른쪽 공백을 제거합니다. |
re_exists | {{ text | re_exists "error" }} | 정규식이 일치하면 True, 아니면 False를 반환합니다. |
add | {{ value | add 1 2 -3 }} | 값에 하나 이상의 숫자(정수, 소수, 음수)를 더합니다. |
sub | {{ value | sub 5 2 }} | 값에서 하나 이상의 숫자를 뺍니다. |
mul | {{ value | mul 2 3 }} | 값에 하나 이상의 숫자를 곱합니다. |
div | {{ value | div 2 }} | 값을 하나 이상의 숫자로 나눕니다. |
mod | {{ value | mod 3 }} | 피연산자로 나눈 나머지를 반환합니다. |
round | {{ value | round "up" 2 }} | 숫자를 반올림합니다. 소수 자릿수를 지정할 수 있으며 기본값은 0입니다. |
조건과 분기
Condition에는 두 개의 출력이 있습니다. true이면 Output 1, false이면 Output 2로 계속 진행합니다. 조건은 평가 전에 텍스트로 렌더링되므로 비교 방식을 신중하게 선택하세요.
느슨한 동등 비교
숫자와 기본 확인에서는 값에 따옴표를 사용하지 마세요. 200 또는 문자열 200으로 렌더링된 상태 코드를 200 == 200으로 비교할 수 있습니다.
{{ login.status_code }} == 200
엄격한 문자열 비교
정확한 텍스트 비교에서는 양쪽을 따옴표로 감싸세요. 숫자 값과 따옴표가 있는 문자열을 섞으면 비교 결과가 false가 될 수 있습니다.
"{{ status_text }}" == "Success"
모바일 조작
| 목표 | 터치 동작 |
|---|---|
| 컴포넌트 추가하기 | 팔레트의 컴포넌트를 탭하거나 누른 채 캔버스로 드래그하세요. |
| 컴포넌트 이동하기 | 컴포넌트 본체를 누른 채 드래그하세요. 세로와 가로로 이동할 수 있습니다. 포트나 폼 컨트롤이 아닌 곳에서 시작하세요. |
| 캔버스 이동 | 빈 캔버스를 드래그하면 캔버스가 이동합니다. 컴포넌트 본체를 드래그하면 해당 컴포넌트만 이동합니다. |
| 컴포넌트 연결하기 | 출력 포트를 탭한 다음 입력 포트를 탭하세요. 유효한 입력을 선택할 때까지 활성 출력이 선택된 상태로 유지됩니다. |
| 컴포넌트 편집하기 | 컴포넌트를 탭하고 Properties Panel을 사용하세요. 새 컴포넌트를 추가하면 자동으로 열립니다. |
| 컴포넌트 삭제하기 | 컴포넌트를 선택하고 Properties Panel에서 Delete component를 누른 다음 삭제를 확인하세요. |
검증 및 실행 규칙
- 유효한 플로는 Start 컴포넌트에서 시작해야 합니다.
- Hato API는 순환, 하나의 출력에서 여러 연결, 하나의 입력으로 여러 연결을 허용하지 않습니다.
- 검증에서 순환을 거부합니다. 루프 실행은 지원하지 않습니다.
- Letterflow는 비동기로 실행되므로 작업을 모니터링하고 전송 후 우편함을 확인하세요.
- 값, 조건, 이메일의 입력과 결과는 Coordinator 리전에 보관됩니다. Letter 아티팩트는 선택한 실행 리전에 유지됩니다. 보관된 모든 실행 콘텐츠에 만료와 삭제가 적용됩니다.
- Letter 컴포넌트에는 Delivery Policy의 시간 초과, 재시도, 페이로드 크기 한도가 적용됩니다. 이메일 컴포넌트에는 별도의 메시지 크기 및 발송 한도가 적용됩니다.
분기 플로 따라 하기
- 플로를 만드세요.
대시보드에서 Create Flow를 선택하세요. Start 컴포넌트는 자동으로 배치됩니다.
- 로그인 Letter를 추가하세요.
Letter 컴포넌트를 배치하고 Start에 연결한 다음 Step ID를 login으로 설정하세요.
- Condition을 추가하세요.
login 결과를 Condition에 연결하고 상태 코드를 200과 비교하세요.
- 성공 분기 만들기
Output 1을 fetch Letter에 연결하고 login 토큰을 헤더에 전달하세요.
- 대체 분기를 만드세요.
성공한 요청의 비교가 거짓일 때 출력 2로 연결합니다. 조건에서 HTTP 또는 연결 오류를 검사하려면 Letter에서 해당 오류 분류를 해제하거나 오류 시 계속을 선택하세요.
- 저장, 검증, 실행하세요.
이름을 붙여 저장하고 Validate를 누르세요. 준비되면 실행한 다음 Letterbox에서 고정된 경로와 보관된 각 컴포넌트를 확인하세요.
템플릿 평가에는 CPU, 메모리, 실행 시간 제한이 적용됩니다. 제한을 초과하는 표현식은 구성 요소를 완료하지 않고 실패합니다. 업로드와 키 생성 권한은 한 번만 사용할 수 있으며 작업 승인에는 요청 빈도 제한이 적용됩니다.