型とヘルパー

すべてのリクエストとレスポンスに型があり、それは対応する 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。
• —Webhook: 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 つ目の写しを置けば、いずれ 2 年前に誰かが固定したバージョンが、新しいサーバーなら受け入れるアドレスを拒否することになる。
• —依存するのは httpx、anyio、typing-extensions だけで、それ以外には何にも依存しない。
• —送信時に変換するのは、JSON がそのままでは表せないものだけである。添付ファイルの content にある bytes は base64 に、datetime は UTC の ISO 8601 の時刻に、date は ISO 形式の日付に、set はリストになる。to、cc、bcc に受信者が 1 人だけ指定されていれば、リストに包まれる。
• —レスポンスの整形は 1 点だけである。コレクションの 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 上の形をそのまま保つ。