Python

Types et utilitaires

Ce que le paquet exporte par ailleurs.

Exports à l'exécution

Export	Ce que c'est
init, openemail	Configurez le client partagé une fois, puis importez `openemail` n'importe où. Il se construit tout seul à partir de `OPENEMAIL_API_KEY` si `init` n'a jamais été appelé.
get_client, reset_client	Le client partagé lui-même, et un moyen de l'abandonner pour que l'appel suivant en construise un neuf, ce qu'un test veut entre deux cas.
OpenEmail, create_client	Un client distinct. `OpenEmail()` lit l'environnement pour tout ce que vous omettez, et `create_client` en est un autre nom.
AsyncOpenEmail	Le même client, chaque méthode s'appelant avec await, sur asyncio ou trio.
create_temp_mail, create_async_temp_mail	Un client de boîte jetable qui ne porte aucune clé API, et son équivalent asynchrone.
OpenEmailError, OpenEmailApiError, OpenEmailNetworkError et WebhookVerificationError	Les erreurs que lève le paquet, toutes sous `OpenEmailError`. Une `OpenEmailApiError` porte la réponse d'erreur analysée dans `body`, et `fields` quand une inscription à un formulaire a été refusée.
verify_webhook_signature	À temps constant, avec une fenêtre de rejeu. Renvoie la charge utile analysée et lève `WebhookVerificationError` au moindre échec.
to_base64	Base64 pour les octets des pièces jointes, à partir de `bytes`, `bytearray` ou `memoryview`.
is_api_key	Indique si une chaîne a la forme `oe_live_` ou `oe_test_`. Une vérification de forme, pas une preuve que la clé fonctionne encore.
is_access_token	Indique si une chaîne a la forme d'un jeton d'accès OAuth : de 1 à 512 caractères, sans commencer par `oe_`.
is_sealed, MESSAGE_ENCRYPTION_FORMATS	Indique si le corps d'un message est du chiffré, et les cinq enveloppes que l'ingestion peut nommer. `is_sealed` vaut false pour les deux formats SIGNED, dont les corps sont arrivés en clair : c'est pourquoi il est fourni plutôt que laissé à l'appelant, qui devrait le déduire de l'union.
LANGUAGES, resolve_language, language_by_code et is_rtl_language	La table de langues intégrée, et les fonctions de recherche dont un sélecteur de langue a besoin.
API_SCOPES	Le vocabulaire des portées, pour un écran de création de clé.
WEBHOOK_EVENTS, WEBHOOK_SIGNATURE_HEADERS	Les événements auxquels un endpoint peut s'abonner, et les noms des en-têtes que porte une livraison.
RULE_FIELDS, RULE_OPERATORS et RULE_ACTIONS	Le vocabulaire à partir duquel se construisent les conditions et les actions d'une règle.
PAGE_LIMITS	La valeur maximale et la valeur par défaut de `limit` sur la plupart des listes paginées : 100 et 25. `contacts.list`, `audiences.list_contacts` et les listes `tracking` acceptent jusqu'à 200 avec une valeur par défaut de 50, et `temp_mail.list_messages` accepte jusqu'à 50.
ERROR_TYPES	Le vocabulaire figé des erreurs.
VERSION, __version__	La version du paquet.
THREAD_SORTS, PEOPLE_SORTS, CONTACT_THREAD_SORTS et FILE_SORTS	Les ordres dans lesquels peuvent être triées les listes des fils, des personnes, des fils d'un contact et des fichiers.
FILE_KINDS, FILE_DIRECTIONS, CONTACT_BLOCK_LISTS et CONTACT_PHOTO_TYPES	Les filtres de la liste des fichiers, les deux listes de blocage de l'espace de travail, et les types d'image que peut avoir la photo d'un contact.
BROADCAST_STATUSES, BROADCAST_RECIPIENT_FILTERS, SUPPRESSION_REASONS et WEBHOOK_REPLAY_ERROR_CODES	Où en est une diffusion, lesquelles de ses copies lister, pourquoi une adresse est supprimée, et pourquoi un rejeu de webhook a été refusé.
PROVIDER_IMPORT_RESOURCES, PROVIDER_IMPORT_STATUSES et PROVIDER_IMPORT_DOMAIN_STATES	Ce qu'un import de fournisseur peut reprendre, où en est une exécution, et où en est chaque domaine qu'il a trouvé.
FILE_USAGES	Pourquoi un fichier est conservé plutôt que supprimable : `received`, `sent`, `linked` ou `scheduled`.
CREDENTIAL_KINDS, STEP_UP_METHODS et STEP_UP_ERROR_CODES	Quel identifiant décrivent `me.get()` et `me.ping()` (`apiKey` ou `oauth`), comment un code de vérification est contrôlé (`email` ou `totp`), et les codes avec lesquels une vérification peut échouer.
FORM_STATUSES, FORM_SUBMISSION_STATUSES, FORM_FIELD_TYPES, FORM_STARTER_SLUGS et FORM_*	Les valeurs que prennent un formulaire, ses champs et ses inscriptions, en seize ensembles : statuts, types de champ, points de départ, polices, largeurs, et les raisons pour lesquelles une réponse est refusée.
BILLING_, BRAND_, DNS_, DOMAIN_ et les autres ensembles	Les valeurs de tous les autres espaces de noms, chaque ensemble étant nommé d'après ce qu'il contient.

Types

Chaque requête et chaque réponse en a un, un TypedDict dans openemail.types qui porte le même nom que son équivalent TypeScript. …Resource est ce que l'API renvoie, et …Create, …Patch, …Input et …Send sont ce que vous passez. Les filtres et les options propres à un appel sont des arguments nommés : les types TypeScript qui les portent, comme EmailListOptions, n'ont donc pas d'équivalent ici.

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

Les clés sont les noms de champs propres à l'API, en camelCase, comme 'replyTo', 'scheduledAt' et 'nextCursor', dans ce que vous envoyez comme dans ce qui revient. Seuls les arguments d'une méthode sont en snake_case (idempotency_key=, label_ids=), et un argument qui s'appellerait from devient from_=, comme sur emails.list et calendar.list_events.

mypy et pyright les lisent tous deux : une clé mal orthographiée fait donc échouer la vérification des types au lieu d'atteindre l'API. mypy signale Extra key "replyto" for TypedDict "EmailSend" pour un corps et TypedDict "SentEmailResource" has no key "satus" pour une réponse, et pyright dit la même chose à sa manière. Une valeur hors d'un ensemble échoue de la même façon, comme status='sending-ish' sur emails.list.

Ils existent pour votre vérificateur de types. À l'exécution, chaque TypedDict est un simple dict : en importer un ne coûte rien, et rien n'est vérifié pendant que le programme tourne.

Client : Page, ApiKeyMode, RawBody. openemail.types.client ajoute AccessTokenProvider, AsyncAccessTokenProvider, HeaderValue et QueryValue.
Erreurs : ErrorType, FormFieldProblem.
E-mails : EmailSend, EmailTranslate, EmailResource, SentEmailResource, EmailRecipientResource, EmailEventResource, EmailStatus, EmailSource, EmailTransport, EmailTrackingSummary, EmailTranslationResource, TranslationResource, RecipientStatus, BatchItemResource, BatchResultResource.
Modèles : TemplateCreate, TemplatePatch, TemplateContent, TemplatePreviewInput, TemplateSend, TemplateResource, TemplateDetailResource, TemplateVersionResource, TemplatePreviewResource, TemplateSendsResource, SentTemplateEmailResource, DeletedTemplateResource, TemplateEngine, TemplateProp, TemplateSlot, TemplateStatus, TemplateValueKind.
Suivi : TrackingResource, TrackingSummary, TrackingRecipientResource, TrackingLinkResource, TrackingOpenResource, TrackingClickResource, TrackingStatsResource, TrackingGrain.
Conversations et brouillons : ThreadPatch, ThreadResource, ThreadSummaryResource, UpdatedThreadResource, TrashedThreadResource, SnoozedThreadResource, DraftInput, DraftResource, DraftSummaryResource, SavedDraftResource, DeletedDraftResource.
Libellés, contacts, domaines et adresses : LabelInput, LabelColor, LabelResource, DeletedLabelResource, ContactCreate, ContactPatch, ContactSource, ContactResource, ContactDetailResource, ContactAudienceResource, ContactAudiencesSet, DeletedContactResource, PeoplePage, PersonResource, DomainPatch, DomainResource, DomainDetailResource, DomainSendingState, DomainTracking, DomainTrackingState, AddressBookPage, AddressBookResource, AddressResource, SendableDomainResource.
Audiences : AudienceCreate, AudiencePatch, AudienceMemberSort, AudienceContactAdd, AudienceContactsBatch, AudienceImport, AudienceImportRow, AudienceResource, AudienceBuiltin, AudienceContactResource, AudienceMemberResource, RemovedAudienceContactResource, DeletedAudienceResource, EmptiedAudienceResource, AudienceBatchAddResource, AudienceBatchRemoveResource, AudienceImportResource, AudienceGrowthResource, AudienceGrowthTotals, AudienceGrowthSeries, AudienceGrowthBucket.
Diffusions : BroadcastCreate, BroadcastPreviewInput, BroadcastResource, BroadcastCounts, BroadcastStatus, BroadcastPreviewResource, BroadcastRecipientResource, BroadcastRecipientContentResource, BroadcastRecipientFilter, BroadcastStatsResource, BroadcastStatsTotals, BroadcastStatsBucket.
Règles : RuleCreate, RulePatch, RuleTestInput, RuleResource, RuleRunResource, RuleTestResource, DeletedRuleResource, RuleCondition, RuleConditionInput, RuleAction, RuleActionType, RuleField, RuleOperator.
Webhooks : WebhookCreate, WebhookPatch, WebhookResource, CreatedWebhookResource, DeletedWebhookResource, WebhookDeliveryResource, WebhookDeliveryDetailResource, WebhookDeliveryAttempt, WebhookReplayResource, WebhookReplayRefusal, WebhookReplayErrorCode, WebhookTestResource, WebhookEvent, WebhookPayload, EmailOpenedData, EmailClickedData, EmailDownloadedData, FileEventData.
Calendrier et paramètres : CalendarOccurrenceResource, CalendarEventResource, CalendarAttendeeResource, SettingsPatch, SettingsResource.
Rôles, membres et clés : RoleCreate, RolePatch, RoleResource, DeletedRoleResource, PermissionResource, MemberAdd, MemberPatch, MemberAddressGrant, MemberResource, MemberAddressResource, RemovedMemberResource, MemberAccess, KeyResource, PingResource.
Boîtes jetables : TempInboxCreate, TempInboxResource, CreatedTempInboxResource, DeletedTempInboxResource, TempDomainResource, TempMessageResource, TempMessagesResource, TempMessageDetailResource, DeletedTempMessageResource.
Partagés : RecipientInput, AttachmentInput, AttachmentResource, MessageResource, MessageEncryption, MessageEncryptionFormat, TrackingRequest, TranslateOptions, SendTranslateOptions, LanguageResource, ApiScope, Permission, BuiltinRole, HitKind.
Jetons d'accès et codes de vérification : CredentialKind, ApiKeySelfResource, OauthTokenSelfResource, ApiKeyPingResource, OauthTokenPingResource, StepUpBegin, StepUpVerify, StepUpMethod, StepUpErrorCode, StepUpStatusResource, StepUpChallengeResource, StepUpVerifiedResource.
Formulaires : FormCreate, FormPatch, FormResource, FormDetailResource, FormDocument, FormField, FormCopy, FormStyle, FormSettings, FormSettingsInput, FormStats, FormAudience, FormStarterResource, FormStarterDetailResource, FormAnalyticsResource, FormSubmissionResource, FormAnswer, ResentFormConfirmationResource, FormSubscribeValues, FormSubscriptionResource, FormSubmittedEventData, FormConfirmedEventData.
Tout ce que l'API renvoie d'autre, de la facturation aux espaces de travail, a ses types sous les mêmes noms.

Ensembles de chaînes

Les ensembles de valeurs sont des constantes dans openemail.constants, chacune nommée d'après ce qu'elle contient, avec un attribut par valeur : EMAIL_STATUSES.SENT vaut 'sent'. Itérez sur un ensemble pour obtenir toutes ses valeurs, vérifiez une valeur venue de l'extérieur avec in, et comptez-les avec len(). Chaque membre est typé Final : mypy et pyright lisent donc EMAIL_STATUSES.SENT comme le littéral 'sent' et l'acceptent partout où un EmailStatus est attendu.

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 exporte lui-même 108 constantes : VERSION, LANGUAGES, PAGE_LIMITS, PAY_AS_YOU_GO_LIMITS_CENTS et 104 des ensembles, ceux qu'une application utilise le plus. Importez les autres, comme EMAIL_STATUSES et TEMPLATE_STATUSES, depuis openemail.constants, où se trouvent tous les ensembles.

Un endpoint que ceci n'encapsule pas encore

Une version du SDK ne devrait jamais s'interposer entre vous et un endpoint qui fonctionne déjà. client.raw.request() prend un chemin et des arguments nommés, et renvoie le corps analysé, en appliquant l'identifiant, l'URL de base, le timeout et la politique de réessai du client.

escape_hatch.py

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

Un GET est réessayé comme n'importe quelle lecture. Toute autre méthode n'est envoyée qu'une fois, sauf si vous passez repeatable=True, qui est votre affirmation qu'elle peut être envoyée deux fois. query ignore les valeurs None ou vides, et api_key= et timeout= se comportent comme sur toutes les autres méthodes. Sur AsyncOpenEmail, l'appel s'utilise avec await.

Le chemin doit commencer par un seul /. Tout autre chemin, ainsi qu'un chemin dont l'URL finale sortirait de l'origine de l'API, lève ValueError avant l'envoi de la requête : l'identifiant n'atteint donc jamais un autre hôte.

Ce qu'il ne fait délibérément pas

Il ne valide aucun corps de requête. Le schéma du serveur est l'unique copie des règles ; une seconde copie ici finirait par refuser une adresse qu'un serveur plus récent accepte, dans une version que quelqu'un a épinglée deux ans plus tôt.
Il dépend de httpx, anyio et typing-extensions, et de rien d'autre.
À l'envoi, il ne convertit que ce que JSON ne peut pas transporter tel quel : les bytes du content d'une pièce jointe deviennent du base64, un datetime devient un instant ISO 8601 en UTC, un date une date ISO et un set une liste. Un destinataire seul dans to, cc ou bcc est enveloppé dans une liste.
Il ne remodèle une réponse que d'une seule façon : le tableau data d'une collection est sorti de son enveloppe. Une liste paginée le restitue sous items, à côté de hasMore et nextCursor ; contacts.list_people sous items, à côté de hasMore, nextCursor et seen ; emails.send_batch sous items, à côté de sent et failed ; templates.list_sends sous items, à côté de total, page et pageSize ; temp_mail.list_messages sous items, à côté de hasMore, nextCursor et expiresAt ; et addresses.list sous addresses, à côté de unrestricted, domains, hasMore et nextCursor. imports.list_failures est la seule liste laissée telle que l'API l'envoie, {'object': ..., 'data': [...], 'nextCursor': ...}. Partout ailleurs, c'est une simple liste. Chaque ressource qu'il contient conserve la forme HTTP documentée.

Le contrôle de parité du paquet garantit que tout cela reste vrai. Il exécute chaque méthode à côté de son équivalent TypeScript, avec les mêmes arguments et toutes les options renseignées, et échoue quand une méthode manque, prend des options différentes, envoie une requête différente ou renvoie une valeur différente.