타입과 헬퍼

모든 요청과 응답에는 대응하는 타입이 있으며, 이는 TypeScript의 짝과 이름이 같은 openemail.types의 TypedDict입니다. …Resource는 API가 반환하는 것이고, …Create, …Patch, …Input, …Send는 여러분이 전달하는 것입니다. 필터와 호출별 옵션은 키워드 인자이므로, 이를 담는 TypeScript 타입(EmailListOptions 등)에는 여기서 대응하는 짝이 없습니다.

from openemail.types import EmailSend, Page, SentEmailResource, ThreadSummaryResource message: EmailSend = {    'from': 'Acme Billing <[email protected]>',    'to': '[email protected]',    'replyTo': '[email protected]',    'subject': 'Your September invoice',    'text': 'Your invoice is attached.',} sent: SentEmailResource = client.emails.send(message)inbox: Page[ThreadSummaryResource] = client.threads.list(folder='inbox') print(sent['status'], sent['scheduledAt'], inbox['nextCursor'])

키는 보내는 쪽이든 돌아오는 쪽이든 'replyTo', 'scheduledAt', 'nextCursor' 같은 API 고유의 camelCase 필드 이름입니다. snake_case인 것은 메서드의 인자(idempotency_key=, label_ids=)뿐이며, from이라고 불렸을 인자는 emails.list와 calendar.list_events에서처럼 from_=입니다.

mypy와 pyright 모두 이 타입을 읽으므로, 철자가 틀린 키는 API에 닿기 전에 타입 검사에서 실패합니다. mypy는 본문에 대해 Extra key "replyto" for TypedDict "EmailSend", 응답에 대해 TypedDict "SentEmailResource" has no key "satus"라고 보고하고, pyright도 자기 방식의 문구로 같은 내용을 알립니다. emails.list에서의 status='sending-ish'처럼 집합에 없는 값도 같은 방식으로 실패합니다.

• —클라이언트: Page, ApiKeyMode, RawBody. openemail.types.client에는 AccessTokenProvider, AsyncAccessTokenProvider, HeaderValue, QueryValue가 더 있습니다.
• —오류: ErrorType, FormFieldProblem.
• —이메일: EmailSend, EmailTranslate, EmailResource, SentEmailResource, EmailRecipientResource, EmailEventResource, EmailStatus, EmailSource, EmailTransport, EmailTrackingSummary, EmailTranslationResource, TranslationResource, RecipientStatus, BatchItemResource, BatchResultResource.
• —템플릿: TemplateCreate, TemplatePatch, TemplateContent, TemplatePreviewInput, TemplateSend, TemplateResource, TemplateDetailResource, TemplateVersionResource, TemplatePreviewResource, TemplateSendsResource, SentTemplateEmailResource, DeletedTemplateResource, TemplateEngine, TemplateProp, TemplateSlot, TemplateStatus, TemplateValueKind.
• —추적: TrackingResource, TrackingSummary, TrackingRecipientResource, TrackingLinkResource, TrackingOpenResource, TrackingClickResource, TrackingStatsResource, TrackingGrain.
• —스레드와 초안: ThreadPatch, ThreadResource, ThreadSummaryResource, UpdatedThreadResource, TrashedThreadResource, SnoozedThreadResource, DraftInput, DraftResource, DraftSummaryResource, SavedDraftResource, DeletedDraftResource.
• —레이블, 연락처, 도메인, 주소: LabelInput, LabelColor, LabelResource, DeletedLabelResource, ContactCreate, ContactPatch, ContactSource, ContactResource, ContactDetailResource, ContactAudienceResource, ContactAudiencesSet, DeletedContactResource, PeoplePage, PersonResource, DomainPatch, DomainResource, DomainDetailResource, DomainSendingState, DomainTracking, DomainTrackingState, AddressBookPage, AddressBookResource, AddressResource, SendableDomainResource.
• —오디언스: AudienceCreate, AudiencePatch, AudienceMemberSort, AudienceContactAdd, AudienceContactsBatch, AudienceImport, AudienceImportRow, AudienceResource, AudienceBuiltin, AudienceContactResource, AudienceMemberResource, RemovedAudienceContactResource, DeletedAudienceResource, EmptiedAudienceResource, AudienceBatchAddResource, AudienceBatchRemoveResource, AudienceImportResource, AudienceGrowthResource, AudienceGrowthTotals, AudienceGrowthSeries, AudienceGrowthBucket.
• —브로드캐스트: BroadcastCreate, BroadcastPreviewInput, BroadcastResource, BroadcastCounts, BroadcastStatus, BroadcastPreviewResource, BroadcastRecipientResource, BroadcastRecipientContentResource, BroadcastRecipientFilter, BroadcastStatsResource, BroadcastStatsTotals, BroadcastStatsBucket.
• —규칙: RuleCreate, RulePatch, RuleTestInput, RuleResource, RuleRunResource, RuleTestResource, DeletedRuleResource, RuleCondition, RuleConditionInput, RuleAction, RuleActionType, RuleField, RuleOperator.
• —웹훅: WebhookCreate, WebhookPatch, WebhookResource, CreatedWebhookResource, DeletedWebhookResource, WebhookDeliveryResource, WebhookDeliveryDetailResource, WebhookDeliveryAttempt, WebhookReplayResource, WebhookReplayRefusal, WebhookReplayErrorCode, WebhookTestResource, WebhookEvent, WebhookPayload, EmailOpenedData, EmailClickedData, EmailDownloadedData, FileEventData.
• —캘린더와 설정: CalendarOccurrenceResource, CalendarEventResource, CalendarAttendeeResource, SettingsPatch, SettingsResource.
• —역할, 멤버, 키: RoleCreate, RolePatch, RoleResource, DeletedRoleResource, PermissionResource, MemberAdd, MemberPatch, MemberAddressGrant, MemberResource, MemberAddressResource, RemovedMemberResource, MemberAccess, KeyResource, PingResource.
• —일회용 수신함: TempInboxCreate, TempInboxResource, CreatedTempInboxResource, DeletedTempInboxResource, TempDomainResource, TempMessageResource, TempMessagesResource, TempMessageDetailResource, DeletedTempMessageResource.
• —공통: RecipientInput, AttachmentInput, AttachmentResource, MessageResource, MessageEncryption, MessageEncryptionFormat, TrackingRequest, TranslateOptions, SendTranslateOptions, LanguageResource, ApiScope, Permission, BuiltinRole, HitKind.
• —액세스 토큰과 인증 코드: CredentialKind, ApiKeySelfResource, OauthTokenSelfResource, ApiKeyPingResource, OauthTokenPingResource, StepUpBegin, StepUpVerify, StepUpMethod, StepUpErrorCode, StepUpStatusResource, StepUpChallengeResource, StepUpVerifiedResource.
• —양식: FormCreate, FormPatch, FormResource, FormDetailResource, FormDocument, FormField, FormCopy, FormStyle, FormSettings, FormSettingsInput, FormStats, FormAudience, FormStarterResource, FormStarterDetailResource, FormAnalyticsResource, FormSubmissionResource, FormAnswer, ResentFormConfirmationResource, FormSubscribeValues, FormSubscriptionResource, FormSubmittedEventData, FormConfirmedEventData.
• —결제부터 워크스페이스까지 API가 반환하는 그 밖의 모든 것에도 같은 이름의 타입이 있습니다.

값 집합은 openemail.constants에 있는 상수로, 각각 담고 있는 것의 이름을 따서 붙였고 값마다 속성이 있습니다. 예를 들어 EMAIL_STATUSES.SENT는 'sent'입니다. 모든 값을 얻으려면 집합을 순회하고, 외부에서 들어온 값은 in으로 확인하며, 개수는 len()으로 셉니다. 각 멤버는 Final로 타입이 지정되어 있으므로, mypy와 pyright는 EMAIL_STATUSES.SENT를 리터럴 'sent'로 읽고 EmailStatus가 필요한 곳이면 어디서든 받아들입니다.

from openemail import PAGE_LIMITS, WEBHOOK_EVENTSfrom openemail.constants import EMAIL_STATUSES failed = client.emails.list(status=EMAIL_STATUSES.FAILED, limit=PAGE_LIMITS.MAX_LIMIT) print(EMAIL_STATUSES.SENT, list(EMAIL_STATUSES), len(WEBHOOK_EVENTS))print('email.opened' in WEBHOOK_EVENTS, len(failed['items']))

openemail 자체가 내보내는 상수는 108개로, VERSION, LANGUAGES, PAGE_LIMITS, PAY_AS_YOU_GO_LIMITS_CENTS, 그리고 애플리케이션이 가장 자주 쓰는 집합 104개입니다. EMAIL_STATUSES나 TEMPLATE_STATUSES 같은 나머지는 모든 집합이 있는 openemail.constants에서 import하십시오.

SDK 릴리스가 이미 동작하는 엔드포인트와 여러분 사이를 가로막는 일은 없어야 합니다. client.raw.request()는 경로와 키워드 인자를 받아 파싱된 본문을 반환하며, 클라이언트의 자격 증명, 기본 URL, 타임아웃, 재시도 정책이 그대로 적용됩니다.

result = client.raw.request(    '/something-new',    method='POST',    query={'dryRun': True},    body={'name': 'Invoices'},    repeatable=True,) print(result)

• —요청 본문을 검증하지 않습니다. 규칙의 사본은 서버 스키마 하나뿐이며, 여기에 두 번째 사본을 두면 언젠가는 2년 전에 고정해 둔 버전에서 최신 서버라면 받아들일 주소를 거부하게 됩니다.
• —httpx, anyio, typing-extensions에만 의존하며, 그 밖에는 아무것에도 의존하지 않습니다.
• —보낼 때는 JSON이 그대로 담을 수 없는 것만 변환합니다. 첨부 파일의 content에 있는 bytes는 base64로, datetime은 UTC 기준 ISO 8601 시각으로, date는 ISO 날짜로, set은 리스트로 바뀝니다. to, cc, bcc에 수신자가 하나뿐이면 리스트로 감쌉니다.
• —응답의 형태를 바꾸는 것은 한 가지뿐입니다. 컬렉션의 data 배열을 봉투에서 꺼내는 것입니다. 페이지 목록은 이를 hasMore, nextCursor와 함께 items로, contacts.list_people은 hasMore, nextCursor, seen과 함께 items로, emails.send_batch는 sent, failed와 함께 items로, templates.list_sends는 total, page, pageSize와 함께 items로, temp_mail.list_messages는 hasMore, nextCursor, expiresAt과 함께 items로, addresses.list는 unrestricted, domains, hasMore, nextCursor와 함께 addresses로 돌려줍니다. imports.list_failures는 API가 보낸 그대로인 {'object': ..., 'data': [...], 'nextCursor': ...} 형태로 남는 유일한 목록입니다. 그 밖의 곳에서는 모두 평범한 리스트입니다. 안에 들어 있는 리소스는 문서화된 HTTP 형태를 그대로 유지합니다.