> ## Documentation Index
> Fetch the complete documentation index at: https://sendmux.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Delivery groups

> Group sending providers, scope credentials, and restrict individual messages to authorised groups.

Delivery groups let you route a sending key or mailbox through a named set of providers. Use them to separate traffic by product, region, customer, or risk profile.

## How routing works

The key or mailbox you authenticate with defines the providers available to you. An optional per-message delivery-group hint narrows that selection.

| Scope | Result |
| - | - |
| **All active providers** | Qubrics can use any active provider on the team. |
| **Specific providers** | Qubrics can use only the providers selected on the key. |
| **Delivery group** | Qubrics can use only providers in the selected group. |

Groups have no activation setting. Their availability depends on eligible member providers, including provider status and sending limits. An empty eligible pool never falls back to providers outside the requested groups.

## Restrict one message

For HTTP, set `delivery_group` to one group public ID or a nonempty array in the send body. In a batch, set it on each message. For SMTP, use one `X-Qubrics-Delivery-Group` header with comma-separated public IDs.

Qubrics trims surrounding whitespace, removes duplicate IDs, and accepts at most 50 groups. Empty entries are invalid. SMTP also rejects repeated occurrences of the header and strips the header before delivery. HTTP callers must use the dedicated field; the header is reserved in `custom_headers`.

The credential's scope determines how the hint is applied:

| Credential scope | Hint behaviour |
| - | - |
| **All active providers** (`all`) | Select only eligible providers in the requested team-owned groups. |
| **Delivery group(s)** (`group`) | Requested IDs must be a subset of the credential's groups. |
| **Specific providers** (`providers`) | Reject the hint. |
| Shared-domain override | Ignore the hint and retain the forced route, with a warning. |
| No hint | Retain the credential's existing routing behaviour. |

Shared-domain routing takes precedence, even if the hint is malformed. Otherwise, Qubrics validates syntax, credential scope and group subset, then team-owned existence. A valid group ID from another team is treated as unknown.

Routing failures use these codes:

| Condition | HTTP status and code | SMTP |
| - | - | - |
| Malformed or ambiguous hint | `422 invalid_delivery_group` | Permanent `550` |
| Unknown or other-team group | `422 delivery_group_not_found` | Permanent `550` |
| Outside the credential's groups | `403 delivery_group_not_allowed` | Permanent `550` |
| Provider-scoped credential | `422 delivery_group_scope_invalid` | Permanent `550` |

Batch responses retain errors at each message's input index, including when every message fails routing. Temporary service failures remain retryable.

Delivery logs expose the applied public IDs in nullable `delivery_group`. Absent, ignored, and historical hints have `null`. Later status updates preserve the applied groups.

## Create a group

**1. Open Accounts**

Open **Accounts**, then select **Groups**.

**2. Create the group**

Add a group name. You can edit the name and description later.

**3. Add providers**

Edit a provider and choose the delivery group in **Advanced Settings**.

> [!TIP]
>
> CSV imports can create a group and assign an account in one step with the
> `group_name` column. See [Sending accounts](https://sendmux.ai/docs/sending/accounts#import-accounts-from-a-file).

## Route a sending key

Create or edit a sending key and choose **Delivery group(s)** under sending scope. Select one or more groups.

If none of the selected groups has an eligible provider, sends through that key fail until a provider is added or becomes eligible again.

## Route a mailbox

Use a mailbox's send scope to bind it to a delivery group. Every API or SMTP send authenticated as that mailbox follows the mailbox scope.

## Delete a group

Deleting a group moves its providers to **No group**. Qubrics warns when API keys depend on the group so you can update their send scope first.

## Related guides

> [card] [Sending accounts](https://sendmux.ai/docs/sending/accounts)
>
> Add providers and tune quotas, sender defaults, and weights.

> [card] [API keys](https://sendmux.ai/docs/account/api-keys.md)
>
> Create sending keys and choose their send scope.

> [card] [Mailboxes](https://sendmux.ai/docs/mailboxes)
>
> Scope mailbox sending to a selected provider group.

> [card] [Send by HTTP](https://sendmux.ai/docs/sending/http.md)
>
> Send messages with a key that already has the right route.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.