release: 0.14.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.13.0"
+  ".": "0.14.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 34
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/ark%2Fark-b651c88f3a87cebd528784fef019612f41517d0912c7e5695bb4419d00b9409b.yml
-openapi_spec_hash: 33d0f5c2bb0349abf085404e2a3b05f7
-config_hash: fbd4e7a9ee50aad316893984a725519b
+configured_endpoints: 35
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/ark%2Fark-1949bcfc8775c97eca880428dc93e9f97aa91144bef82584027ede5089bb2e19.yml
+openapi_spec_hash: 0aa367455a067b701f18ef7892b6c7e9
+config_hash: 373e654f8034a40c42234eee9ebefbb9

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.14.0 (2026-01-29)
+
+Full Changelog: [v0.13.0...v0.14.0](https://github.com/ArkHQ-io/ark-python/compare/v0.13.0...v0.14.0)
+
+### Features
+
+* **api:** add usage and SendLimit Headers ([4281980](https://github.com/ArkHQ-io/ark-python/commit/4281980353ff7423dbc6627e37abefee952bc489))
+* **api:** api update ([10f496a](https://github.com/ArkHQ-io/ark-python/commit/10f496a29924ecd9bcc93d0551ea8bd29662aa89))
+* **api:** domain list improvement ([6929689](https://github.com/ArkHQ-io/ark-python/commit/69296893c13ad8e4f05047f312009e88a8f02830))
+
+
+### Bug Fixes
+
+* **docs:** fix mcp installation instructions for remote servers ([f559107](https://github.com/ArkHQ-io/ark-python/commit/f55910772f06f551b98a1ddc7c7dda45fc2176f4))
+
 ## 0.13.0 (2026-01-25)
 
 Full Changelog: [v0.12.0...v0.13.0](https://github.com/ArkHQ-io/ark-python/compare/v0.12.0...v0.13.0)

README.md

@@ -13,8 +13,8 @@ It is generated with [Stainless](https://www.stainless.com/).
 
 Use the Ark MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.
 
-[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=ark-email-mcp&config=eyJuYW1lIjoiYXJrLWVtYWlsLW1jcCIsInRyYW5zcG9ydCI6InNzZSIsInVybCI6Imh0dHBzOi8vYXJrLW1jcC5zdGxtY3AuY29tL3NzZSJ9)
-[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22ark-email-mcp%22%2C%22type%22%3A%22sse%22%2C%22url%22%3A%22https%3A%2F%2Fark-mcp.stlmcp.com%2Fsse%22%7D)
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=ark-email-mcp&config=eyJuYW1lIjoiYXJrLWVtYWlsLW1jcCIsInRyYW5zcG9ydCI6Imh0dHAiLCJ1cmwiOiJodHRwczovL2Fyay1tY3Auc3RsbWNwLmNvbSIsImhlYWRlcnMiOnsieC1hcmstYXBpLWtleSI6Ik15IEFQSSBLZXkifX0)
+[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22ark-email-mcp%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fark-mcp.stlmcp.com%22%2C%22headers%22%3A%7B%22x-ark-api-key%22%3A%22My%20API%20Key%22%7D%7D)
 
 > Note: You may need to set environment variables in your MCP client.
 

api.md

@@ -142,3 +142,15 @@ Methods:
 
 - <code title="get /logs/{requestId}">client.logs.<a href="./src/ark/resources/logs.py">retrieve</a>(request_id) -> <a href="./src/ark/types/log_retrieve_response.py">LogRetrieveResponse</a></code>
 - <code title="get /logs">client.logs.<a href="./src/ark/resources/logs.py">list</a>(\*\*<a href="src/ark/types/log_list_params.py">params</a>) -> <a href="./src/ark/types/log_entry.py">SyncPageNumberPagination[LogEntry]</a></code>
+
+# Usage
+
+Types:
+
+```python
+from ark.types import UsageRetrieveResponse
+```
+
+Methods:
+
+- <code title="get /usage">client.usage.<a href="./src/ark/resources/usage.py">retrieve</a>() -> <a href="./src/ark/types/usage_retrieve_response.py">UsageRetrieveResponse</a></code>

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ark-email"
-version = "0.13.0"
+version = "0.14.0"
 description = "The official Python library for the ark API"
 dynamic = ["readme"]
 license = "Apache-2.0"

src/ark/_client.py

@@ -31,8 +31,9 @@
 )
 
 if TYPE_CHECKING:
-    from .resources import logs, emails, domains, tracking, webhooks, suppressions
+    from .resources import logs, usage, emails, domains, tracking, webhooks, suppressions
     from .resources.logs import LogsResource, AsyncLogsResource
+    from .resources.usage import UsageResource, AsyncUsageResource
     from .resources.emails import EmailsResource, AsyncEmailsResource
     from .resources.domains import DomainsResource, AsyncDomainsResource
     from .resources.tracking import TrackingResource, AsyncTrackingResource
@@ -133,6 +134,12 @@ def logs(self) -> LogsResource:
 
         return LogsResource(self)
 
+    @cached_property
+    def usage(self) -> UsageResource:
+        from .resources.usage import UsageResource
+
+        return UsageResource(self)
+
     @cached_property
     def with_raw_response(self) -> ArkWithRawResponse:
         return ArkWithRawResponse(self)
@@ -337,6 +344,12 @@ def logs(self) -> AsyncLogsResource:
 
         return AsyncLogsResource(self)
 
+    @cached_property
+    def usage(self) -> AsyncUsageResource:
+        from .resources.usage import AsyncUsageResource
+
+        return AsyncUsageResource(self)
+
     @cached_property
     def with_raw_response(self) -> AsyncArkWithRawResponse:
         return AsyncArkWithRawResponse(self)
@@ -492,6 +505,12 @@ def logs(self) -> logs.LogsResourceWithRawResponse:
 
         return LogsResourceWithRawResponse(self._client.logs)
 
+    @cached_property
+    def usage(self) -> usage.UsageResourceWithRawResponse:
+        from .resources.usage import UsageResourceWithRawResponse
+
+        return UsageResourceWithRawResponse(self._client.usage)
+
 
 class AsyncArkWithRawResponse:
     _client: AsyncArk
@@ -535,6 +554,12 @@ def logs(self) -> logs.AsyncLogsResourceWithRawResponse:
 
         return AsyncLogsResourceWithRawResponse(self._client.logs)
 
+    @cached_property
+    def usage(self) -> usage.AsyncUsageResourceWithRawResponse:
+        from .resources.usage import AsyncUsageResourceWithRawResponse
+
+        return AsyncUsageResourceWithRawResponse(self._client.usage)
+
 
 class ArkWithStreamedResponse:
     _client: Ark
@@ -578,6 +603,12 @@ def logs(self) -> logs.LogsResourceWithStreamingResponse:
 
         return LogsResourceWithStreamingResponse(self._client.logs)
 
+    @cached_property
+    def usage(self) -> usage.UsageResourceWithStreamingResponse:
+        from .resources.usage import UsageResourceWithStreamingResponse
+
+        return UsageResourceWithStreamingResponse(self._client.usage)
+
 
 class AsyncArkWithStreamedResponse:
     _client: AsyncArk
@@ -621,6 +652,12 @@ def logs(self) -> logs.AsyncLogsResourceWithStreamingResponse:
 
         return AsyncLogsResourceWithStreamingResponse(self._client.logs)
 
+    @cached_property
+    def usage(self) -> usage.AsyncUsageResourceWithStreamingResponse:
+        from .resources.usage import AsyncUsageResourceWithStreamingResponse
+
+        return AsyncUsageResourceWithStreamingResponse(self._client.usage)
+
 
 Client = Ark
 

src/ark/_version.py

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

src/ark/resources/__init__.py

@@ -8,6 +8,14 @@
     LogsResourceWithStreamingResponse,
     AsyncLogsResourceWithStreamingResponse,
 )
+from .usage import (
+    UsageResource,
+    AsyncUsageResource,
+    UsageResourceWithRawResponse,
+    AsyncUsageResourceWithRawResponse,
+    UsageResourceWithStreamingResponse,
+    AsyncUsageResourceWithStreamingResponse,
+)
 from .emails import (
     EmailsResource,
     AsyncEmailsResource,
@@ -86,4 +94,10 @@
     "AsyncLogsResourceWithRawResponse",
     "LogsResourceWithStreamingResponse",
     "AsyncLogsResourceWithStreamingResponse",
+    "UsageResource",
+    "AsyncUsageResource",
+    "UsageResourceWithRawResponse",
+    "AsyncUsageResourceWithRawResponse",
+    "UsageResourceWithStreamingResponse",
+    "AsyncUsageResourceWithStreamingResponse",
 ]

src/ark/resources/usage.py

@@ -0,0 +1,177 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+import httpx
+
+from .._types import Body, Query, Headers, NotGiven, not_given
+from .._compat import cached_property
+from .._resource import SyncAPIResource, AsyncAPIResource
+from .._response import (
+    to_raw_response_wrapper,
+    to_streamed_response_wrapper,
+    async_to_raw_response_wrapper,
+    async_to_streamed_response_wrapper,
+)
+from .._base_client import make_request_options
+from ..types.usage_retrieve_response import UsageRetrieveResponse
+
+__all__ = ["UsageResource", "AsyncUsageResource"]
+
+
+class UsageResource(SyncAPIResource):
+    @cached_property
+    def with_raw_response(self) -> UsageResourceWithRawResponse:
+        """
+        This property can be used as a prefix for any HTTP method call to return
+        the raw response object instead of the parsed content.
+
+        For more information, see https://www.github.com/ArkHQ-io/ark-python#accessing-raw-response-data-eg-headers
+        """
+        return UsageResourceWithRawResponse(self)
+
+    @cached_property
+    def with_streaming_response(self) -> UsageResourceWithStreamingResponse:
+        """
+        An alternative to `.with_raw_response` that doesn't eagerly read the response body.
+
+        For more information, see https://www.github.com/ArkHQ-io/ark-python#with_streaming_response
+        """
+        return UsageResourceWithStreamingResponse(self)
+
+    def retrieve(
+        self,
+        *,
+        # 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,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> UsageRetrieveResponse:
+        """
+        Returns current usage and limit information for your account.
+
+        This endpoint is designed for:
+
+        - **AI agents/MCP servers:** Check constraints before planning batch operations
+        - **Monitoring dashboards:** Display current usage status
+        - **Rate limit awareness:** Know remaining capacity before making requests
+
+        **Response includes:**
+
+        - `rateLimit` - API request rate limit (requests per second)
+        - `sendLimit` - Email sending limit (emails per hour)
+        - `billing` - Credit balance and auto-recharge configuration
+
+        **Notes:**
+
+        - This request counts against your rate limit
+        - `sendLimit` may be null if Postal is temporarily unavailable
+        - `billing` is null if billing is not configured
+        - Send limit resets at the top of each hour
+        """
+        return self._get(
+            "/usage",
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=UsageRetrieveResponse,
+        )
+
+
+class AsyncUsageResource(AsyncAPIResource):
+    @cached_property
+    def with_raw_response(self) -> AsyncUsageResourceWithRawResponse:
+        """
+        This property can be used as a prefix for any HTTP method call to return
+        the raw response object instead of the parsed content.
+
+        For more information, see https://www.github.com/ArkHQ-io/ark-python#accessing-raw-response-data-eg-headers
+        """
+        return AsyncUsageResourceWithRawResponse(self)
+
+    @cached_property
+    def with_streaming_response(self) -> AsyncUsageResourceWithStreamingResponse:
+        """
+        An alternative to `.with_raw_response` that doesn't eagerly read the response body.
+
+        For more information, see https://www.github.com/ArkHQ-io/ark-python#with_streaming_response
+        """
+        return AsyncUsageResourceWithStreamingResponse(self)
+
+    async def retrieve(
+        self,
+        *,
+        # 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,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> UsageRetrieveResponse:
+        """
+        Returns current usage and limit information for your account.
+
+        This endpoint is designed for:
+
+        - **AI agents/MCP servers:** Check constraints before planning batch operations
+        - **Monitoring dashboards:** Display current usage status
+        - **Rate limit awareness:** Know remaining capacity before making requests
+
+        **Response includes:**
+
+        - `rateLimit` - API request rate limit (requests per second)
+        - `sendLimit` - Email sending limit (emails per hour)
+        - `billing` - Credit balance and auto-recharge configuration
+
+        **Notes:**
+
+        - This request counts against your rate limit
+        - `sendLimit` may be null if Postal is temporarily unavailable
+        - `billing` is null if billing is not configured
+        - Send limit resets at the top of each hour
+        """
+        return await self._get(
+            "/usage",
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=UsageRetrieveResponse,
+        )
+
+
+class UsageResourceWithRawResponse:
+    def __init__(self, usage: UsageResource) -> None:
+        self._usage = usage
+
+        self.retrieve = to_raw_response_wrapper(
+            usage.retrieve,
+        )
+
+
+class AsyncUsageResourceWithRawResponse:
+    def __init__(self, usage: AsyncUsageResource) -> None:
+        self._usage = usage
+
+        self.retrieve = async_to_raw_response_wrapper(
+            usage.retrieve,
+        )
+
+
+class UsageResourceWithStreamingResponse:
+    def __init__(self, usage: UsageResource) -> None:
+        self._usage = usage
+
+        self.retrieve = to_streamed_response_wrapper(
+            usage.retrieve,
+        )
+
+
+class AsyncUsageResourceWithStreamingResponse:
+    def __init__(self, usage: AsyncUsageResource) -> None:
+        self._usage = usage
+
+        self.retrieve = async_to_streamed_response_wrapper(
+            usage.retrieve,
+        )