docs(api): document provider settings.rate_limit [C-21732]

src/courier/resources/providers/providers.py

@@ -91,7 +91,17 @@ def create(
 
           settings: Provider-specific settings (snake_case keys). Defaults to an empty object when
               omitted. Use the catalog endpoint to discover required fields for a given
-              provider — omitting a required field returns a 400 validation error.
+              provider — omitting a required field returns a 400 validation error. Set
+              `rate_limit` to cap this configuration's send rate:
+              `{ "rate": <number greater than 0>, "period": "second" | "minute" | "hour" }`,
+              e.g. `{ "rate": 0.5, "period": "minute" }` for one send every 2 minutes. The
+              interval between sends (`period` divided by `rate`) must be from 1 millisecond
+              to 12 hours, otherwise the request returns a 400 `InvalidRateLimit` error. The
+              limit applies per configuration and per environment (a test-environment
+              configuration has its own limit). Sends above the rate are queued, not dropped,
+              and changes take up to 60 seconds to apply. It has no effect on observability or
+              CDP integrations, which do not send messages. Omit it or set it to null for no
+              limit.
 
           title: Optional display title. Omit to use "Default Configuration".
 
@@ -190,7 +200,16 @@ def update(
 
           settings: Provider-specific settings (snake_case keys). Replaces the full settings object
               — omitted settings fields are removed. Use the catalog endpoint to check
-              required fields.
+              required fields. Set `rate_limit` to cap this configuration's send rate:
+              `{ "rate": <number greater than 0>, "period": "second" | "minute" | "hour" }`,
+              e.g. `{ "rate": 0.5, "period": "minute" }` for one send every 2 minutes. The
+              interval between sends (`period` divided by `rate`) must be from 1 millisecond
+              to 12 hours, otherwise the request returns a 400 `InvalidRateLimit` error. The
+              limit applies per configuration and per environment (a test-environment
+              configuration has its own limit). Sends above the rate are queued, not dropped,
+              and changes take up to 60 seconds to apply. It has no effect on observability or
+              CDP integrations, which do not send messages. Omitting `rate_limit` or setting
+              it to null removes any existing limit, including one set in Studio.
 
           title: Updated display title.
 
@@ -354,7 +373,17 @@ async def create(
 
           settings: Provider-specific settings (snake_case keys). Defaults to an empty object when
               omitted. Use the catalog endpoint to discover required fields for a given
-              provider — omitting a required field returns a 400 validation error.
+              provider — omitting a required field returns a 400 validation error. Set
+              `rate_limit` to cap this configuration's send rate:
+              `{ "rate": <number greater than 0>, "period": "second" | "minute" | "hour" }`,
+              e.g. `{ "rate": 0.5, "period": "minute" }` for one send every 2 minutes. The
+              interval between sends (`period` divided by `rate`) must be from 1 millisecond
+              to 12 hours, otherwise the request returns a 400 `InvalidRateLimit` error. The
+              limit applies per configuration and per environment (a test-environment
+              configuration has its own limit). Sends above the rate are queued, not dropped,
+              and changes take up to 60 seconds to apply. It has no effect on observability or
+              CDP integrations, which do not send messages. Omit it or set it to null for no
+              limit.
 
           title: Optional display title. Omit to use "Default Configuration".
 
@@ -453,7 +482,16 @@ async def update(
 
           settings: Provider-specific settings (snake_case keys). Replaces the full settings object
               — omitted settings fields are removed. Use the catalog endpoint to check
-              required fields.
+              required fields. Set `rate_limit` to cap this configuration's send rate:
+              `{ "rate": <number greater than 0>, "period": "second" | "minute" | "hour" }`,
+              e.g. `{ "rate": 0.5, "period": "minute" }` for one send every 2 minutes. The
+              interval between sends (`period` divided by `rate`) must be from 1 millisecond
+              to 12 hours, otherwise the request returns a 400 `InvalidRateLimit` error. The
+              limit applies per configuration and per environment (a test-environment
+              configuration has its own limit). Sends above the rate are queued, not dropped,
+              and changes take up to 60 seconds to apply. It has no effect on observability or
+              CDP integrations, which do not send messages. Omitting `rate_limit` or setting
+              it to null removes any existing limit, including one set in Studio.
 
           title: Updated display title.
 

src/courier/types/provider.py

@@ -20,7 +20,12 @@ class Provider(BaseModel):
     """The provider key (e.g. "sendgrid", "twilio", "slack")."""
 
     settings: Dict[str, object]
-    """Provider-specific settings (snake_case keys on the wire)."""
+    """Provider-specific settings (snake_case keys on the wire).
+
+    `rate_limit` is this configuration's send rate limit,
+    `{ "rate": number, "period": "second" | "minute" | "hour" }`, or null for no
+    limit.
+    """
 
     title: str
     """Display title. Defaults to "Default Configuration" when not explicitly set."""

src/courier/types/provider_create_params.py

@@ -26,7 +26,16 @@ class ProviderCreateParams(TypedDict, total=False):
 
     Defaults to an empty object when omitted. Use the catalog endpoint to discover
     required fields for a given provider — omitting a required field returns a 400
-    validation error.
+    validation error. Set `rate_limit` to cap this configuration's send rate:
+    `{ "rate": <number greater than 0>, "period": "second" | "minute" | "hour" }`,
+    e.g. `{ "rate": 0.5, "period": "minute" }` for one send every 2 minutes. The
+    interval between sends (`period` divided by `rate`) must be from 1 millisecond
+    to 12 hours, otherwise the request returns a 400 `InvalidRateLimit` error. The
+    limit applies per configuration and per environment (a test-environment
+    configuration has its own limit). Sends above the rate are queued, not dropped,
+    and changes take up to 60 seconds to apply. It has no effect on observability or
+    CDP integrations, which do not send messages. Omit it or set it to null for no
+    limit.
     """
 
     title: str

src/courier/types/provider_update_params.py

@@ -23,7 +23,17 @@ class ProviderUpdateParams(TypedDict, total=False):
     """Provider-specific settings (snake_case keys).
 
     Replaces the full settings object — omitted settings fields are removed. Use the
-    catalog endpoint to check required fields.
+    catalog endpoint to check required fields. Set `rate_limit` to cap this
+    configuration's send rate:
+    `{ "rate": <number greater than 0>, "period": "second" | "minute" | "hour" }`,
+    e.g. `{ "rate": 0.5, "period": "minute" }` for one send every 2 minutes. The
+    interval between sends (`period` divided by `rate`) must be from 1 millisecond
+    to 12 hours, otherwise the request returns a 400 `InvalidRateLimit` error. The
+    limit applies per configuration and per environment (a test-environment
+    configuration has its own limit). Sends above the rate are queued, not dropped,
+    and changes take up to 60 seconds to apply. It has no effect on observability or
+    CDP integrations, which do not send messages. Omitting `rate_limit` or setting
+    it to null removes any existing limit, including one set in Studio.
     """
 
     title: str