Define an audience with its resolution strategy.

Options

• :from_context - Extract from context.data. Can be:

  • An atom: from_context: :user extracts context.data.user
  • A list of atoms: from_context: [:user, :assignee] tries each key until non-nil

• :extract - When using from_context with a collection, extract this field from each item. Example: from_context: [:meeting, :participants], extract: :user

• :filter - Filter extracted recipients by field values. Only recipients matching ALL conditions are included. Works with from_context, query, and path. Example: from_context: :user, filter: [user_type: :customer, is_active: true]

• :from_resource - Extract email/name fields directly from the event's resource. Creates a raw recipient map without needing a custom resolver function. Example: from_resource: [email: :contact_email, name: :contact_name] Required keys: :email. Optional: :name, :id. If :id is not specified, uses the resource's :id field.

• :query - Ash filter to query user_resource. Example: query: [role: :admin, is_active: true]

• :path - Relationship path to follow from the resource. Example: path: [:customer, :customer_users, :user]

• :combine - Union of other audiences (deduped by id). Example: combine: [:owner, :team]

• :resolve - Custom resolver function. Can be:

  • An atom: function name in this module, called as function_name(resource, context)
  • A tuple: {Module, :function} or {Module, :function, extra_args}

• :raw - When true, skip to_recipient/1 conversion. Use for audiences that return pre-formatted recipient maps instead of user structs. Default: false

Examples

# Extract from context
audience :user, from_context: :user

# Try multiple context keys
audience :assignee, from_context: [:user, :assignee]

# Extract field from collection
audience :participants, from_context: [:meeting, :participants], extract: :user

# Filter extracted recipients by field values
audience :customer, from_context: [:customer_user, :user], filter: [user_type: :customer]

# Extract email/name from resource fields (no custom resolver needed!)
audience :lead_contact, from_resource: [email: :contact_email, name: :contact_name]

# Query users
audience :admins, query: [role: :admin, is_active: true]

# Follow relationship path
audience :customer_users, path: [:customer, :users]

# Combine audiences
audience :stakeholders, combine: [:owner, :team]

# Custom resolver
audience :owner, resolve: :resolve_owner

# Custom resolver returning raw maps (use from_resource instead when possible)
audience :lead_contact, resolve: :resolve_lead_contact, raw: true

Define audiences block.

All audience definitions must be inside this block.