Working with Email Flows

Email flows are automated sequences of emails sent to subscribers. The package provides functions to subscribe recipients, manage subscriptions, and work with recipient data.

Subscribing to a Flow

Use subscribe_to_flow() to add a recipient to an email flow. The recipient will be created automatically if they don’t already exist.

from notifiedby import subscribe_to_flow

subscribe_to_flow(
    flow_trigger='WELCOME_SIGNUP',
    email='user@example.com',
    first_name='John',
    last_name='Doe',
    flags=['new_user', 'free_plan']
)

Parameter	Required	Description
flow_trigger	Yes	The trigger keyword of the flow.
email	Yes	The recipient’s email address.
first_name	No	The recipient’s first name.
last_name	No	The recipient’s last name.
flags	No	A list of flag names to set on the recipient.
client	No	A custom NotifiedByClient instance (see email_flows/django_package:Using a Custom Client).

A common pattern is to subscribe users when they sign up, using a Django signal:

from django.db.models.signals import post_save
from django.dispatch import receiver
from django.contrib.auth.models import User
from notifiedby import subscribe_to_flow

@receiver(post_save, sender=User)
def on_user_created(sender, instance, created, **kwargs):
    if created:
        subscribe_to_flow(
            flow_trigger='WELCOME_SIGNUP',
            email=instance.email,
            first_name=instance.first_name,
            last_name=instance.last_name,
        )

Unsubscribing from a Flow

Use unsubscribe_from_flow() to stop a recipient from receiving further emails in a flow.

from notifiedby import unsubscribe_from_flow

unsubscribe_from_flow(
    flow_trigger='WELCOME_SIGNUP',
    email='user@example.com'
)

Listing Flow Subscriptions

Use list_flow_subscriptions() to retrieve all flow subscriptions for your team. Results are paginated.

from notifiedby import list_flow_subscriptions

result = list_flow_subscriptions(page=1)

print(f"Total subscriptions: {result['count']}")

for sub in result['results']:
    print(f"{sub['recipient_email']} - {sub['flow_name']} ({sub['status']})")

Each subscription in the results contains:

Field	Description
id	The subscription ID.
flow_name	The human-readable name of the flow.
flow_trigger	The trigger keyword of the flow.
recipient_email	The subscribed recipient’s email address.
status	One of active, completed, or cancelled.
current_step_order	The current step number in the sequence.
next_send_date	When the next step will be processed.
created_at	When the subscription was created.
updated_at	When the subscription was last updated.

Deleting All Subscriptions

Use delete_all_subscriptions() to remove all flow subscriptions for your team.

from notifiedby import delete_all_subscriptions

delete_all_subscriptions()

Warning

This deletes all subscriptions for your team and cannot be undone. Use with caution.

Managing Recipients

You can create and list recipients independently of flows.

Creating a Recipient

from notifiedby import create_recipient

recipient = create_recipient(
    email='user@example.com',
    first_name='John',
    last_name='Doe',
    flags=['premium', 'active']
)

If a recipient with that email already exists, their details will be updated.

Listing Recipients

from notifiedby import list_recipients

recipients = list_recipients()
for r in recipients:
    print(f"{r['email']} - {r['first_name']} {r['last_name']}")

Managing Recipient Flags

Flags let you tag recipients for segmentation and flow branching. You can set and clear flags at any time.

Setting Flags

from notifiedby import set_recipient_flags

set_recipient_flags(
    email='user@example.com',
    flags=['premium', 'onboarded']
)

Clearing Flags

from notifiedby import clear_recipient_flags

clear_recipient_flags(
    email='user@example.com',
    flags=['trial']
)