Send email from Flask with one route.

1. Build the client once, in the factory.

   from_prefixed_env() reads FLASK_NOTIX_API_KEY into app.config. The client goes on app.extensions, where every blueprint can reach it through current_app and a test can replace it.

   acme/__init__.py

   # acme/__init__.py
   import os
   
   from flask import Flask
   from notix import Notix
   
   
   def create_app(test_config=None):
       app = Flask(__name__)
   
       # FLASK_NOTIX_API_KEY and FLASK_NOTIX_WEBHOOK_SECRET in the environment
       # become app.config["NOTIX_API_KEY"] and app.config["NOTIX_WEBHOOK_SECRET"].
       app.config.from_prefixed_env()
       if test_config:
           app.config.from_mapping(test_config)
   
       # One client per app; requests.Session reuse is built in.
       # raise_on_error=False returns (None, error) instead of raising.
       app.extensions["notix"] = Notix(app.config["NOTIX_API_KEY"], raise_on_error=False)
   
       # Pointing at a different Notix base URL (a staging environment, say)?
       # Notix(app.config["NOTIX_API_KEY"], url=app.config["NOTIX_URL"], raise_on_error=False)
   
       from acme import mail, webhooks
       app.register_blueprint(mail.bp)
       app.register_blueprint(webhooks.bp)
       return app
   

2. Send from a route.

   notix.emails.send takes the payload and, as the second argument, options with the idempotency key. It returns (data, err): on success keep emailId, on failure err is the API’s own {code, message} envelope and nothing was sent.

   RouteTest

   acme/mail.py

   from flask import Blueprint, current_app, jsonify, request
   
   bp = Blueprint("mail", __name__)
   
   
   @bp.post("/orders/<int:order_id>/receipt")
   def send_receipt(order_id):
       notix = current_app.extensions["notix"]
       body = request.get_json(force=True)
   
       data, err = notix.emails.send(
           {
               "from": "Acme <receipts@acme.com>",
               "to": body["email"],
               "templateId": "tpl_receipt_v4",
               "variables": {"orderId": str(order_id), "total": body["total"]},
           },
           # One key per business event: a client retry can never send twice.
           options={"idempotency_key": f"order-{order_id}-receipt"},
       )
   
       if err:
           # err is the API's own envelope: {"code": ..., "message": ...}
           status = 429 if err["code"] == "RATE_LIMITED" else 502
           return jsonify(error=err), status
   
       # Keep data["emailId"]: it is the key on every webhook event for this message.
       return jsonify(emailId=data["emailId"]), 202
   

3. Receive delivery events.

   The route above answers when the message is queued. Delivered, bounced and complained arrive later on a webhook. Verify with the raw body from request.get_data(); a re-serialised JSON body no longer matches the signature.

   acme/webhooks.py

   # acme/webhooks.py
   from flask import Blueprint, current_app, request
   from notix.webhooks import WebhookVerificationError
   
   bp = Blueprint("webhooks", __name__)
   
   
   @bp.post("/webhooks/notix")
   def notix_webhook():
       notix = current_app.extensions["notix"]
       webhooks = notix.webhooks(current_app.config["NOTIX_WEBHOOK_SECRET"])
   
       try:
           # get_data() is the raw body; the signature covers exactly those bytes.
           # Never re-serialise request.get_json(): it no longer matches.
           event = webhooks.construct_event(request.get_data(), headers=request.headers)
       except WebhookVerificationError as error:
           return str(error), 400
   
       email_id = event["data"]["id"]
       if event["type"] == "email.delivered":
           mark_receipt(email_id, "delivered")
       elif event["type"] == "email.bounced" and event["data"]["bounce"]["type"] == "Permanent":
           mark_receipt(email_id, "bounced")   # the address is now suppressed by Notix
   
       return "ok", 200
   

Register the webhook URL in the dashboard and copy its secret into FLASK_NOTIX_WEBHOOK_SECRET. Answer 200 fast; a non-2xx reply is retried with backoff. The scheme is on the webhook signature page.