헬퍼와 상수
클라이언트의 메서드 외에 패키지가 정의하는 것.
정적 메서드
| 메서드 | 설명 |
|---|---|
| OpenEmail::init(), OpenEmail::getClient() | 공유 클라이언트를 한 번 구성한 뒤 어디서든 사용하세요. init을 실행한 적이 없으면 getClient()가 환경에서 클라이언트를 하나 만듭니다. |
| OpenEmail::resetClient() | 공유 클라이언트를 버려 다음 getClient()가 새 클라이언트를 만들게 합니다. 테스트에서 케이스 사이에 필요한 것이 바로 이것입니다. |
| new OpenEmail(), OpenEmail::createClient() | 별도의 클라이언트입니다. 둘 다 지정하지 않은 값을 환경에서 읽습니다. |
| OpenEmail::createTempMail() | API 키를 담지 않는 일회용 받은편지함 클라이언트. |
| OpenEmail::verifyWebhookSignature() | 전달의 서명을 상수 시간으로 검사하며, 재전송 허용 창은 5분이고 toleranceSeconds:로 바꿀 수 있습니다. 디코딩된 이벤트를 반환하며, 실패하면 WebhookSignatureException을 던집니다. |
| OpenEmail::toBase64() | 문자열, 스트림 리소스, SplFileInfo, PSR-7 스트림에서 첨부 파일 바이트를 Base64로 만듭니다. |
| OpenEmail::isApiKey() | 값이 oe_live_ 또는 oe_test_ 형태인지 확인합니다. 형태 검사일 뿐, 키가 아직 유효하다는 증거는 아닙니다. |
| OpenEmail::isAccessToken() | 값이 OAuth 액세스 토큰의 형태인지 여부입니다: 1~512자이고 oe_로 시작하지 않아야 합니다. |
| OpenEmail::isSealed() | 메시지의 본문이 암호문인지 여부입니다. 두 서명 형식에서는 본문이 평문으로 도착했으므로 false입니다. |
| OpenEmail::resolveLanguage(), OpenEmail::languageByCode(), OpenEmail::isRtlLanguage() | 번들로 포함된 Languages::ALL 표를 대상으로, 언어 선택기에 필요한 조회 메서드입니다. |
| $client->close() | 클라이언트의 cURL 핸들과 그 뒤의 연결을 해제합니다. 더 이상 참조되지 않는 클라이언트는 PHP가 해제할 때 같은 일을 합니다. |
상수
TypeScript SDK가 내보내는 모든 값 집합은 OpenEmail\Constants의 final 클래스이며, 멤버마다 같은 이름의 상수가 하나씩 있으므로 WebhookEvents::EMAIL_DELIVERED는 email.delivered입니다. values()는 집합 전체를 반환하며, 외부에서 들어온 값을 확인하는 방법이기도 합니다.
use OpenEmail\Constants\ApiScopes;use OpenEmail\Constants\PageLimits;use OpenEmail\Constants\WebhookEvents; $events = WebhookEvents::values(); $scopes = [ApiScopes::EMAILS_SEND, ApiScopes::THREADS_READ]; $known = in_array('email.delivered', $events, true); echo count($events), ' ', implode(',', $scopes), ' ', PageLimits::MAX_LIMIT, ' ', $known ? 'known' : 'unknown', PHP_EOL;| 상수 | 담긴 내용 |
|---|---|
| OpenEmail::VERSION | 패키지 버전입니다. |
| ApiScopes | 키 생성 화면에서 쓸 스코프 어휘입니다. |
| WebhookEvents, WebhookSignatureHeaders | 엔드포인트가 구독할 수 있는 이벤트와, 전달 요청에 담기는 헤더 이름입니다. |
| ErrorTypes | ApiException::$type이 가질 수 있는 오류 어휘. |
| PageLimits | 대부분의 페이지 목록에서 limit:의 최댓값과 기본값인 MAX_LIMIT와 DEFAULT_LIMIT: 100과 25. 몇몇 목록은 더 많이 받으며, 각 메서드의 레퍼런스에 그렇게 적혀 있습니다. |
| RuleFields, RuleOperators, RuleActions | 규칙의 조건과 동작을 구성하는 어휘입니다. |
| MessageEncryptionFormats | 수신 처리가 식별할 수 있는 다섯 가지 봉투. 그중 셋은 봉인되어 있습니다. |
| CredentialKinds, StepUpMethods, StepUpErrorCodes | me->get과 me->ping이 설명하는 자격 증명의 종류, 인증 코드를 확인하는 방식, 그리고 인증이 실패할 때의 코드. |
| ThreadSorts, PeopleSorts, FileSorts와 그 밖의 *Sorts | 목록을 정렬할 수 있는 순서. |
| FormStatuses, BroadcastStatuses, SuppressionReasons와 그 밖의 집합 | 리소스의 필드가 가질 수 있는 값. 각 집합은 담고 있는 것의 이름을 따릅니다. |
| Languages::ALL | 번역 발송이나 미리보기가 받는 모든 언어이며, 각각의 코드, 이름, 쓰기 방향이 함께 있습니다. |
객체
응답은 디코딩된 JSON을 연관 배열로 만든 것입니다. 패키지는 답의 형태를 갖출 때만 자체 객체를 만들며, 각각은 OpenEmail\Result에 있고, 불변이며, 그 행들에 대해 IteratorAggregate이자 Countable입니다.
| 클래스 | 담는 것 |
|---|---|
| Page | items, hasMore, nextCursor. 페이지로 나뉘는 모든 list에서 옵니다. |
| PeoplePage | 같은 것에 seen을 더한 것. contacts->listPeople에서 옵니다. |
| TempMessagesPage | 같은 것에 expiresAt을 더한 것. tempMail->listMessages에서 옵니다. |
| AddressBookPage, AddressBook | unrestricted, addresses, domains. addresses->list(hasMore와 nextCursor 포함)와 addresses->listAll에서 옵니다. |
| BatchResult | items, sent, failed. emails->sendBatch에서 옵니다. |
| TemplateSends | items, total, page, pageSize. templates->listSends에서 옵니다. |
| OpenEmail\Http\HttpRequest, OpenEmail\Http\HttpResponse | httpClient:가 받고 반환하는 것. var_dump(), print_r(), json_encode()는 요청의 Authorization 헤더를 [redacted]로 표시하지만, var_export()와 Symfony의 dump()는 그대로 표시합니다. |
패키지가 던지는 모든 예외는 OpenEmail\Exception\OpenEmailException을 구현합니다: ApiException과 그 하위 클래스, NetworkException, WebhookSignatureException, 그리고 API가 응답한 내용이 아니라 호출 자체의 실수 때문에 던져지는 InvalidArgumentException입니다.
아직 감싸지 않은 엔드포인트
패키지 릴리스가 이미 동작하는 엔드포인트와 여러분 사이를 가로막는 일은 없어야 합니다. $client->raw->request()는 경로와 명명된 인자를 받아 디코딩된 본문을 반환하며, 클라이언트의 자격 증명, 기본 URL, 타임아웃, 재시도 정책이 그대로 적용됩니다.
$result = $client->raw->request( '/labels', method: 'POST', query: ['dryRun' => true], body: ['name' => 'Invoices'], repeatable: true,); var_dump($result);GET은 다른 읽기와 마찬가지로 재시도됩니다. 그 밖의 메서드는 repeatable: true를 전달하지 않는 한 한 번만 전송되며, 이 값은 두 번 보내도 된다는 여러분의 단언입니다. query:는 null이거나 빈 값을 건너뛰고, apiKey:는 다른 모든 메서드에서와 똑같이 동작합니다.
의도적으로 하지 않는 것
- 요청 본문을 검증하지 않습니다. 규칙의 사본은 서버 스키마 하나뿐이며, 여기에 두 번째 사본을 두면 언젠가는 2년 전에 고정해 둔 버전에서 최신 서버라면 받아들일 주소를 거부하게 됩니다.
- curl과 json 확장 외에는 런타임 의존성이 없습니다. PSR-18 클라이언트는 선택 사항일 뿐 필수가 아닙니다.
- 응답의 형태를 바꾸는 방식은 하나뿐입니다: 컬렉션의
data배열을 봉투에서 꺼내 위의 객체 중 하나로 만듭니다. 그 밖의 모든 응답은 API가 보낸 그대로, API의 camelCase 키와 함께 돌아옵니다.
패키지의 패리티 검사가 이를 정직하게 지켜 줍니다. TypeScript 메서드에 PHP 짝이 없거나, 다른 인자를 받거나, 다른 요청을 보내면 빌드를 실패시킵니다.