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

# Create smart delivery rule

> Create a custom smart delivery rule that limits how often a contact receives messages.

**name** `string` *required*

Name of the rule. Max 255 characters.

**description** `string`

Description of the rule. Max 1000 characters.

**applicability** `string` (default: both)

Where the rule can be used. Allowed values: `campaign`, `pipeline`, `both`.

**limits** `object` *required*

The limits of the rule. Send `null` or omit a field to switch that limit off.

**limits properties**

**limits\[priority\_window\_hours]** `integer`

Skip a contact who received a message in the last N hours. Range `0`–`24`. Requires `priority_scope`.

**limits\[priority\_scope]** `string`

Which messages count for `priority_window_hours`. Allowed values: `all`, `campaigns`, `pipelines_all`, `pipelines_other`.

**limits\[frequency\_cap\_email\_count]** `integer`

Maximum number of e-mails a contact can receive in `frequency_cap_email_days` days. Range `1`–`50`.

**limits\[frequency\_cap\_email\_days]** `integer`

Length of the e-mail frequency cap period in days. Range `1`–`7`.

**limits\[frequency\_cap\_email\_scope]** `string`

Which e-mails count for the e-mail frequency cap. Allowed values: `all`, `campaigns`, `pipelines_all`, `pipelines_other`.

**limits\[frequency\_cap\_sms\_count]** `integer`

Maximum number of SMS messages a contact can receive in `frequency_cap_sms_days` days. Range `1`–`50`.

**limits\[frequency\_cap\_sms\_days]** `integer`

Length of the SMS frequency cap period in days. Range `1`–`7`.

**limits\[frequency\_cap\_sms\_scope]** `string`

Which SMS messages count for the SMS frequency cap. Allowed values: `all`, `campaigns`, `pipelines_all`, `pipelines_other`.

> [!NOTE]
>
> Each frequency cap is all or nothing: when you send one of its three fields (`count`, `days`, `scope`), you must send the other two.
> The scope `pipelines_other` means "other automations than the one that sends the message", so it applies only to automation actions.
> An account can have at most 50 custom rules.

```bash cURL theme={null}
curl -X POST https://api2.ecomailapp.cz/smart-delivery/rules \
  -H "key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekend",
    "description": "Weekend sends",
    "applicability": "campaign",
    "limits": {
      "priority_window_hours": 12,
      "priority_scope": "all",
      "frequency_cap_email_count": 2,
      "frequency_cap_email_days": 7,
      "frequency_cap_email_scope": "all"
    }
  }'
```

```php PHP theme={null}
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api2.ecomailapp.cz/smart-delivery/rules');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'key: YOUR_API_KEY',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'name' => 'Weekend',
    'description' => 'Weekend sends',
    'applicability' => 'campaign',
    'limits' => [
        'priority_window_hours' => 12,
        'priority_scope' => 'all',
        'frequency_cap_email_count' => 2,
        'frequency_cap_email_days' => 7,
        'frequency_cap_email_scope' => 'all',
    ],
]));
$response = curl_exec($ch);
curl_close($ch);
```

```json 201 theme={null}
{
  "success": true,
  "data": {
    "id": "aB3dE5fG7h",
    "name": "Weekend",
    "description": "Weekend sends",
    "is_system": false,
    "applicability": "campaign",
    "limits": {
      "priority_window_hours": 12,
      "priority_scope": "all",
      "frequency_cap_email_count": 2,
      "frequency_cap_email_days": 7,
      "frequency_cap_email_scope": "all",
      "frequency_cap_sms_count": null,
      "frequency_cap_sms_days": null,
      "frequency_cap_sms_scope": null
    },
    "usage": null
  }
}
```

```json 422 theme={null}
{
  "success": false,
  "message": "Validation errors",
  "data": {
    "limits.frequency_cap_email_days": ["The limits.frequency cap email days field is required when limits.frequency cap email count / limits.frequency cap email scope is present."],
    "limits.frequency_cap_email_scope": ["The limits.frequency cap email scope field is required when limits.frequency cap email count / limits.frequency cap email days is present."]
  }
}
```

```json 422 theme={null}
{
  "success": false,
  "message": "You have reached the maximum number of custom sending policies."
}
```


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