Sending Email
Send transactional email from a workflow using your own provider and an event-driven handoff
Current Bifrost has no built-in email SDK and no Settings → Email page. The
bifrost.email module, platform email configuration, and POST /api/email/send
were removed in Bifrost PR #273,
before the v1.0.0 release. They are absent from both v1.0.0 and v1.0.5.
Email delivery is now an ordinary workflow responsibility: call your provider from
a workflow, and trigger that workflow with an event.
Store the provider credentials
Section titled “Store the provider credentials”Keep the sender and API key in configuration rather than in source. A global secret is the usual choice for a shared notification workflow; use an organization-scoped value when a single customer has its own sender.
bifrost configs set smtp2go_api_key --value "<api-key>" --type secret --globalbifrost configs set smtp2go_from_address --value "notifications@example.com" --type string --globalRead them inside the workflow with config.get(). The value resolves through the
organization → global cascade. See Configuration and
Storing Sensitive Config Values.
Create the topic source
Section titled “Create the topic source”Create a Topic event source named email.send_requested. The topic string must
contain a dot. See Create an Event Source
and Events.
Then subscribe your workflow to that source. The workflow below reads the full event
body from _event, so no input mapping is required. If you prefer mapped parameters,
map {{ payload.to }} and the other fields instead.
Write the sending workflow
Section titled “Write the sending workflow”from bifrost import config, context, workflowimport httpx
@workflow(category="Notifications", tags=["email", "notifications"])async def send_email_requested(): """Send one email from an email.send_requested topic event.""" event = context.parameters.get("_event", {}) data = event.get("body") or {}
recipients = data.get("to") or [] subject = data.get("subject") body = data.get("body") if not recipients or not subject or not body: raise ValueError("Email event requires to, subject, and body")
api_key = await config.get("smtp2go_api_key") sender = await config.get("smtp2go_from_address") if not api_key or not sender: raise RuntimeError("Email provider is not configured")
async with httpx.AsyncClient(timeout=30) as client: response = await client.post( "https://api.smtp2go.com/v3/email/send", headers={"X-Smtp2go-Api-Key": str(api_key)}, json={ "sender": str(sender), "to": recipients, "subject": subject, "text_body": body, "fastaccept": True, }, ) response.raise_for_status() result = response.json().get("data", {}) if result.get("error") or result.get("error_code") or result.get("failed") or result.get("failures"): raise RuntimeError("Email provider rejected all or part of the request") if not result.get("email_id"): raise RuntimeError("Email provider did not confirm acceptance")
return {"accepted": True, "email_id": result["email_id"]}SMTP2GO can return HTTP 200 with processing failures, so the example also checks
its response body. With fastaccept, success means the provider accepted the
message for background processing. Use provider delivery webhooks or logs to
confirm arrival; Bifrost execution success alone does not prove delivery. See the
SMTP2GO send API.
Emit the event
Section titled “Emit the event”Any workflow, form, app server route, or agent tool can request an email without knowing which provider is configured:
from bifrost import events, workflow
@workflowasync def request_invoice_email(recipient: str, invoice_url: str): """Queue an invoice-ready email through the topic workflow.""" await events.emit("email.send_requested", { "to": [recipient], "subject": "Your invoice is ready", "body": f"Download your invoice here: {invoice_url}", }) return {"queued": True}events.emit() returns after publishing and queuing the event, without waiting
for the sending workflow to finish. The sending workflow runs in its own
organization scope, not the event source’s scope. An organization-scoped workflow
therefore reads that organization’s configuration; a global workflow reads global
configuration. To use a customer’s sender, scope the sending workflow to that
customer’s organization. Check the source’s delivery log and workflow execution
history for processing status, and the provider’s delivery records for arrival.
Why an event instead of a direct call
Section titled “Why an event instead of a direct call”The event boundary keeps the sender deployable and replaceable: one workflow owns the
provider credentials and retry behavior, while callers only publish a message. It also
matches the platform’s current direction for built-in notifications such as
user.invited.
Related
Section titled “Related”- Events — source types and built-in topics
- Subscribe a Workflow or Agent — routing and filters
- Webhook & Event Variables — the
_eventpayload - Writing Workflows — workflow structure