Python

Tipos y utilidades

Qué más exporta el paquete.

Exportaciones en tiempo de ejecución

Exportación	Qué es
init, openemail	Configura el cliente compartido una vez y luego importa `openemail` donde quieras. Se construye solo a partir de `OPENEMAIL_API_KEY` si `init` nunca se ejecutó.
get_client, reset_client	El propio cliente compartido, y una forma de descartarlo para que la siguiente llamada construya uno nuevo, que es lo que necesita una prueba entre casos.
OpenEmail, create_client	Un cliente aparte. `OpenEmail()` lee el entorno para todo lo que omitas, y `create_client` es otro nombre para él.
AsyncOpenEmail	El mismo cliente con cada método llamado con await, en asyncio o trio.
create_temp_mail, create_async_temp_mail	Un cliente de buzones desechables que no lleva ninguna clave de API, y su equivalente asíncrono.
OpenEmailError, OpenEmailApiError, OpenEmailNetworkError y WebhookVerificationError	Los errores que lanza el paquete, todos bajo `OpenEmailError`. Un `OpenEmailApiError` lleva la respuesta de error ya analizada como `body`, y `fields` cuando se rechazó una suscripción mediante un formulario.
verify_webhook_signature	De tiempo constante, con una ventana de repetición. Devuelve el payload ya analizado y lanza `WebhookVerificationError` ante cualquier fallo.
to_base64	Base64 para los bytes de los adjuntos, a partir de `bytes`, `bytearray` o `memoryview`.
is_api_key	Si una cadena tiene la forma `oe_live_` u `oe_test_`. Es una comprobación de forma, no una prueba de que la clave siga funcionando.
is_access_token	Si una cadena tiene la forma de un token de acceso OAuth: de 1 a 512 caracteres, sin empezar por `oe_`.
is_sealed, MESSAGE_ENCRYPTION_FORMATS	Si el cuerpo de un mensaje está cifrado, y los cinco sobres que puede nombrar la ingesta. `is_sealed` es false para los dos formatos SIGNED, cuyos cuerpos llegaron en claro, y por eso se incluye en lugar de dejar que quien llama lo deduzca de la unión.
LANGUAGES, resolve_language, language_by_code y is_rtl_language	La tabla de idiomas incluida, y las búsquedas que necesita un selector de idioma.
API_SCOPES	El vocabulario de ámbitos, para una pantalla de creación de claves.
WEBHOOK_EVENTS, WEBHOOK_SIGNATURE_HEADERS	Los eventos a los que se puede suscribir un endpoint, y los nombres de las cabeceras que lleva una entrega.
RULE_FIELDS, RULE_OPERATORS y RULE_ACTIONS	El vocabulario con el que se construyen las condiciones y las acciones de una regla.
PAGE_LIMITS	El `limit` máximo y el predeterminado en la mayoría de las listas paginadas: 100 y 25. `contacts.list`, `audiences.list_contacts` y las listas de `tracking` aceptan hasta 200 con un valor predeterminado de 50, y `temp_mail.list_messages` acepta hasta 50.
ERROR_TYPES	El vocabulario de errores congelado.
VERSION, __version__	La versión del paquete.
THREAD_SORTS, PEOPLE_SORTS, CONTACT_THREAD_SORTS y FILE_SORTS	Los órdenes en que se pueden ordenar las listas de hilos, de personas, de hilos de un contacto y de archivos.
FILE_KINDS, FILE_DIRECTIONS, CONTACT_BLOCK_LISTS y CONTACT_PHOTO_TYPES	Los filtros de la lista de archivos, las dos listas de bloqueo del espacio de trabajo y los tipos de imagen que puede tener la foto de un contacto.
BROADCAST_STATUSES, BROADCAST_RECIPIENT_FILTERS, SUPPRESSION_REASONS y WEBHOOK_REPLAY_ERROR_CODES	En qué punto está un envío masivo, qué copias suyas listar, por qué una dirección está suprimida y por qué se rechazó un reenvío de webhook.
PROVIDER_IMPORT_RESOURCES, PROVIDER_IMPORT_STATUSES y PROVIDER_IMPORT_DOMAIN_STATES	Lo que puede traer una importación de proveedor, en qué punto está una ejecución y en qué punto está cada dominio que encontró.
FILE_USAGES	Por qué un archivo se conserva en lugar de poder eliminarse: `received`, `sent`, `linked` o `scheduled`.
CREDENTIAL_KINDS, STEP_UP_METHODS y STEP_UP_ERROR_CODES	Qué credencial describen `me.get()` y `me.ping()` (`apiKey` u `oauth`), cómo se comprueba un código de verificación (`email` o `totp`) y los códigos con los que puede fallar una verificación.
FORM_STATUSES, FORM_SUBMISSION_STATUSES, FORM_FIELD_TYPES, FORM_STARTER_SLUGS y FORM_*	Los valores que toman un formulario, sus campos y sus suscripciones, en dieciséis conjuntos: estados, tipos de campo, puntos de partida, fuentes, anchos y los motivos por los que se rechaza una respuesta.
BILLING_, BRAND_, DNS_, DOMAIN_ y los demás conjuntos	Los valores de todos los demás espacios de nombres, cada conjunto con el nombre de lo que contiene.

Tipos

Cada solicitud y cada respuesta tiene uno, un TypedDict en openemail.types con el mismo nombre que su equivalente en TypeScript. …Resource es lo que devuelve la API, y …Create, …Patch, …Input y …Send son lo que le pasas. Los filtros y las opciones por llamada son argumentos nombrados, así que los tipos de TypeScript que los contienen, como EmailListOptions, no tienen equivalente aquí.

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

Las claves son los nombres de campo en camelCase propios de la API, como 'replyTo', 'scheduledAt' y 'nextCursor', tanto en lo que envías como en lo que vuelve. Solo los argumentos de un método están en snake_case (idempotency_key=, label_ids=), y un argumento que se llamaría from es from_=, como en emails.list y calendar.list_events.

mypy y pyright los leen, así que una clave mal escrita hace fallar la comprobación de tipos en lugar de llegar a la API. mypy informa Extra key "replyto" for TypedDict "EmailSend" para un cuerpo y TypedDict "SentEmailResource" has no key "satus" para una respuesta, y pyright dice lo mismo con sus propias palabras. Un valor fuera de un conjunto falla de la misma forma, como status='sending-ish' en emails.list.

Existen para tu comprobador de tipos. En tiempo de ejecución, cada TypedDict es un dict simple, así que importar uno no cuesta nada y no se comprueba nada mientras el programa se ejecuta.

Cliente: Page, ApiKeyMode y RawBody. openemail.types.client añade AccessTokenProvider, AsyncAccessTokenProvider, HeaderValue y QueryValue.
Errores: ErrorType y FormFieldProblem.
Correos: EmailSend, EmailTranslate, EmailResource, SentEmailResource, EmailRecipientResource, EmailEventResource, EmailStatus, EmailSource, EmailTransport, EmailTrackingSummary, EmailTranslationResource, TranslationResource, RecipientStatus, BatchItemResource y BatchResultResource.
Plantillas: TemplateCreate, TemplatePatch, TemplateContent, TemplatePreviewInput, TemplateSend, TemplateResource, TemplateDetailResource, TemplateVersionResource, TemplatePreviewResource, TemplateSendsResource, SentTemplateEmailResource, DeletedTemplateResource, TemplateEngine, TemplateProp, TemplateSlot, TemplateStatus y TemplateValueKind.
Seguimiento: TrackingResource, TrackingSummary, TrackingRecipientResource, TrackingLinkResource, TrackingOpenResource, TrackingClickResource, TrackingStatsResource y TrackingGrain.
Conversaciones y borradores: ThreadPatch, ThreadResource, ThreadSummaryResource, UpdatedThreadResource, TrashedThreadResource, SnoozedThreadResource, DraftInput, DraftResource, DraftSummaryResource, SavedDraftResource y DeletedDraftResource.
Etiquetas, contactos, dominios y direcciones: LabelInput, LabelColor, LabelResource, DeletedLabelResource, ContactCreate, ContactPatch, ContactSource, ContactResource, ContactDetailResource, ContactAudienceResource, ContactAudiencesSet, DeletedContactResource, PeoplePage, PersonResource, DomainPatch, DomainResource, DomainDetailResource, DomainSendingState, DomainTracking, DomainTrackingState, AddressBookPage, AddressBookResource, AddressResource y SendableDomainResource.
Audiencias: AudienceCreate, AudiencePatch, AudienceMemberSort, AudienceContactAdd, AudienceContactsBatch, AudienceImport, AudienceImportRow, AudienceResource, AudienceBuiltin, AudienceContactResource, AudienceMemberResource, RemovedAudienceContactResource, DeletedAudienceResource, EmptiedAudienceResource, AudienceBatchAddResource, AudienceBatchRemoveResource, AudienceImportResource, AudienceGrowthResource, AudienceGrowthTotals, AudienceGrowthSeries y AudienceGrowthBucket.
Envíos masivos: BroadcastCreate, BroadcastPreviewInput, BroadcastResource, BroadcastCounts, BroadcastStatus, BroadcastPreviewResource, BroadcastRecipientResource, BroadcastRecipientContentResource, BroadcastRecipientFilter, BroadcastStatsResource, BroadcastStatsTotals y BroadcastStatsBucket.
Reglas: RuleCreate, RulePatch, RuleTestInput, RuleResource, RuleRunResource, RuleTestResource, DeletedRuleResource, RuleCondition, RuleConditionInput, RuleAction, RuleActionType, RuleField y RuleOperator.
Webhooks: WebhookCreate, WebhookPatch, WebhookResource, CreatedWebhookResource, DeletedWebhookResource, WebhookDeliveryResource, WebhookDeliveryDetailResource, WebhookDeliveryAttempt, WebhookReplayResource, WebhookReplayRefusal, WebhookReplayErrorCode, WebhookTestResource, WebhookEvent, WebhookPayload, EmailOpenedData, EmailClickedData, EmailDownloadedData y FileEventData.
Calendario y ajustes: CalendarOccurrenceResource, CalendarEventResource, CalendarAttendeeResource, SettingsPatch y SettingsResource.
Roles, miembros y claves: RoleCreate, RolePatch, RoleResource, DeletedRoleResource, PermissionResource, MemberAdd, MemberPatch, MemberAddressGrant, MemberResource, MemberAddressResource, RemovedMemberResource, MemberAccess, KeyResource y PingResource.
Buzones desechables: TempInboxCreate, TempInboxResource, CreatedTempInboxResource, DeletedTempInboxResource, TempDomainResource, TempMessageResource, TempMessagesResource, TempMessageDetailResource y DeletedTempMessageResource.
Compartidos: RecipientInput, AttachmentInput, AttachmentResource, MessageResource, MessageEncryption, MessageEncryptionFormat, TrackingRequest, TranslateOptions, SendTranslateOptions, LanguageResource, ApiScope, Permission, BuiltinRole, HitKind.
Tokens de acceso y códigos de verificación: CredentialKind, ApiKeySelfResource, OauthTokenSelfResource, ApiKeyPingResource, OauthTokenPingResource, StepUpBegin, StepUpVerify, StepUpMethod, StepUpErrorCode, StepUpStatusResource, StepUpChallengeResource y StepUpVerifiedResource.
Formularios: FormCreate, FormPatch, FormResource, FormDetailResource, FormDocument, FormField, FormCopy, FormStyle, FormSettings, FormSettingsInput, FormStats, FormAudience, FormStarterResource, FormStarterDetailResource, FormAnalyticsResource, FormSubmissionResource, FormAnswer, ResentFormConfirmationResource, FormSubscribeValues, FormSubscriptionResource, FormSubmittedEventData y FormConfirmedEventData.
Todo lo demás que devuelve la API, desde la facturación hasta los espacios de trabajo, tiene sus tipos con los mismos nombres.

Conjuntos de cadenas

Los conjuntos de valores son constantes en openemail.constants, cada una con el nombre de lo que contiene y un atributo por cada valor: EMAIL_STATUSES.SENT es 'sent'. Recorre uno para obtener todos sus valores, comprueba con in un valor que venga de fuera y cuéntalos con len(). Cada miembro está tipado como Final, así que mypy y pyright leen EMAIL_STATUSES.SENT como el literal 'sent' y lo aceptan dondequiera que se espere un 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']))

El propio openemail exporta 108 constantes: VERSION, LANGUAGES, PAGE_LIMITS, PAY_AS_YOU_GO_LIMITS_CENTS y 104 de los conjuntos, los que más usa una aplicación. Importa los demás, como EMAIL_STATUSES y TEMPLATE_STATUSES, desde openemail.constants, donde están todos los conjuntos.

Un endpoint que esto todavía no envuelve

Una versión del SDK nunca debería ser lo que te separa de un endpoint que ya funciona. client.raw.request() recibe una ruta y argumentos nombrados y devuelve el cuerpo ya analizado, aplicando la credencial, la URL base, el tiempo de espera y la política de reintentos del cliente.

escape_hatch.py

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

Un GET se reintenta como cualquier otra lectura. Cualquier otro método se envía una sola vez salvo que pases repeatable=True, que es tu afirmación de que puede enviarse dos veces. query omite los valores que son None o están vacíos, y api_key= y timeout= funcionan igual que en todos los demás métodos. En AsyncOpenEmail la llamada se hace con await.

La ruta debe empezar por una sola /. Cualquier otra cosa, y una ruta cuya URL final saldría del origen de la API, lanza ValueError antes de enviar la solicitud, así que la credencial nunca llega a otro host.

Lo que deliberadamente no hace

No valida ningún cuerpo de petición. El esquema del servidor es la única copia de las reglas, y una segunda copia aquí acabaría rechazando una dirección que un servidor más reciente acepta, en una versión que alguien fijó hace dos años.
Depende de httpx, anyio y typing-extensions, y de nada más.
Al salir solo convierte lo que JSON no puede representar tal cual: los bytes del content de un adjunto pasan a base64, un datetime pasa a ser un instante ISO 8601 en UTC, un date una fecha ISO y un set una lista. Un único destinatario en to, cc o bcc se envuelve en una lista.
Solo reestructura una respuesta de una manera: el array data de una colección se extrae de su envoltorio. Una lista paginada lo devuelve como items junto a hasMore y nextCursor; contacts.list_people, como items junto a hasMore, nextCursor y seen; emails.send_batch, como items junto a sent y failed; templates.list_sends, como items junto a total, page y pageSize; temp_mail.list_messages, como items junto a hasMore, nextCursor y expiresAt, y addresses.list, como addresses junto a unrestricted, domains, hasMore y nextCursor. imports.list_failures es la única lista que se deja tal como la envía la API, {'object': ..., 'data': [...], 'nextCursor': ...}. En todos los demás casos es una lista simple. Cada recurso que contiene conserva la forma HTTP documentada.

La comprobación de paridad del paquete garantiza que esto se cumpla. Ejecuta cada método junto a su equivalente en TypeScript, con los mismos argumentos y con todas las opciones definidas, y falla cuando falta un método, cuando acepta opciones distintas, envía una solicitud distinta o devuelve un valor distinto.