Configuration

These raise ValueError, or TypeError where the table says so, before any request is sent, rather than surfacing as a confusing failure on your first send. The message says what was wrong and what to pass instead.

Build the client once and share it. A fresh instance per request throws away the connection pool and the configuration for nothing, and none of the state on it is per-caller.

One client is safe to share between threads. close() or the end of a with block closes the connection pool it opened, and an http_client you passed stays open for you to close.

For the case that would otherwise force one instance per key, such as a job sending on behalf of several workspaces, pass api_key on the call. It replaces the Authorization header for that request and leaves nothing behind on the client.

from openemail.types import EmailSend workspace_key = 'oe_live_...' message: EmailSend = {'from': sender, 'to': recipient, 'subject': subject, 'text': text} client.emails.send(message) client.emails.send(message, api_key=workspace_key) client.threads.list(folder='inbox', api_key=workspace_key)client.webhooks.list(api_key=workspace_key)

Every method outside temp_mail takes it as a keyword argument, beside timeout. It is checked before the request is sent, by the same rule the constructor uses, so a typo raises a ValueError naming api_key= on this call rather than a 401 about a credential you then have to go and find. A retried call keeps the key it was given.

timeout is in seconds and replaces the client’s timeout for that one call, on each of its attempts.

client.raw.request sends a request with the client’s credential, base URL, timeout and retry policy applied, and returns the parsed JSON. It takes method, query, body, api_key and timeout. It retries a GET and sends anything else once, unless you pass repeatable=True. idempotent=True adds an Idempotency-Key, the one you pass as idempotency_key or a fresh one.

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

create_temp_mail() builds a client that carries no API key, and create_async_temp_mail() is its asynchronous twin. It creates inboxes anonymously, and each read sends the inbox token that create returned, or the newer one extend returned, either per call as inbox_token or once as create_temp_mail(inbox_token=...).

from openemail import create_temp_mail temp_mail = create_temp_mail() inbox = temp_mail.create()messages = temp_mail.list_messages(inbox['id'], inbox_token=inbox['token']) print(messages['items'], messages['expiresAt'])

An app a person connected over OAuth, such as a command line tool or an agent, holds an access token rather than an API key. Pass it as access_token, either the token itself, or a function that returns it, which on AsyncOpenEmail may be async. The function is called once for every call, and that call’s retries reuse what it returned, so renew the token inside it when it is close to expiring and the client never has to be rebuilt.

from openemail import OpenEmail client = OpenEmail(access_token=session.fresh_access_token) me = client.me.get() if me['object'] == 'oauth_token':    print(me['clientId'], me['expiresAt'])

Before a sensitive change, such as deleting a domain or changing a webhook, the API asks an access token for the verification code the web app would ask the person for. The call raises an OpenEmailApiError whose is_step_up_required is True, and nothing was changed. Ask for a code, verify the one the person gives you, then make the call again. An API key is never asked.

from openemail import OpenEmailApiError try:    client.domains.delete(domain_id)except OpenEmailApiError as error:    if not error.is_step_up_required:        raise     challenge = client.security.begin_step_up()     if challenge['method'] == 'email':        prompt = f'Enter the code we emailed to {challenge.get("sentTo")}: '    else:        prompt = 'Enter the code from your authenticator app, or a backup code: '     client.security.verify_step_up({'code': input(prompt)})    client.domains.delete(domain_id)