release: 0.27.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
- ".": "0.26.0"
+ ".": "0.27.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 41
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/surge/surge-b0be84bbd2acb3b1441eedd973161e22d633387c0919c52cbecdaf964c1e5980.yml
-openapi_spec_hash: 402af89d33c0accd114958a9d4fb74d2
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/surge/surge-ffd563fe3318efc4a305510ec4ae66fea4a32d96ed34abd985b44692edb3535e.yml
+openapi_spec_hash: fd58e5b23f677b6de74244fcf1669d8d
 config_hash: 6cd48b2a1ecc5f0cf0903e70c0c6260e

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.27.0 (2026-09-04)
+
+Full Changelog: [v0.26.0...v0.27.0](https://github.com/surgeapi/python-sdk/compare/v0.26.0...v0.27.0)
+
+### Features
+
+* **api:** add status to messages ([8659b97](https://github.com/surgeapi/python-sdk/commit/8659b97758ebf0d1d912d209ad418302f14c7360))
+* **api:** add toll free messaging capability to accounts ([0a80fa5](https://github.com/surgeapi/python-sdk/commit/0a80fa5557c9071a0462c02c6050af3cde05c6b5))
+* **api:** phone number imported webhook event ([d950456](https://github.com/surgeapi/python-sdk/commit/d95045674c38c98b86c525a5784f8e0bd8c206d7))
+
+
+### Documentation
+
+* **api:** add note about links in messages for campaigns ([bbaabd5](https://github.com/surgeapi/python-sdk/commit/bbaabd54fcf26f6be4b80a287e0cf19724f03b4a))
+* **api:** add note about links in messages for campaigns (continued) ([54504f8](https://github.com/surgeapi/python-sdk/commit/54504f83fedb8e3b9fe033bb628eb4ca5bbc7e84))
+
 ## 0.26.0 (2026-08-19)
 
 Full Changelog: [v0.25.0...v0.26.0](https://github.com/surgeapi/python-sdk/compare/v0.25.0...v0.26.0)

api.md

@@ -188,6 +188,7 @@ from surge.types import (
  MessageReceivedWebhookEvent,
  MessageSentWebhookEvent,
  PhoneNumberAttachedToCampaignWebhookEvent,
+ PhoneNumberImportedWebhookEvent,
  RecordingCompletedWebhookEvent,
  VoicemailReceivedWebhookEvent,
  UnwrapWebhookEvent,

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "surge-sdk"
-version = "0.26.0"
+version = "0.27.0"
 description = "The official Python library for the surge API"
 dynamic = ["readme"]
 license = "Apache-2.0"

src/surge/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "surge"
-__version__ = "0.26.0" # x-release-please-version
+__version__ = "0.27.0" # x-release-please-version

src/surge/resources/accounts.py

@@ -297,7 +297,7 @@ def retrieve_status(
  self,
  account_id: str,
  *,
- capabilities: List[Literal["local_messaging"]] | Omit = omit,
+ capabilities: List[Literal["local_messaging", "toll_free_messaging"]] | Omit = omit,
  # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
  # The extra values given here take precedence over values defined on the client or passed to this method.
  extra_headers: Headers | None = None,
@@ -609,7 +609,7 @@ async def retrieve_status(
  self,
  account_id: str,
  *,
- capabilities: List[Literal["local_messaging"]] | Omit = omit,
+ capabilities: List[Literal["local_messaging", "toll_free_messaging"]] | Omit = omit,
  # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
  # The extra values given here take precedence over values defined on the client or passed to this method.
  extra_headers: Headers | None = None,

src/surge/resources/campaigns.py

@@ -160,11 +160,10 @@ def create(
  - `direct_lending` - whether the campaign contains content related to direct
  lending or other loan arrangements
 
- link_sample: A sample link that might be sent by this campaign. If links from other domains
- are sent through this campaign, they are much more likely to be filtered by the
- carriers. If link shortening is enabled for the account, the link shortener URL
- will be used instead of what is provided. Reach out to support if you would like
- to disable automatic link shortening.
+ link_sample: A sample link that might be sent by this campaign. This is required when
+ `includes` contains `links`. Provide the same URL or domain that the campaign
+ will use in production. If links from other domains are sent through this
+ campaign, they are much more likely to be filtered by the carriers.
 
  extra_headers: Send extra headers
 
@@ -432,11 +431,10 @@ def update(
  - `direct_lending` - whether the campaign contains content related to direct
  lending or other loan arrangements
 
- link_sample: A sample link that might be sent by this campaign. If links from other domains
- are sent through this campaign, they are much more likely to be filtered by the
- carriers. If link shortening is enabled for the account, the link shortener URL
- will be used instead of what is provided. Reach out to support if you would like
- to disable automatic link shortening.
+ link_sample: A sample link that might be sent by this campaign. This is required when
+ `includes` contains `links`. Provide the same URL or domain that the campaign
+ will use in production. If links from other domains are sent through this
+ campaign, they are much more likely to be filtered by the carriers.
 
  extra_headers: Send extra headers
 
@@ -778,11 +776,10 @@ async def create(
  - `direct_lending` - whether the campaign contains content related to direct
  lending or other loan arrangements
 
- link_sample: A sample link that might be sent by this campaign. If links from other domains
- are sent through this campaign, they are much more likely to be filtered by the
- carriers. If link shortening is enabled for the account, the link shortener URL
- will be used instead of what is provided. Reach out to support if you would like
- to disable automatic link shortening.
+ link_sample: A sample link that might be sent by this campaign. This is required when
+ `includes` contains `links`. Provide the same URL or domain that the campaign
+ will use in production. If links from other domains are sent through this
+ campaign, they are much more likely to be filtered by the carriers.
 
  extra_headers: Send extra headers
 
@@ -1050,11 +1047,10 @@ async def update(
  - `direct_lending` - whether the campaign contains content related to direct
  lending or other loan arrangements
 
- link_sample: A sample link that might be sent by this campaign. If links from other domains
- are sent through this campaign, they are much more likely to be filtered by the
- carriers. If link shortening is enabled for the account, the link shortener URL
- will be used instead of what is provided. Reach out to support if you would like
- to disable automatic link shortening.
+ link_sample: A sample link that might be sent by this campaign. This is required when
+ `includes` contains `links`. Provide the same URL or domain that the campaign
+ will use in production. If links from other domains are sent through this
+ campaign, they are much more likely to be filtered by the carriers.
 
  extra_headers: Send extra headers
 

src/surge/types/__init__.py

@@ -60,6 +60,7 @@
 from .voicemail_received_webhook_event import VoicemailReceivedWebhookEvent as VoicemailReceivedWebhookEvent
 from .recording_completed_webhook_event import RecordingCompletedWebhookEvent as RecordingCompletedWebhookEvent
 from .conversation_created_webhook_event import ConversationCreatedWebhookEvent as ConversationCreatedWebhookEvent
+from .phone_number_imported_webhook_event import PhoneNumberImportedWebhookEvent as PhoneNumberImportedWebhookEvent
 from .phone_number_list_available_numbers_params import (
  PhoneNumberListAvailableNumbersParams as PhoneNumberListAvailableNumbersParams,
 )

src/surge/types/account_retrieve_status_params.py

@@ -9,5 +9,5 @@
 
 
 class AccountRetrieveStatusParams(TypedDict, total=False):
- capabilities: List[Literal["local_messaging"]]
+ capabilities: List[Literal["local_messaging", "toll_free_messaging"]]
  """capabilities about which to check the status"""

src/surge/types/campaign.py

@@ -61,7 +61,7 @@ class Campaign(BaseModel):
  users when they opt in to messaging.
  """
 
- status: Literal["active", "canceled", "created", "deactivated", "in_review"]
+ status: Literal["active", "canceled", "rejected", "created", "deactivated", "in_review"]
  """The current status of the campaign."""
 
  use_cases: List[
@@ -122,10 +122,10 @@ class Campaign(BaseModel):
  link_sample: Optional[str] = None
  """A sample link that might be sent by this campaign.
 
-If links from other domains are sent through this campaign, they are much more
-likely to be filtered by the carriers. If link shortening is enabled for the
-account, the link shortener URL will be used instead of what is provided. Reach
-out to support if you would like to disable automatic link shortening.
+This is required when `includes` contains `links`. Provide the same URL or
+domain that the campaign will use in production. If links from other domains are
+sent through this campaign, they are much more likely to be filtered by the
+carriers.
  """
 
  terms_and_conditions_url: Optional[str] = None

src/surge/types/campaign_create_params.py

@@ -124,10 +124,10 @@ class StandardCampaignParams(TypedDict, total=False):
  link_sample: str
  """A sample link that might be sent by this campaign.
 
-If links from other domains are sent through this campaign, they are much more
-likely to be filtered by the carriers. If link shortening is enabled for the
-account, the link shortener URL will be used instead of what is provided. Reach
-out to support if you would like to disable automatic link shortening.
+This is required when `includes` contains `links`. Provide the same URL or
+domain that the campaign will use in production. If links from other domains are
+sent through this campaign, they are much more likely to be filtered by the
+carriers.
  """
 
 

src/surge/types/campaign_update_params.py

@@ -124,10 +124,10 @@ class StandardCampaignParams(TypedDict, total=False):
  link_sample: str
  """A sample link that might be sent by this campaign.
 
-If links from other domains are sent through this campaign, they are much more
-likely to be filtered by the carriers. If link shortening is enabled for the
-account, the link shortener URL will be used instead of what is provided. Reach
-out to support if you would like to disable automatic link shortening.
+This is required when `includes` contains `links`. Provide the same URL or
+domain that the campaign will use in production. If links from other domains are
+sent through this campaign, they are much more likely to be filtered by the
+carriers.
  """
 
 

src/surge/types/message.py

@@ -73,3 +73,6 @@ class Message(BaseModel):
 
  metadata: Optional[Dict[str, str]] = None
  """Set of key-value pairs that will be stored with the object."""
+
+ status: Optional[Literal["pending", "received", "sent", "delivered", "failed"]] = None
+ """The current status of the message."""

src/surge/types/message_delivered_webhook_event.py

@@ -53,6 +53,9 @@ class Data(BaseModel):
  metadata: Dict[str, str]
  """Set of key-value pairs that will be stored with the object."""
 
+ status: Literal["delivered"]
+ """The message status represented by this event"""
+
  attachments: Optional[List[DataAttachment]] = None
  """Attachments included with the message"""
 

src/surge/types/message_failed_webhook_event.py

@@ -56,6 +56,9 @@ class Data(BaseModel):
  metadata: Dict[str, str]
  """Set of key-value pairs that will be stored with the object."""
 
+ status: Literal["failed"]
+ """The message status represented by this event"""
+
  attachments: Optional[List[DataAttachment]] = None
  """Attachments included with the message"""
 

src/surge/types/message_received_webhook_event.py

@@ -53,6 +53,9 @@ class Data(BaseModel):
  received_at: datetime
  """When the message was received"""
 
+ status: Literal["received"]
+ """The message status represented by this event"""
+
  attachments: Optional[List[DataAttachment]] = None
  """Attachments included with the message"""
 

src/surge/types/message_sent_webhook_event.py

@@ -53,6 +53,9 @@ class Data(BaseModel):
  sent_at: datetime
  """When the message was sent"""
 
+ status: Literal["sent"]
+ """The message status represented by this event"""
+
  attachments: Optional[List[DataAttachment]] = None
  """Attachments included with the message"""
 

src/surge/types/phone_number_imported_webhook_event.py

@@ -0,0 +1,58 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Optional
+from datetime import datetime
+from typing_extensions import Literal
+
+from .._models import BaseModel
+
+__all__ = ["PhoneNumberImportedWebhookEvent", "Data", "DataCampaign"]
+
+
+class DataCampaign(BaseModel):
+ """Campaign attachment details for a domestic local phone number"""
+
+ id: str
+ """The unique identifier of the campaign this phone number is attached to"""
+
+ attachment_status: Literal["attached", "attachment_pending", "detached", "detachment_pending"]
+ """The current campaign attachment status for this phone number."""
+
+
+class Data(BaseModel):
+ """The data associated with the event"""
+
+ id: str
+ """The unique identifier for the phone number"""
+
+ campaign: Optional[DataCampaign] = None
+ """Campaign attachment details for a domestic local phone number"""
+
+ campaign_id: Optional[str] = None
+ """Deprecated.
+
+ The unique identifier of the campaign this phone number is attached to
+ """
+
+ name: Optional[str] = None
+ """A human-readable name for the phone number"""
+
+ number: str
+ """The phone number in E.164 format"""
+
+ type: Literal["local", "short_code", "toll_free"]
+ """Whether the phone number is local, toll-free, or short code"""
+
+
+class PhoneNumberImportedWebhookEvent(BaseModel):
+ account_id: str
+ """The ID of the account in which this event occurred"""
+
+ data: Data
+ """The data associated with the event"""
+
+ timestamp: datetime
+ """The timestamp when this event occurred, in ISO8601 format"""
+
+ type: Literal["phone_number.imported"]
+ """The type of the event. Always `phone_number.imported` for this event."""

src/surge/types/unwrap_webhook_event.py

@@ -16,6 +16,7 @@
 from .voicemail_received_webhook_event import VoicemailReceivedWebhookEvent
 from .recording_completed_webhook_event import RecordingCompletedWebhookEvent
 from .conversation_created_webhook_event import ConversationCreatedWebhookEvent
+from .phone_number_imported_webhook_event import PhoneNumberImportedWebhookEvent
 from .phone_number_attached_to_campaign_webhook_event import PhoneNumberAttachedToCampaignWebhookEvent
 
 __all__ = ["UnwrapWebhookEvent"]
@@ -33,6 +34,7 @@
  MessageReceivedWebhookEvent,
  MessageSentWebhookEvent,
  PhoneNumberAttachedToCampaignWebhookEvent,
+ PhoneNumberImportedWebhookEvent,
  RecordingCompletedWebhookEvent,
  VoicemailReceivedWebhookEvent,
  ],