Python

Tipos e utilitários

O que mais o pacote exporta.

Exportações em runtime

Exportação	O que é
init, openemail	Configure uma vez o cliente partilhado e depois importe `openemail` em qualquer lado. Constrói-se a partir de `OPENEMAIL_API_KEY` se `init` nunca correu.
get_client, reset_client	O próprio cliente partilhado, e uma forma de o largar para que a chamada seguinte construa um novo, que é o que um teste quer entre casos.
OpenEmail, create_client	Um cliente separado. `OpenEmail()` lê o ambiente para tudo o que deixar de fora, e `create_client` é outro nome para ele.
AsyncOpenEmail	O mesmo cliente com cada método chamado com await, em asyncio ou trio.
create_temp_mail, create_async_temp_mail	Um cliente de caixas descartáveis que não transporta chave de API, e o seu equivalente assíncrono.
OpenEmailError, OpenEmailApiError, OpenEmailNetworkError e WebhookVerificationError	Os erros que o pacote lança, todos sob `OpenEmailError`. Um `OpenEmailApiError` traz a resposta de erro analisada como `body`, e `fields` quando uma inscrição através de um formulário foi recusada.
verify_webhook_signature	Em tempo constante, com uma janela de repetição. Devolve o payload analisado e lança `WebhookVerificationError` em qualquer falha.
to_base64	Base64 para os bytes dos anexos, a partir de `bytes`, `bytearray` ou `memoryview`.
is_api_key	Se uma string tem a forma `oe_live_` ou `oe_test_`. Uma verificação de forma, não prova de que a chave ainda funciona.
is_access_token	Se uma string tem a forma de um token de acesso OAuth: de 1 a 512 caracteres, sem começar por `oe_`.
is_sealed, MESSAGE_ENCRYPTION_FORMATS	Se o corpo de uma mensagem é texto cifrado, e os cinco envelopes que a ingestão pode nomear. `is_sealed` é false para os dois formatos SIGNED, cujos corpos chegaram em claro, e é por isso que vem no pacote em vez de ser deixado a quem chama para derivar da união.
LANGUAGES, resolve_language, language_by_code e is_rtl_language	A tabela de idiomas incluída, e as procuras de que um seletor de idioma precisa.
API_SCOPES	O vocabulário de âmbitos, para um ecrã de criação de chaves.
WEBHOOK_EVENTS, WEBHOOK_SIGNATURE_HEADERS	Os eventos que um endpoint pode subscrever, e os nomes dos cabeçalhos que uma entrega transporta.
RULE_FIELDS, RULE_OPERATORS e RULE_ACTIONS	O vocabulário a partir do qual as condições e as ações de uma regra são construídas.
PAGE_LIMITS	O maior valor e o valor por omissão de `limit` na maioria das listas paginadas: 100 e 25. `contacts.list`, `audiences.list_contacts` e as listas de `tracking` aceitam até 200 com 50 por omissão, e `temp_mail.list_messages` aceita até 50.
ERROR_TYPES	O vocabulário de erros congelado.
VERSION, __version__	A versão do pacote.
THREAD_SORTS, PEOPLE_SORTS, CONTACT_THREAD_SORTS e FILE_SORTS	As ordens pelas quais as listas de conversas, pessoas, conversas de um contacto e ficheiros podem ser ordenadas.
FILE_KINDS, FILE_DIRECTIONS, CONTACT_BLOCK_LISTS e CONTACT_PHOTO_TYPES	Os filtros da lista de ficheiros, as duas listas de bloqueio do espaço de trabalho e os tipos de imagem que uma foto de contacto pode ter.
BROADCAST_STATUSES, BROADCAST_RECIPIENT_FILTERS, SUPPRESSION_REASONS e WEBHOOK_REPLAY_ERROR_CODES	Em que ponto está uma difusão, que cópias listar, porque é que um endereço está suprimido e porque é que um reenvio de webhook foi recusado.
PROVIDER_IMPORT_RESOURCES, PROVIDER_IMPORT_STATUSES e PROVIDER_IMPORT_DOMAIN_STATES	O que uma importação de fornecedor pode trazer, em que ponto está uma execução e em que ponto está cada domínio que encontrou.
FILE_USAGES	Porque é que um ficheiro é mantido em vez de poder ser eliminado: `received`, `sent`, `linked` ou `scheduled`.
CREDENTIAL_KINDS, STEP_UP_METHODS e STEP_UP_ERROR_CODES	Que credencial `me.get()` e `me.ping()` descrevem (`apiKey` ou `oauth`), como é verificado um código de verificação (`email` ou `totp`) e os códigos com que uma verificação pode falhar.
FORM_STATUSES, FORM_SUBMISSION_STATUSES, FORM_FIELD_TYPES, FORM_STARTER_SLUGS e FORM_*	Os valores que um formulário, os seus campos e as suas inscrições assumem, em dezasseis conjuntos: estados, tipos de campo, pontos de partida, tipos de letra, larguras e os motivos pelos quais uma resposta é recusada.
BILLING_, BRAND_, DNS_, DOMAIN_ e os outros conjuntos	Os valores de todos os outros espaços de nomes, cada conjunto com o nome do que contém.

Tipos

Cada pedido e cada resposta tem um, um TypedDict em openemail.types com o mesmo nome do seu equivalente em TypeScript. …Resource é o que a API devolve, e …Create, …Patch, …Input e …Send são o que passa. Os filtros e as opções por chamada são argumentos nomeados, por isso os tipos de TypeScript que os contêm, como EmailListOptions, não têm equivalente aqui.

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

As chaves são os nomes de campo em camelCase da própria API, como 'replyTo', 'scheduledAt' e 'nextCursor', tanto no que envia como no que volta. Só os argumentos de um método estão em snake_case (idempotency_key=, label_ids=), e um argumento que se chamaria from é from_=, como em emails.list e calendar.list_events.

O mypy e o pyright leem-nos, por isso uma chave mal escrita faz falhar a verificação de tipos em vez de chegar à API. O mypy indica Extra key "replyto" for TypedDict "EmailSend" para um corpo e TypedDict "SentEmailResource" has no key "satus" para uma resposta, e o pyright diz o mesmo por palavras suas. Um valor fora de um conjunto falha da mesma forma, como status='sending-ish' em emails.list.

Existem para o seu verificador de tipos. Em tempo de execução, cada TypedDict é um dict simples, por isso importar um não custa nada e nada é verificado enquanto o programa corre.

Cliente: Page, ApiKeyMode e RawBody. openemail.types.client acrescenta AccessTokenProvider, AsyncAccessTokenProvider, HeaderValue e QueryValue.
Erros: ErrorType e FormFieldProblem.
Emails: EmailSend, EmailTranslate, EmailResource, SentEmailResource, EmailRecipientResource, EmailEventResource, EmailStatus, EmailSource, EmailTransport, EmailTrackingSummary, EmailTranslationResource, TranslationResource, RecipientStatus, BatchItemResource e BatchResultResource.
Modelos: TemplateCreate, TemplatePatch, TemplateContent, TemplatePreviewInput, TemplateSend, TemplateResource, TemplateDetailResource, TemplateVersionResource, TemplatePreviewResource, TemplateSendsResource, SentTemplateEmailResource, DeletedTemplateResource, TemplateEngine, TemplateProp, TemplateSlot, TemplateStatus e TemplateValueKind.
Monitorização: TrackingResource, TrackingSummary, TrackingRecipientResource, TrackingLinkResource, TrackingOpenResource, TrackingClickResource, TrackingStatsResource e TrackingGrain.
Conversas e rascunhos: ThreadPatch, ThreadResource, ThreadSummaryResource, UpdatedThreadResource, TrashedThreadResource, SnoozedThreadResource, DraftInput, DraftResource, DraftSummaryResource, SavedDraftResource e DeletedDraftResource.
Etiquetas, contactos, domínios e endereços: LabelInput, LabelColor, LabelResource, DeletedLabelResource, ContactCreate, ContactPatch, ContactSource, ContactResource, ContactDetailResource, ContactAudienceResource, ContactAudiencesSet, DeletedContactResource, PeoplePage, PersonResource, DomainPatch, DomainResource, DomainDetailResource, DomainSendingState, DomainTracking, DomainTrackingState, AddressBookPage, AddressBookResource, AddressResource e SendableDomainResource.
Audiências: AudienceCreate, AudiencePatch, AudienceMemberSort, AudienceContactAdd, AudienceContactsBatch, AudienceImport, AudienceImportRow, AudienceResource, AudienceBuiltin, AudienceContactResource, AudienceMemberResource, RemovedAudienceContactResource, DeletedAudienceResource, EmptiedAudienceResource, AudienceBatchAddResource, AudienceBatchRemoveResource, AudienceImportResource, AudienceGrowthResource, AudienceGrowthTotals, AudienceGrowthSeries e AudienceGrowthBucket.
Difusões: BroadcastCreate, BroadcastPreviewInput, BroadcastResource, BroadcastCounts, BroadcastStatus, BroadcastPreviewResource, BroadcastRecipientResource, BroadcastRecipientContentResource, BroadcastRecipientFilter, BroadcastStatsResource, BroadcastStatsTotals e BroadcastStatsBucket.
Regras: RuleCreate, RulePatch, RuleTestInput, RuleResource, RuleRunResource, RuleTestResource, DeletedRuleResource, RuleCondition, RuleConditionInput, RuleAction, RuleActionType, RuleField e RuleOperator.
Webhooks: WebhookCreate, WebhookPatch, WebhookResource, CreatedWebhookResource, DeletedWebhookResource, WebhookDeliveryResource, WebhookDeliveryDetailResource, WebhookDeliveryAttempt, WebhookReplayResource, WebhookReplayRefusal, WebhookReplayErrorCode, WebhookTestResource, WebhookEvent, WebhookPayload, EmailOpenedData, EmailClickedData, EmailDownloadedData e FileEventData.
Calendário e definições: CalendarOccurrenceResource, CalendarEventResource, CalendarAttendeeResource, SettingsPatch e SettingsResource.
Funções, membros e chaves: RoleCreate, RolePatch, RoleResource, DeletedRoleResource, PermissionResource, MemberAdd, MemberPatch, MemberAddressGrant, MemberResource, MemberAddressResource, RemovedMemberResource, MemberAccess, KeyResource e PingResource.
Caixas descartáveis: TempInboxCreate, TempInboxResource, CreatedTempInboxResource, DeletedTempInboxResource, TempDomainResource, TempMessageResource, TempMessagesResource, TempMessageDetailResource e DeletedTempMessageResource.
Partilhados: RecipientInput, AttachmentInput, AttachmentResource, MessageResource, MessageEncryption, MessageEncryptionFormat, TrackingRequest, TranslateOptions, SendTranslateOptions, LanguageResource, ApiScope, Permission, BuiltinRole, HitKind.
Tokens de acesso e códigos de verificação: CredentialKind, ApiKeySelfResource, OauthTokenSelfResource, ApiKeyPingResource, OauthTokenPingResource, StepUpBegin, StepUpVerify, StepUpMethod, StepUpErrorCode, StepUpStatusResource, StepUpChallengeResource e StepUpVerifiedResource.
Formulários: FormCreate, FormPatch, FormResource, FormDetailResource, FormDocument, FormField, FormCopy, FormStyle, FormSettings, FormSettingsInput, FormStats, FormAudience, FormStarterResource, FormStarterDetailResource, FormAnalyticsResource, FormSubmissionResource, FormAnswer, ResentFormConfirmationResource, FormSubscribeValues, FormSubscriptionResource, FormSubmittedEventData e FormConfirmedEventData.
Tudo o resto que a API devolve, da faturação aos espaços de trabalho, tem os seus tipos com os mesmos nomes.

Conjuntos de strings

Os conjuntos de valores são constantes em openemail.constants, cada uma com o nome do que contém e um atributo para cada valor: EMAIL_STATUSES.SENT é 'sent'. Itere sobre um para obter todos os seus valores, verifique com in um valor que veio de fora e conte-os com len(). Cada membro é tipado como Final, por isso o mypy e o pyright leem EMAIL_STATUSES.SENT como o literal 'sent' e aceitam-no onde quer que se espere um EmailStatus.

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

O próprio openemail exporta 108 constantes: VERSION, LANGUAGES, PAGE_LIMITS, PAY_AS_YOU_GO_LIMITS_CENTS e 104 dos conjuntos, os que uma aplicação mais usa. Importe os outros, como EMAIL_STATUSES e TEMPLATE_STATUSES, a partir de openemail.constants, onde estão todos os conjuntos.

Um endpoint que isto ainda não envolve

Uma versão do SDK nunca deve ser o que se interpõe entre si e um endpoint que já funciona. client.raw.request() recebe um caminho e argumentos nomeados e devolve o corpo analisado, com a credencial, o URL base, o timeout e a política de repetição do cliente aplicados.

escape_hatch.py

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

Um GET é repetido como qualquer outra leitura. Qualquer outro método é enviado uma só vez a menos que passe repeatable=True, que é a sua afirmação de que pode ser enviado duas vezes. query ignora valores que sejam None ou vazios, e api_key= e timeout= funcionam como em todos os outros métodos. Em AsyncOpenEmail a chamada é feita com await.

O caminho tem de começar por uma única /. Qualquer outra coisa, e um caminho cujo URL final sairia da origem da API, lança ValueError antes de o pedido ser enviado, por isso a credencial nunca chega a outro host.

O que deliberadamente não faz

Não valida nenhum corpo de pedido. O esquema do servidor é a única cópia das regras, e uma segunda cópia aqui acabaria por recusar um endereço que um servidor mais recente aceita, numa versão que alguém fixou há dois anos.
Depende de httpx, anyio e typing-extensions, e de mais nada.
À saída converte apenas o que o JSON não consegue representar tal como está: os bytes no content de um anexo passam a base64, um datetime passa a ser um instante ISO 8601 em UTC, um date uma data ISO e um set uma lista. Um único destinatário em to, cc ou bcc é envolvido numa lista.
Remodela uma resposta de uma única forma: o array data de uma coleção é retirado do seu envelope. Uma lista paginada devolve-o como items ao lado de hasMore e nextCursor, contacts.list_people como items ao lado de hasMore, nextCursor e seen, emails.send_batch como items ao lado de sent e failed, templates.list_sends como items ao lado de total, page e pageSize, temp_mail.list_messages como items ao lado de hasMore, nextCursor e expiresAt, e addresses.list como addresses ao lado de unrestricted, domains, hasMore e nextCursor. imports.list_failures é a única lista deixada tal como a API a envia, {'object': ..., 'data': [...], 'nextCursor': ...}. Em todo o resto é uma lista simples. Cada recurso lá dentro mantém a forma HTTP documentada.

A verificação de paridade do pacote garante que isto se cumpre. Executa cada método ao lado do seu equivalente em TypeScript, com os mesmos argumentos e com todas as opções definidas, e falha quando falta um método, quando aceita opções diferentes, envia um pedido diferente ou devolve um valor diferente.