imio.emailkit

Errors

Every error here is raised deliberately, and every one exists to replace a silent failure that happened at least once. The shape of the hierarchy follows one rule: fail loud, never drop.

from imio.emailkit.interfaces import (
    AttachmentError,
    EmailkitError,
    RecipientError,
    TemplateNotFound,
)

The hierarchy

  • Name
    EmailkitError
    Type
    Exception
    Description

    Base class of every error this package raises deliberately. Catch this if you want all of them and nothing else.

  • Name
    TemplateNotFound
    Type
    EmailkitError
    Description

    No template is registered under the requested name. Carries the list of names that are registered — the mistake is nearly always a typo or a forgotten entry point, and both are obvious once the list is in front of you.

  • Name
    RecipientError
    Type
    EmailkitError
    Description

    One or more recipients could not be resolved. Raised at .send(), listing every one that failed and saying why each failed.

  • Name
    AttachmentError
    Type
    EmailkitError
    Description

    One or more attachments could not be resolved — an unreadable source, or a missing filename / mimetype that could not be inferred. Raised at .send().

Why they all arrive at .send()

RecipientError and AttachmentError are raised at .send(), not when you called .to() or .attach(). TemplateNotFound likewise — Email("typo") is legal and silent until you send it.

Two reasons, and both are deliberate:

  1. One place where things fail, one place to look. The builder holds data; it does not validate incrementally.
  2. Every problem, not the first one. A caller who mistyped three userids should learn about three, not fix one and run again. So resolution collects problems and raises once.

Resolution also happens before the first render, so a mistyped userid does not surface only after half the language groups have already been queued.

What is not an error

  • Name
    A missing plaintext twin
    Description

    render() falls back to a naive text extraction of the HTML and logs a deprecation. The mail still sends. See render().

  • Name
    An unset theme record
    Description

    A missing registry, a missing record and None all collapse to the empty string. A token is interpolated straight into markup, and the string "None" in a mail is worse than nothing.

  • Name
    A missing fixture in the preview view
    Description

    Reported as a plain fact rather than an error. An egg installed without its source tree is the normal production case, and the preview simply has nothing to show for that template there.