Api

Sibling-facing API for postal letter operations within the monolith.

list_letters

list_letters(*, query)

List letters filtered by provider metadata (e.g. user id).

Source code in components/emailing/subcomponents/postal_letter/protected/api.py

def list_letters(*, query: ListPostalLettersQuery) -> list[PostalLetterResult]:
    """List letters filtered by provider metadata (e.g. user id)."""
    return list_postal_letters(query)

retrieve_letter

retrieve_letter(*, letter_id, context)

Fetch letter status / payload from the provider.

Source code in components/emailing/subcomponents/postal_letter/protected/api.py

def retrieve_letter(*, letter_id: str, context: PostalContext) -> PostalLetterResult:
    """Fetch letter status / payload from the provider."""
    return retrieve_postal_letter(letter_id=letter_id, context=context)

send_letter

send_letter(request)

Send one postal letter using the provider configured for request.context.

Source code in components/emailing/subcomponents/postal_letter/protected/api.py

def send_letter(request: SendPostalLetterRequest) -> PostalLetterResult:
    """Send one postal letter using the provider configured for ``request.context``."""
    user_id = _user_id_from_metadata(request.metadata)
    if user_id is None:
        return send_postal_letter(request)

    postal_request = create_postal_request(
        user_id=user_id,
        postal_flow=request.context.use_case_key,
        recipient_address=_format_recipient_address(request.postal_address),
        extra_metadata=dict(request.metadata),
    )
    try:
        result = send_postal_letter(request)
    except PostalLetterError:
        current_session.rollback()
        raise

    update_postal_request(
        postal_request=postal_request,
        provider_letter_id=result.letter_id,
        provider_name=_provider_name_for_context(request.context),
        requested_at=date.today(),
    )
    current_session.commit()
    return result