compose.compose_email

compose.compose_email(
    body=None,
    header=None,
    footer=None,
    title=None,
    template='blastula',
    **kwargs,
)

Compose an email message using simple building blocks or Markdown.

This is the primary entry point for creating emails in nbmail. It accepts optional header, body, and footer sections, processes them into MJML, and returns an Email object ready for preview or sending.

Parameters

body : Optional[Union[str, Block, BlockList]] = None: Main email content. Can be a Markdown string, single Block, or blocks() result.
header : Optional[Union[str, Block, BlockList]] = None: Optional header section (appears at top).
footer : Optional[Union[str, Block, BlockList]] = None: Optional footer section (appears at bottom).
title : Optional[str] = None: Large title/header text to display at the top of the email. If provided, this creates a block_title() in the header section. Note: This is NOT the email subject line; use email metadata for that.
template : str = 'blastula': Email template style. Default is “blastula”, which wraps content in a grey border container (similar to Blastula’s html_email_template_1). Use "none" for no template wrapper.
****kwargs** : = {}: Additional template options (reserved for future use).

Returns

: Email: Converted Email object ready for preview or sending.

Examples

Simple email with single block:

from nbmail.compose import compose_email, block_text

compose_email(
    body=block_text("This is a simple email.")
)

This is a simple email.

Email with title/header and multiple blocks:

from nbmail.compose import compose_email, create_blocks, block_title, block_text

compose_email(
    title="Welcome!",
    body=block_text("Welcome to this week's update!"),
)

Welcome!

Welcome to this week's update!

Email with header section and body:

from nbmail.compose import compose_email, create_blocks, block_title, block_text

compose_email(
    header=create_blocks(block_title("Newsletter")),
    body=create_blocks(
        block_text("Welcome to this week's update!"),
        block_text("Here's what's new...")
    ),
    footer=create_blocks(block_text("© 2025 My Company"))
)

Welcome to this week's update!

Here's what's new...