Send an email to a distribution list
/distribution-lists/{distribution_list_id}/sendsEmails the list's active members and returns the send with a Location. Delivery completes after the response: it starts as queued, and status, email_count and failed_count update as it proceeds. deal_ids (up to 20 deals you can see) adds them to the email. A disabled template or a list with no active members returns 409 conflict. dry_run shows the count and sends nothing. Emits distribution_list_send.created. Sent email cannot be recalled.
Path parameters
The distribution list's id. Distribution lists are keyed by integer ids, not UUIDs. An unknown list, one in another organisation or a deleted one returns 404.
Query parameters
Validate and run the call without committing it, returning what the real call would return with
meta.dry_runset.
Headers
Makes a retry safe. Send a new UUID for each new request and reuse it only to retry that request; the first response is replayed for 24 hours.
Request body
application/json, required · DistributionListSendCreate
The email's subject line.
The email body, as HTML.
Deals to present in the email, each one you can see. Leave it out to send the body alone.
{
"subject": "Quarterly update",
"body": "<p>Our latest quarterly report is ready.</p>"
}Responses
{
"data": {
"id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"status": "queued",
"recipient_count": 1,
"email_count": 1,
"failed_count": 1,
"error": "string",
"deal_ids": [
"9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a"
],
"created_by": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"created_at": "2026-06-12T10:00:00+00:00",
"updated_at": "2026-06-12T10:00:00+00:00"
}
}Authorization failed. error.code is one of org_disabled,
ip_blocked, missing_scope, scope_disabled, user_disabled.
The request conflicts with existing state (error.code = conflict),
e.g. a compliance flow with the requested name already exists.
The request can't be processed (HTTP 422): validation_failed with one ErrorDetail per
problem, or a code documented on the operation.
Examples
curl -X POST https://your-org-domain/kong/core/api/v2/distribution-lists/{distribution_list_id}/sends\
-H "Authorization: Bearer $HELM_API_KEY"\
-H "Content-Type: application/json"\
-d '{
"subject": "Quarterly update",
"body": "<p>Our latest quarterly report is ready.</p>"
}'