Backfill Payout Link Delivery Methods

The delivery-method backfill tool lets you change how payout links notify recipients — for example, migrating a batch of email-based links to SMS delivery. Use this to correct delivery configuration or switch methods after payout links have already been created.

This is an internal tooling endpoint intended for workspace operators and administrators. It does not change what recipients can choose during claim — it changes how Dots delivers the payout link notification itself.

When to Use Backfill

Use the backfill tool when you need to:

Switch a group of payout links from email delivery to SMS (or vice versa)
Add an additional delivery method to links that previously used only one channel
Re-send notifications after correcting a delivery configuration issue

The tool processes existing payout links in bulk and updates their delivery method, then sends new notifications through the channels you specify.

Request Parameters

The backfill endpoint accepts the following fields:

Field	Type	Default	Description
`api_app_id`	UUID string	Required	The API app whose payout links to process.
`dry_run`	boolean	`true`	If true, simulates the backfill without sending notifications or updating records.
`limit`	integer	None	Maximum number of payout links to process. Minimum 1.
`payout_link_ids`	array of UUIDs	None	Specific payout link IDs to target. If omitted, matches all links for the app based on `current_delivery_methods`.
`current_delivery_methods`	array	`["email"]`	Filter to links currently using these delivery methods. Options: `"email"`, `"sms"`, `"link"`, `"all"`.
`delivery_methods_to_send`	array	`["sms"]`	Which delivery channels to use after backfill. Options: `"email"`, `"sms"`.
`force_resend_existing_methods`	boolean	`false`	If true, re-sends notifications even for delivery methods the link already had.

Dry-Run Mode

By default, dry_run is true. In dry-run mode:

The endpoint calculates which links would be processed and skipped
No email or SMS notifications are sent
Payout link delivery records are not updated
Notification counts are not incremented

Always run a dry-run first to verify the affected links before executing the real backfill.

Delivery Method Filtering

The current_delivery_methods filter determines which existing links are eligible for backfill:

"email" — Links that currently deliver via email only
"sms" — Links that currently deliver via SMS only
"link" — Links with no explicit email or SMS delivery configured
"all" — Links that use both email and SMS

After backfill, the link's final delivery method is normalized:

Email + SMS → "all"
Email only → "email"
SMS only → "sms"
Neither → "link"

Force Resend Behavior

By default, the backfill skips delivery methods a link already has. For example, if a link currently uses SMS and you request SMS delivery, it will be skipped to avoid duplicate notifications.

Set force_resend_existing_methods to true to override this and re-send notifications even for methods already configured on the link.

Response Format

The response includes counts and per-link details:

{
  "success": true,
  "dry_run": true,
  "api_app_id": "uuid-string",
  "current_delivery_methods": ["email"],
  "delivery_methods_to_send": ["sms"],
  "force_resend_existing_methods": false,
  "processed_count": 42,
  "skipped_count": 8,
  "processed": [
    {
      "payout_link_id": "uuid-string",
      "existing_delivery_methods": ["email"],
      "delivery_methods_to_send": ["sms"],
      "final_delivery_method": "all",
      "skipped_delivery_methods": [],
      "email_message_id": null,
      "sms_message_id": null
    }
  ],
  "skipped": [
    {
      "payout_link_id": "uuid-string",
      "reason": "no_new_delivery_methods_to_send"
    }
  ]
}

In non-dry-run mode, email_message_id and sms_message_id contain the message IDs for sent notifications.

Understanding Skip Reasons

Links may be skipped for the following reasons:

Reason	Meaning
`delivery_method_not_selected`	The link's current delivery method did not match the `current_delivery_methods` filter.
`terminal_status`	The payout link has already been claimed or is in a final state that cannot be modified.
`no_new_delivery_methods_to_send`	The requested delivery methods were already configured on this link and `force_resend_existing_methods` was false.
`no_sendable_delivery_methods`	No valid delivery methods remained after filtering.

Running a Backfill

To execute a delivery-method backfill:

Start with dry-run — Set dry_run: true and your filter criteria to preview affected links.
Review processed and skipped counts — Verify the counts match your expectations.
Inspect skip reasons — Confirm skipped links were excluded for the right reasons.
Execute the real backfill — Set dry_run: false to apply changes and send notifications.
Check message IDs — After execution, each processed link includes email_message_id and/or sms_message_id confirming delivery.

Next Steps

Learn about Getting Started with the Dots Dashboard
See how recipients claim a payout link

Was this helpful?