sendly 3.34.0__tar.gz → 3.37.0__tar.gz

{sendly-3.34.0 → sendly-3.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sendly
-Version: 3.34.0
+Version: 3.37.0
 Summary: Official Sendly Python SDK for SMS messaging
 Project-URL: Homepage, https://sendly.live
 Project-URL: Documentation, https://sendly.live/docs
@@ -402,6 +402,13 @@ print(f"Credits used: {usage['creditsUsed']}")
 result = client.account.create_api_key('Production Key')
 print(f"New key: {result['key']}")  # Only shown once!
 
+# Rotate an API key (old key keeps working for a 24h grace period by default)
+rotation = client.account.rotate_api_key('key_xxx')
+print(f"New key: {rotation['newKey']['key']}")  # Only shown once!
+
+# Rotate with a wider overlap window (24-168 hours)
+rotation = client.account.rotate_api_key('key_xxx', grace_period_hours=72)
+
 # Revoke an API key
 client.account.revoke_api_key('key_xxx')
 ```
@@ -431,6 +438,23 @@ owned = client.numbers.list()
 for num in owned.numbers:
     print(f'{num.phone_number} ({num.status})')
 
+# Get one owned number (includes whether it's your default sender)
+number = client.numbers.get('num_xxx')
+print(f'{number.phone_number} default={number.is_default}')
+
+# Make a number your default sender
+client.numbers.update('num_xxx', is_default=True)
+
+# Cancel a scheduled release and keep the number
+client.numbers.update('num_xxx', pending_cancellation=False)
+
+# Release a number (a paid number is kept until the end of the billed period)
+result = client.numbers.release('num_xxx')
+if result.scheduled:
+    print(f'Releases at {result.scheduled_release_at}')
+else:
+    print('Released')
+
 # Buy a number
 chosen = available.numbers[0]
 result = client.numbers.buy(
@@ -457,6 +481,103 @@ elif result.status in ('documents_required', 'payment_required'):
     )
 ```
 
+## 10DLC (Local Number Texting)
+
+Register your business for carrier review so you can text from local
+(10-digit) US numbers. Requires an API key with the `tendlc:read` /
+`tendlc:write` scopes; writes need a live key. The flow has three steps:
+brand → campaign → assign a number.
+
+```python
+# 1. Register a brand and poll until it's verified
+brand = client.ten_dlc.create_brand(
+    legal_name='Acme Holdings LLC',
+    ein='12-3456789',
+    website='https://acme.example',
+    email='ops@acme.example',
+).data
+# ...poll client.ten_dlc.get_brand(brand.id) until brand.status == 'verified'
+# (or 'failed', with brand.failure_reasons explaining why)
+
+# 2. Pre-check the use case, then create a campaign
+check = client.ten_dlc.qualify(brand.id, 'MIXED').data
+if check.qualified:
+    campaign = client.ten_dlc.create_campaign(
+        brand_id=brand.id,
+        use_case='MIXED',
+        description='Order updates and support replies for Acme customers',
+        message_flow='Customers opt in at checkout on acme.example',
+        sample_messages=['Your order #123 has shipped!'],
+        opt_out_keywords='STOP',
+    ).data
+    # ...poll client.ten_dlc.get_campaign(campaign.id) until status == 'active'
+
+    # 3. Assign a number you own; it can send once the assignment is 'Active'
+    assignment = client.ten_dlc.assign_number(campaign.id, '+15551234567').data
+    print(assignment.status)
+
+# List what you have registered
+brands = client.ten_dlc.list_brands()
+campaigns = client.ten_dlc.list_campaigns()
+assignments = client.ten_dlc.list_assignments()
+```
+
+## Group MMS
+
+Send one message to 2-8 US/Canada recipients who share a single thread; replies
+fan out to everyone. Provide `text`, `media_urls`, or both. Requires the
+`group_mms` feature.
+
+```python
+group = client.messages.send_group(
+    to=['+14155551234', '+14155555678'],
+    text='Dinner at 7?'
+)
+print(f'{group.id}: {group.status}')  # 'sent' (or 'delivered' on a test key)
+print(group.group_message_id)         # stable group thread id, when available
+
+# With media
+client.messages.send_group(
+    to=['+14155551234', '+14155555678'],
+    text='Here is the menu',
+    media_urls=['https://example.com/menu.jpg'],
+)
+```
+
+## AI Enhance
+
+Polish message copy before sending. Pass `text` and/or a `message_type` to steer
+the tone.
+
+```python
+result = client.messages.enhance(text='ur order shipped', message_type='transactional')
+print(result.enhanced)     # cleaned-up copy
+print(result.explanation)  # why it changed
+```
+
+## Branded Links (URL Shortener)
+
+Mint branded short links for a destination URL, list them with click analytics,
+and flip a per-link kill switch. Branded, owned-domain links improve
+deliverability and give you click data. Gated behind the `url_shortener` flag.
+
+```python
+# Shorten a URL
+link = client.links.create('https://example.com/spring-sale?utm_source=sms')
+print(link.short_url)        # https://sendly.live/l/Ab3xY7
+print(link.code)             # Ab3xY7
+
+# List your links with click counts and a 14-day daily histogram
+listing = client.links.list(limit=20)
+print(f'{listing.total} links')
+for lk in listing.links:
+    print(f'{lk.short_url} -> {lk.destination_url} ({lk.click_count} clicks)')
+
+# Kill a link (its redirect 404s until re-enabled)
+client.links.disable(link.code)
+client.links.enable(link.code)
+```
+
 ## Error Handling
 
 The SDK provides typed exception classes:
@@ -663,6 +784,44 @@ List the numbers the account already owns.
 
 Buy a number. Returns `status` of `provisioning`, `documents_required`, or `payment_required`; when documents/payment are required, `action` carries a hosted page URL + code to hand to the user before re-calling with `action_code`.
 
+### `client.ten_dlc`
+
+#### `list_brands() -> TenDlcBrandListResponse`
+
+List the brands registered for carrier review.
+
+#### `create_brand(legal_name, dba=None, ein=None, entity_type=None, ...) -> TenDlcBrandResponse`
+
+Register a brand for carrier review — step 1 of enabling local-number texting. The brand starts `pending`; poll `get_brand()` until it becomes `verified`.
+
+#### `get_brand(id) -> TenDlcBrandResponse`
+
+Fetch one brand; also refreshes its carrier-review status, so polling shows progress (`pending` → `verified`/`failed`).
+
+#### `qualify(brand_id, use_case) -> TenDlcQualifyResponse`
+
+Pre-check whether a use case qualifies for a brand on the carrier network before creating a campaign.
+
+#### `list_campaigns() -> TenDlcCampaignListResponse`
+
+List your messaging campaigns.
+
+#### `create_campaign(brand_id, use_case, description, message_flow, sample_messages, ...) -> TenDlcCampaignResponse`
+
+Create a campaign under a verified brand and submit it for carrier review. Starts `pending`; poll `get_campaign()` until it becomes `active`.
+
+#### `get_campaign(id) -> TenDlcCampaignResponse`
+
+Fetch one campaign; also refreshes its carrier-review status, including throughput once carriers approve.
+
+#### `assign_number(campaign_id, phone_number) -> TenDlcAssignmentResponse`
+
+Assign a number you own to an active campaign, making the number sendable. Idempotent — re-assigning the same number to the same campaign returns the existing assignment.
+
+#### `list_assignments() -> TenDlcAssignmentListResponse`
+
+List your number-to-campaign assignments.
+
 ## Enterprise
 
 The Enterprise API lets you programmatically manage workspaces, verification, credits, and API keys for multi-tenant platforms. Requires an enterprise master key (`sk_live_v1_master_*`).

{sendly-3.34.0 → sendly-3.37.0}/README.md

@@ -367,6 +367,13 @@ print(f"Credits used: {usage['creditsUsed']}")
 result = client.account.create_api_key('Production Key')
 print(f"New key: {result['key']}")  # Only shown once!
 
+# Rotate an API key (old key keeps working for a 24h grace period by default)
+rotation = client.account.rotate_api_key('key_xxx')
+print(f"New key: {rotation['newKey']['key']}")  # Only shown once!
+
+# Rotate with a wider overlap window (24-168 hours)
+rotation = client.account.rotate_api_key('key_xxx', grace_period_hours=72)
+
 # Revoke an API key
 client.account.revoke_api_key('key_xxx')
 ```
@@ -396,6 +403,23 @@ owned = client.numbers.list()
 for num in owned.numbers:
     print(f'{num.phone_number} ({num.status})')
 
+# Get one owned number (includes whether it's your default sender)
+number = client.numbers.get('num_xxx')
+print(f'{number.phone_number} default={number.is_default}')
+
+# Make a number your default sender
+client.numbers.update('num_xxx', is_default=True)
+
+# Cancel a scheduled release and keep the number
+client.numbers.update('num_xxx', pending_cancellation=False)
+
+# Release a number (a paid number is kept until the end of the billed period)
+result = client.numbers.release('num_xxx')
+if result.scheduled:
+    print(f'Releases at {result.scheduled_release_at}')
+else:
+    print('Released')
+
 # Buy a number
 chosen = available.numbers[0]
 result = client.numbers.buy(
@@ -422,6 +446,103 @@ elif result.status in ('documents_required', 'payment_required'):
     )
 ```
 
+## 10DLC (Local Number Texting)
+
+Register your business for carrier review so you can text from local
+(10-digit) US numbers. Requires an API key with the `tendlc:read` /
+`tendlc:write` scopes; writes need a live key. The flow has three steps:
+brand → campaign → assign a number.
+
+```python
+# 1. Register a brand and poll until it's verified
+brand = client.ten_dlc.create_brand(
+    legal_name='Acme Holdings LLC',
+    ein='12-3456789',
+    website='https://acme.example',
+    email='ops@acme.example',
+).data
+# ...poll client.ten_dlc.get_brand(brand.id) until brand.status == 'verified'
+# (or 'failed', with brand.failure_reasons explaining why)
+
+# 2. Pre-check the use case, then create a campaign
+check = client.ten_dlc.qualify(brand.id, 'MIXED').data
+if check.qualified:
+    campaign = client.ten_dlc.create_campaign(
+        brand_id=brand.id,
+        use_case='MIXED',
+        description='Order updates and support replies for Acme customers',
+        message_flow='Customers opt in at checkout on acme.example',
+        sample_messages=['Your order #123 has shipped!'],
+        opt_out_keywords='STOP',
+    ).data
+    # ...poll client.ten_dlc.get_campaign(campaign.id) until status == 'active'
+
+    # 3. Assign a number you own; it can send once the assignment is 'Active'
+    assignment = client.ten_dlc.assign_number(campaign.id, '+15551234567').data
+    print(assignment.status)
+
+# List what you have registered
+brands = client.ten_dlc.list_brands()
+campaigns = client.ten_dlc.list_campaigns()
+assignments = client.ten_dlc.list_assignments()
+```
+
+## Group MMS
+
+Send one message to 2-8 US/Canada recipients who share a single thread; replies
+fan out to everyone. Provide `text`, `media_urls`, or both. Requires the
+`group_mms` feature.
+
+```python
+group = client.messages.send_group(
+    to=['+14155551234', '+14155555678'],
+    text='Dinner at 7?'
+)
+print(f'{group.id}: {group.status}')  # 'sent' (or 'delivered' on a test key)
+print(group.group_message_id)         # stable group thread id, when available
+
+# With media
+client.messages.send_group(
+    to=['+14155551234', '+14155555678'],
+    text='Here is the menu',
+    media_urls=['https://example.com/menu.jpg'],
+)
+```
+
+## AI Enhance
+
+Polish message copy before sending. Pass `text` and/or a `message_type` to steer
+the tone.
+
+```python
+result = client.messages.enhance(text='ur order shipped', message_type='transactional')
+print(result.enhanced)     # cleaned-up copy
+print(result.explanation)  # why it changed
+```
+
+## Branded Links (URL Shortener)
+
+Mint branded short links for a destination URL, list them with click analytics,
+and flip a per-link kill switch. Branded, owned-domain links improve
+deliverability and give you click data. Gated behind the `url_shortener` flag.
+
+```python
+# Shorten a URL
+link = client.links.create('https://example.com/spring-sale?utm_source=sms')
+print(link.short_url)        # https://sendly.live/l/Ab3xY7
+print(link.code)             # Ab3xY7
+
+# List your links with click counts and a 14-day daily histogram
+listing = client.links.list(limit=20)
+print(f'{listing.total} links')
+for lk in listing.links:
+    print(f'{lk.short_url} -> {lk.destination_url} ({lk.click_count} clicks)')
+
+# Kill a link (its redirect 404s until re-enabled)
+client.links.disable(link.code)
+client.links.enable(link.code)
+```
+
 ## Error Handling
 
 The SDK provides typed exception classes:
@@ -628,6 +749,44 @@ List the numbers the account already owns.
 
 Buy a number. Returns `status` of `provisioning`, `documents_required`, or `payment_required`; when documents/payment are required, `action` carries a hosted page URL + code to hand to the user before re-calling with `action_code`.
 
+### `client.ten_dlc`
+
+#### `list_brands() -> TenDlcBrandListResponse`
+
+List the brands registered for carrier review.
+
+#### `create_brand(legal_name, dba=None, ein=None, entity_type=None, ...) -> TenDlcBrandResponse`
+
+Register a brand for carrier review — step 1 of enabling local-number texting. The brand starts `pending`; poll `get_brand()` until it becomes `verified`.
+
+#### `get_brand(id) -> TenDlcBrandResponse`
+
+Fetch one brand; also refreshes its carrier-review status, so polling shows progress (`pending` → `verified`/`failed`).
+
+#### `qualify(brand_id, use_case) -> TenDlcQualifyResponse`
+
+Pre-check whether a use case qualifies for a brand on the carrier network before creating a campaign.
+
+#### `list_campaigns() -> TenDlcCampaignListResponse`
+
+List your messaging campaigns.
+
+#### `create_campaign(brand_id, use_case, description, message_flow, sample_messages, ...) -> TenDlcCampaignResponse`
+
+Create a campaign under a verified brand and submit it for carrier review. Starts `pending`; poll `get_campaign()` until it becomes `active`.
+
+#### `get_campaign(id) -> TenDlcCampaignResponse`
+
+Fetch one campaign; also refreshes its carrier-review status, including throughput once carriers approve.
+
+#### `assign_number(campaign_id, phone_number) -> TenDlcAssignmentResponse`
+
+Assign a number you own to an active campaign, making the number sendable. Idempotent — re-assigning the same number to the same campaign returns the existing assignment.
+
+#### `list_assignments() -> TenDlcAssignmentListResponse`
+
+List your number-to-campaign assignments.
+
 ## Enterprise
 
 The Enterprise API lets you programmatically manage workspaces, verification, credits, and API keys for multi-tenant platforms. Requires an enterprise master key (`sk_live_v1_master_*`).

{sendly-3.34.0 → sendly-3.37.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sendly"
-version = "3.34.0"
+version = "3.37.0"
 description = "Official Sendly Python SDK for SMS messaging"
 readme = "README.md"
 license = "MIT"

{sendly-3.34.0 → sendly-3.37.0}/sendly/__init__.py

@@ -51,8 +51,10 @@ from .resources.business_upgrade import (
     AsyncBusinessUpgradeResource,
     BusinessUpgradeResource,
 )
+from .resources.links import AsyncLinksResource, LinksResource
 from .resources.media import AsyncMediaResource, MediaResource
 from .resources.numbers import AsyncNumbersResource, NumbersResource
+from .resources.tendlc import AsyncTenDlcResource, TenDlcResource
 
 # Types
 from .types import (
@@ -126,6 +128,29 @@ from .types import (
     NumberCountry,
     OwnedNumber,
     OwnedNumbersResponse,
+    ReleaseNumberResponse,
+    # Group MMS + AI types
+    EnhanceMessageResponse,
+    GroupMessageResponse,
+    SendGroupMessageRequest,
+    # URL shortener types
+    CreateShortLinkResponse,
+    ShortLink,
+    ShortLinkListResponse,
+    UpdateShortLinkResponse,
+    # 10DLC types
+    TenDlcAssignment,
+    TenDlcAssignmentListResponse,
+    TenDlcAssignmentResponse,
+    TenDlcBrand,
+    TenDlcBrandListResponse,
+    TenDlcBrandResponse,
+    TenDlcCampaign,
+    TenDlcCampaignListResponse,
+    TenDlcCampaignResponse,
+    TenDlcQualifyResponse,
+    TenDlcQualifyResult,
+    TenDlcThroughput,
     OptInPage,
     PricingTier,
     QuotaSettings,
@@ -272,12 +297,41 @@ __all__ = [
     "NumberCountry",
     "OwnedNumber",
     "OwnedNumbersResponse",
+    "ReleaseNumberResponse",
+    # Group MMS + AI types
+    "EnhanceMessageResponse",
+    "GroupMessageResponse",
+    "SendGroupMessageRequest",
+    # URL shortener types
+    "CreateShortLinkResponse",
+    "ShortLink",
+    "ShortLinkListResponse",
+    "UpdateShortLinkResponse",
+    # 10DLC types
+    "TenDlcAssignment",
+    "TenDlcAssignmentListResponse",
+    "TenDlcAssignmentResponse",
+    "TenDlcBrand",
+    "TenDlcBrandListResponse",
+    "TenDlcBrandResponse",
+    "TenDlcCampaign",
+    "TenDlcCampaignListResponse",
+    "TenDlcCampaignResponse",
+    "TenDlcQualifyResponse",
+    "TenDlcQualifyResult",
+    "TenDlcThroughput",
+    # Links resources
+    "LinksResource",
+    "AsyncLinksResource",
     # Media resources
     "MediaResource",
     "AsyncMediaResource",
     # Numbers resources
     "NumbersResource",
     "AsyncNumbersResource",
+    # 10DLC resources
+    "TenDlcResource",
+    "AsyncTenDlcResource",
     # Business upgrade resources
     "BusinessUpgradeResource",
     "AsyncBusinessUpgradeResource",

{sendly-3.34.0 → sendly-3.37.0}/sendly/client.py

@@ -17,11 +17,13 @@ from .resources.conversations import AsyncConversationsResource, ConversationsRe
 from .resources.drafts import AsyncDraftsResource, DraftsResource
 from .resources.enterprise import AsyncEnterpriseResource, EnterpriseResource
 from .resources.labels import AsyncLabelsResource, LabelsResource
+from .resources.links import AsyncLinksResource, LinksResource
 from .resources.media import AsyncMediaResource, MediaResource
 from .resources.messages import AsyncMessagesResource, MessagesResource
 from .resources.numbers import AsyncNumbersResource, NumbersResource
 from .resources.rules import AsyncRulesResource, RulesResource
 from .resources.templates import AsyncTemplatesResource, TemplatesResource
+from .resources.tendlc import AsyncTenDlcResource, TenDlcResource
 from .resources.verify import AsyncVerifyResource, VerifyResource
 from .resources.webhooks import AsyncWebhooksResource, WebhooksResource
 from .types import RateLimitInfo, SendlyConfig
@@ -119,8 +121,10 @@ class Sendly:
         self.contacts = ContactsResource(self._http)
         self.media = MediaResource(self._http)
         self.numbers = NumbersResource(self._http)
+        self.ten_dlc = TenDlcResource(self._http)
         self.enterprise = EnterpriseResource(self._http)
         self.labels = LabelsResource(self._http)
+        self.links = LinksResource(self._http)
         self.drafts = DraftsResource(self._http)
         self.rules = RulesResource(self._http)
         self.business_upgrade = BusinessUpgradeResource(self._http)
@@ -258,8 +262,10 @@ class AsyncSendly:
         self.contacts = AsyncContactsResource(self._http)
         self.media = AsyncMediaResource(self._http)
         self.numbers = AsyncNumbersResource(self._http)
+        self.ten_dlc = AsyncTenDlcResource(self._http)
         self.enterprise = AsyncEnterpriseResource(self._http)
         self.labels = AsyncLabelsResource(self._http)
+        self.links = AsyncLinksResource(self._http)
         self.drafts = AsyncDraftsResource(self._http)
         self.rules = AsyncRulesResource(self._http)
         self.business_upgrade = AsyncBusinessUpgradeResource(self._http)

{sendly-3.34.0 → sendly-3.37.0}/sendly/resources/__init__.py

@@ -6,11 +6,13 @@ from .conversations import AsyncConversationsResource, ConversationsResource
 from .drafts import AsyncDraftsResource, DraftsResource
 from .enterprise import AsyncEnterpriseResource, EnterpriseResource
 from .labels import AsyncLabelsResource, LabelsResource
+from .links import AsyncLinksResource, LinksResource
 from .media import AsyncMediaResource, MediaResource
 from .messages import AsyncMessagesResource, MessagesResource
 from .numbers import AsyncNumbersResource, NumbersResource
 from .rules import AsyncRulesResource, RulesResource
 from .templates import AsyncTemplatesResource, TemplatesResource
+from .tendlc import AsyncTenDlcResource, TenDlcResource
 from .verify import AsyncVerifyResource, VerifyResource
 
 __all__ = [
@@ -26,6 +28,8 @@ __all__ = [
     "AsyncEnterpriseResource",
     "LabelsResource",
     "AsyncLabelsResource",
+    "LinksResource",
+    "AsyncLinksResource",
     "MediaResource",
     "AsyncMediaResource",
     "MessagesResource",
@@ -38,4 +42,6 @@ __all__ = [
     "AsyncTemplatesResource",
     "RulesResource",
     "AsyncRulesResource",
+    "TenDlcResource",
+    "AsyncTenDlcResource",
 ]

{sendly-3.34.0 → sendly-3.37.0}/sendly/resources/account.py

@@ -192,6 +192,42 @@ class AccountResource:
 
         self._http.request("DELETE", f"/account/keys/{key_id}")
 
+    def rotate_api_key(
+        self, key_id: str, grace_period_hours: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """
+        Rotate an API key.
+
+        Mints a replacement key and, by default, keeps the old key working for a
+        24-hour grace period so you can roll the new secret out before the old
+        one stops. Pass ``grace_period_hours`` (24-168) to widen the window, or
+        the caller can revoke the old key immediately once the new one is live.
+
+        Args:
+            key_id: ID of the API key to rotate
+            grace_period_hours: Overlap window in hours (24-168, default 24)
+
+        Returns:
+            Dict with 'newKey' (metadata plus the full 'key' secret - only shown
+            once - and a 'warning'), 'oldKey' (the predecessor), and 'message'
+
+        Example:
+            >>> result = client.account.rotate_api_key('key_xxx')
+            >>> print(f"Save this key: {result['newKey']['key']}")  # Only shown once!
+        """
+        if not key_id:
+            raise ValueError("API key ID is required")
+
+        body: Dict[str, Any] = {}
+        if grace_period_hours is not None:
+            if not isinstance(grace_period_hours, int) or not (
+                24 <= grace_period_hours <= 168
+            ):
+                raise ValueError("grace_period_hours must be between 24 and 168")
+            body["gracePeriodHours"] = grace_period_hours
+
+        return self._http.request("POST", f"/account/keys/{key_id}/rotate", body=body)
+
 
 class AsyncAccountResource:
     """
@@ -284,3 +320,36 @@ class AsyncAccountResource:
             raise ValueError("API key ID is required")
 
         await self._http.request("DELETE", f"/account/keys/{key_id}")
+
+    async def rotate_api_key(
+        self, key_id: str, grace_period_hours: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """
+        Rotate an API key (async).
+
+        Mints a replacement key and, by default, keeps the old key working for a
+        24-hour grace period. Pass ``grace_period_hours`` (24-168) to widen the
+        overlap window.
+
+        Args:
+            key_id: ID of the API key to rotate
+            grace_period_hours: Overlap window in hours (24-168, default 24)
+
+        Returns:
+            Dict with 'newKey' (metadata plus the full 'key' secret - only shown
+            once - and a 'warning'), 'oldKey' (the predecessor), and 'message'
+        """
+        if not key_id:
+            raise ValueError("API key ID is required")
+
+        body: Dict[str, Any] = {}
+        if grace_period_hours is not None:
+            if not isinstance(grace_period_hours, int) or not (
+                24 <= grace_period_hours <= 168
+            ):
+                raise ValueError("grace_period_hours must be between 24 and 168")
+            body["gracePeriodHours"] = grace_period_hours
+
+        return await self._http.request(
+            "POST", f"/account/keys/{key_id}/rotate", body=body
+        )