Python

Typen und Helfer

Was das Paket sonst noch exportiert.

Laufzeit-Exporte

Export	Was es ist
init, openemail	Konfigurieren Sie den gemeinsamen Client einmal, danach importieren Sie `openemail` überall. Er baut sich aus `OPENEMAIL_API_KEY` selbst auf, wenn `init` nie gelaufen ist.
get_client, reset_client	Der gemeinsame Client selbst, und eine Möglichkeit, ihn zu verwerfen, sodass der nächste Aufruf einen frischen erzeugt, genau das braucht ein Test zwischen zwei Fällen.
OpenEmail, create_client	Ein eigenständiger Client. `OpenEmail()` liest alles, was Sie weglassen, aus der Umgebung, und `create_client` ist ein anderer Name dafür.
AsyncOpenEmail	Derselbe Client, bei dem jede Methode mit await aufgerufen wird, auf asyncio oder trio.
create_temp_mail, create_async_temp_mail	Ein Client für Wegwerf-Postfächer, der keinen API-Schlüssel mitführt, und sein asynchrones Gegenstück.
OpenEmailError, OpenEmailApiError, OpenEmailNetworkError und WebhookVerificationError	Die Fehler, die das Paket auslöst, alle unterhalb von `OpenEmailError`. Ein `OpenEmailApiError` trägt die geparste Fehlerantwort als `body` und, wenn eine Anmeldung über ein Formular abgelehnt wurde, `fields`.
verify_webhook_signature	Konstante Laufzeit, mit einem Replay-Fenster. Gibt den geparsten Payload zurück und löst bei jedem Fehlschlag `WebhookVerificationError` aus.
to_base64	Base64 für die Bytes von Anhängen, aus `bytes`, `bytearray` oder `memoryview`.
is_api_key	Ob ein String die Form `oe_live_` oder `oe_test_` hat. Eine Formprüfung, kein Beleg dafür, dass der Key noch funktioniert.
is_access_token	Ob ein String die Form eines OAuth-Zugriffstokens hat: 1 bis 512 Zeichen, ohne `oe_` am Anfang.
is_sealed, MESSAGE_ENCRYPTION_FORMATS	Ob der Body einer Nachricht Chiffretext ist, und die fünf Envelopes, die der Eingang benennen kann. `is_sealed` ist false für die beiden SIGNED-Formate, deren Bodys im Klartext eintrafen, und genau deshalb wird es mitgeliefert, statt es einem Aufrufer zu überlassen, es aus der Union abzuleiten.
LANGUAGES, resolve_language, language_by_code und is_rtl_language	Die mitgelieferte Sprachtabelle und die Nachschlagefunktionen, die eine Sprachauswahl braucht.
API_SCOPES	Das Scope-Vokabular, für einen Bildschirm zum Anlegen von Keys.
WEBHOOK_EVENTS, WEBHOOK_SIGNATURE_HEADERS	Die Events, die ein Endpunkt abonnieren kann, und die Namen der Header, die eine Zustellung mitführt.
RULE_FIELDS, RULE_OPERATORS und RULE_ACTIONS	Das Vokabular, aus dem die Bedingungen und Aktionen einer Regel aufgebaut werden.
PAGE_LIMITS	Das größte und das voreingestellte `limit` der meisten paginierten Listen: 100 und 25. `contacts.list`, `audiences.list_contacts` und die `tracking`-Listen nehmen bis zu 200 mit einem Standardwert von 50, und `temp_mail.list_messages` nimmt bis zu 50.
ERROR_TYPES	Das eingefrorene Fehlervokabular.
VERSION, __version__	Die Version des Pakets.
THREAD_SORTS, PEOPLE_SORTS, CONTACT_THREAD_SORTS und FILE_SORTS	Die Reihenfolgen, in denen sich die Listen der Threads, der Personen, der Threads eines Kontakts und der Dateien sortieren lassen.
FILE_KINDS, FILE_DIRECTIONS, CONTACT_BLOCK_LISTS und CONTACT_PHOTO_TYPES	Die Filter der Dateiliste, die beiden Blocklisten des Workspace und die Bildtypen, die ein Kontaktfoto haben kann.
BROADCAST_STATUSES, BROADCAST_RECIPIENT_FILTERS, SUPPRESSION_REASONS und WEBHOOK_REPLAY_ERROR_CODES	Wo ein Broadcast steht, welche seiner Kopien aufgelistet werden, warum eine Adresse unterdrückt ist und warum ein Webhook-Replay abgelehnt wurde.
PROVIDER_IMPORT_RESOURCES, PROVIDER_IMPORT_STATUSES und PROVIDER_IMPORT_DOMAIN_STATES	Was ein Anbieter-Import übernehmen kann, wo ein Lauf steht und wo jede gefundene Domain steht.
FILE_USAGES	Warum eine Datei behalten wird, statt löschbar zu sein: `received`, `sent`, `linked` oder `scheduled`.
CREDENTIAL_KINDS, STEP_UP_METHODS und STEP_UP_ERROR_CODES	Welchen Zugang `me.get()` und `me.ping()` beschreiben (`apiKey` oder `oauth`), wie ein Bestätigungscode geprüft wird (`email` oder `totp`) und die Codes, mit denen eine Bestätigung scheitern kann.
FORM_STATUSES, FORM_SUBMISSION_STATUSES, FORM_FIELD_TYPES, FORM_STARTER_SLUGS und FORM_*	Die Werte, die ein Formular, seine Felder und seine Anmeldungen annehmen, in sechzehn Mengen: Status, Feldtypen, Ausgangspunkte, Schriften, Breiten und die Gründe, aus denen eine Antwort abgelehnt wird.
BILLING_, BRAND_, DNS_, DOMAIN_ und die übrigen Mengen	Die Werte jedes anderen Namespace, jede Menge benannt nach dem, was sie enthält.

Typen

Jede Anfrage und jede Antwort hat einen, ein TypedDict in openemail.types mit demselben Namen wie sein TypeScript-Gegenstück. …Resource ist, was die API zurückgibt, und …Create, …Patch, …Input und …Send sind, was Sie übergeben. Filter und Optionen pro Aufruf sind Schlüsselwortargumente, die TypeScript-Typen, die sie tragen, etwa EmailListOptions, haben hier daher kein Gegenstück.

typed.py

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'])

Die Schlüssel sind die eigenen camelCase-Feldnamen der API, etwa 'replyTo', 'scheduledAt' und 'nextCursor', in dem, was Sie senden, und in dem, was zurückkommt. Nur die Argumente einer Methode sind snake_case (idempotency_key=, label_ids=), und ein Argument, das from heißen würde, ist from_=, wie bei emails.list und calendar.list_events.

mypy und pyright lesen sie beide, ein falsch geschriebener Schlüssel lässt also die Typprüfung scheitern, statt die API zu erreichen. mypy meldet Extra key "replyto" for TypedDict "EmailSend" für einen Body und TypedDict "SentEmailResource" has no key "satus" für eine Antwort, und pyright sagt dasselbe mit eigenen Worten. Ein Wert außerhalb einer Menge scheitert auf dieselbe Weise, etwa status='sending-ish' bei emails.list.

Diese Typen existieren für Ihren Typprüfer. Zur Laufzeit ist jedes TypedDict ein einfaches dict, ein Import kostet also nichts, und während das Programm läuft, wird nichts geprüft.

Client: Page, ApiKeyMode und RawBody. openemail.types.client ergänzt AccessTokenProvider, AsyncAccessTokenProvider, HeaderValue und QueryValue.
Fehler: ErrorType und FormFieldProblem.
E-Mails: EmailSend, EmailTranslate, EmailResource, SentEmailResource, EmailRecipientResource, EmailEventResource, EmailStatus, EmailSource, EmailTransport, EmailTrackingSummary, EmailTranslationResource, TranslationResource, RecipientStatus, BatchItemResource und BatchResultResource.
Vorlagen: TemplateCreate, TemplatePatch, TemplateContent, TemplatePreviewInput, TemplateSend, TemplateResource, TemplateDetailResource, TemplateVersionResource, TemplatePreviewResource, TemplateSendsResource, SentTemplateEmailResource, DeletedTemplateResource, TemplateEngine, TemplateProp, TemplateSlot, TemplateStatus und TemplateValueKind.
Tracking: TrackingResource, TrackingSummary, TrackingRecipientResource, TrackingLinkResource, TrackingOpenResource, TrackingClickResource, TrackingStatsResource und TrackingGrain.
Threads und Entwürfe: ThreadPatch, ThreadResource, ThreadSummaryResource, UpdatedThreadResource, TrashedThreadResource, SnoozedThreadResource, DraftInput, DraftResource, DraftSummaryResource, SavedDraftResource und DeletedDraftResource.
Labels, Kontakte, Domains und Adressen: LabelInput, LabelColor, LabelResource, DeletedLabelResource, ContactCreate, ContactPatch, ContactSource, ContactResource, ContactDetailResource, ContactAudienceResource, ContactAudiencesSet, DeletedContactResource, PeoplePage, PersonResource, DomainPatch, DomainResource, DomainDetailResource, DomainSendingState, DomainTracking, DomainTrackingState, AddressBookPage, AddressBookResource, AddressResource und SendableDomainResource.
Audiences: AudienceCreate, AudiencePatch, AudienceMemberSort, AudienceContactAdd, AudienceContactsBatch, AudienceImport, AudienceImportRow, AudienceResource, AudienceBuiltin, AudienceContactResource, AudienceMemberResource, RemovedAudienceContactResource, DeletedAudienceResource, EmptiedAudienceResource, AudienceBatchAddResource, AudienceBatchRemoveResource, AudienceImportResource, AudienceGrowthResource, AudienceGrowthTotals, AudienceGrowthSeries und AudienceGrowthBucket.
Broadcasts: BroadcastCreate, BroadcastPreviewInput, BroadcastResource, BroadcastCounts, BroadcastStatus, BroadcastPreviewResource, BroadcastRecipientResource, BroadcastRecipientContentResource, BroadcastRecipientFilter, BroadcastStatsResource, BroadcastStatsTotals und BroadcastStatsBucket.
Regeln: RuleCreate, RulePatch, RuleTestInput, RuleResource, RuleRunResource, RuleTestResource, DeletedRuleResource, RuleCondition, RuleConditionInput, RuleAction, RuleActionType, RuleField und RuleOperator.
Webhooks: WebhookCreate, WebhookPatch, WebhookResource, CreatedWebhookResource, DeletedWebhookResource, WebhookDeliveryResource, WebhookDeliveryDetailResource, WebhookDeliveryAttempt, WebhookReplayResource, WebhookReplayRefusal, WebhookReplayErrorCode, WebhookTestResource, WebhookEvent, WebhookPayload, EmailOpenedData, EmailClickedData, EmailDownloadedData und FileEventData.
Kalender und Einstellungen: CalendarOccurrenceResource, CalendarEventResource, CalendarAttendeeResource, SettingsPatch und SettingsResource.
Rollen, Mitglieder und Schlüssel: RoleCreate, RolePatch, RoleResource, DeletedRoleResource, PermissionResource, MemberAdd, MemberPatch, MemberAddressGrant, MemberResource, MemberAddressResource, RemovedMemberResource, MemberAccess, KeyResource und PingResource.
Wegwerf-Postfächer: TempInboxCreate, TempInboxResource, CreatedTempInboxResource, DeletedTempInboxResource, TempDomainResource, TempMessageResource, TempMessagesResource, TempMessageDetailResource und DeletedTempMessageResource.
Gemeinsam genutzt: RecipientInput, AttachmentInput, AttachmentResource, MessageResource, MessageEncryption, MessageEncryptionFormat, TrackingRequest, TranslateOptions, SendTranslateOptions, LanguageResource, ApiScope, Permission, BuiltinRole, HitKind.
Zugriffstoken und Bestätigungscodes: CredentialKind, ApiKeySelfResource, OauthTokenSelfResource, ApiKeyPingResource, OauthTokenPingResource, StepUpBegin, StepUpVerify, StepUpMethod, StepUpErrorCode, StepUpStatusResource, StepUpChallengeResource und StepUpVerifiedResource.
Formulare: FormCreate, FormPatch, FormResource, FormDetailResource, FormDocument, FormField, FormCopy, FormStyle, FormSettings, FormSettingsInput, FormStats, FormAudience, FormStarterResource, FormStarterDetailResource, FormAnalyticsResource, FormSubmissionResource, FormAnswer, ResentFormConfirmationResource, FormSubscribeValues, FormSubscriptionResource, FormSubmittedEventData und FormConfirmedEventData.
Alles andere, was die API zurückgibt, von der Abrechnung bis zu den Workspaces, hat seine Typen unter denselben Namen.

String-Mengen

Die Wertemengen sind Konstanten in openemail.constants, jede benannt nach dem, was sie enthält, mit einem Attribut für jeden Wert: EMAIL_STATUSES.SENT ist 'sent'. Iterieren Sie über eine, um jeden Wert zu erhalten, prüfen Sie einen Wert, der von außen kam, mit in, und zählen Sie die Werte mit len(). Jedes Element ist als Final typisiert, mypy und pyright lesen EMAIL_STATUSES.SENT daher als das Literal 'sent' und akzeptieren es überall, wo ein EmailStatus erwartet wird.

constants.py

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 selbst exportiert 108 Konstanten: VERSION, LANGUAGES, PAGE_LIMITS, PAY_AS_YOU_GO_LIMITS_CENTS und 104 der Mengen, nämlich die, zu denen eine Anwendung am häufigsten greift. Importieren Sie die übrigen, etwa EMAIL_STATUSES und TEMPLATE_STATUSES, aus openemail.constants, wo jede Menge liegt.

Ein Endpunkt, den dies noch nicht kapselt

Ein SDK-Release sollte nie zwischen Ihnen und einem Endpunkt stehen, der bereits funktioniert. client.raw.request() nimmt einen Pfad und Schlüsselwortargumente entgegen und gibt den geparsten Body zurück, wobei Anmeldedaten, Basis-URL, Timeout und Retry-Policy des Clients angewendet werden.

escape_hatch.py

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

Ein GET wird wie jeder andere Lesevorgang wiederholt. Jede andere Methode wird genau einmal gesendet, sofern Sie nicht repeatable=True übergeben, womit Sie zusichern, dass sie zweimal gesendet werden darf. query überspringt Werte, die None oder leer sind, und api_key= und timeout= funktionieren wie bei jeder anderen Methode. Auf AsyncOpenEmail wird der Aufruf mit await abgewartet.

Der Pfad muss mit genau einem / beginnen. Alles andere sowie ein Pfad, dessen fertige URL den Ursprung der API verlassen würde, löst ValueError aus, bevor eine Anfrage gesendet wird, sodass die Anmeldedaten nie einen anderen Host erreichen.

Was es bewusst nicht tut

Es validiert keinen Request-Body. Das Schema des Servers ist die einzige Kopie der Regeln, und eine zweite Kopie hier würde irgendwann eine Adresse ablehnen, die ein neuerer Server akzeptiert, in einer Version, die jemand vor zwei Jahren gepinnt hat.
Es hängt von httpx, anyio und typing-extensions ab und von nichts anderem.
Auf dem Weg hinaus wandelt es nur um, was JSON nicht unverändert abbilden kann: bytes im content eines Anhangs werden zu base64, ein datetime wird zu einem ISO-8601-Zeitpunkt in UTC, ein date zu einem ISO-Datum und ein set zu einer Liste. Ein einzelner Empfänger in to, cc oder bcc wird in eine Liste verpackt.
Es formt eine Antwort auf nur eine einzige Weise um: Das data-Array einer Collection wird aus seinem Umschlag gehoben. Eine paginierte Liste gibt es als items neben hasMore und nextCursor zurück, contacts.list_people als items neben hasMore, nextCursor und seen, emails.send_batch als items neben sent und failed, templates.list_sends als items neben total, page und pageSize, temp_mail.list_messages als items neben hasMore, nextCursor und expiresAt und addresses.list als addresses neben unrestricted, domains, hasMore und nextCursor. imports.list_failures ist die einzige Liste, die so bleibt, wie die API sie sendet, {'object': ..., 'data': [...], 'nextCursor': ...}. Überall sonst ist es eine einfache Liste. Jede darin enthaltene Ressource behält die dokumentierte HTTP-Form.

Die Paritätsprüfung des Pakets hält das ehrlich. Die Prüfung führt jede Methode neben ihrem TypeScript-Gegenstück aus, mit denselben Argumenten und mit allen gesetzten Optionen, und schlägt fehl, wenn eine Methode fehlt, andere Optionen nimmt, eine andere Anfrage sendet oder einen anderen Wert zurückgibt.