sendio 1.0.0__py3-none-any.whl

sendio/__init__.py

@@ -0,0 +1,302 @@
+import os
+from typing import Optional, Union
+
+from .api_keys._api_key import ApiKey
+from .api_keys._api_keys import ApiKeys
+from .audiences._audience import Audience
+from .audiences._audiences import Audiences
+from .automations._automation import (Automation, AutomationConnection,
+                                      AutomationConnectionType,
+                                      AutomationListItem,
+                                      AutomationResponseStep, AutomationRun,
+                                      AutomationRunListItem,
+                                      AutomationRunStatus, AutomationRunStep,
+                                      AutomationStatus, AutomationStep,
+                                      AutomationStepType, WebhookFormField,
+                                      WebhookHeader, WebhookStepConfig)
+from .automations._automation_template import (AutomationEmail,
+                                               AutomationTemplate,
+                                               AutomationTemplateCategory,
+                                               AutomationTemplateDetail,
+                                               AutomationTemplateEmail,
+                                               AutomationTemplateEvent,
+                                               AutomationTemplateEventDetail,
+                                               AutomationTemplateKind,
+                                               AutomationTemplateParam,
+                                               AutomationTemplateStep)
+from .automations._automations import Automations
+from .broadcasts._broadcast import Broadcast
+from .broadcasts._broadcast_recipient import (BroadcastRecipient,
+                                              BroadcastRecipientBounceType,
+                                              BroadcastRecipientClickedLink,
+                                              BroadcastRecipientEventType)
+from .broadcasts._broadcast_version import BroadcastVersion
+from .broadcasts._broadcasts import Broadcasts
+from .broadcasts._clicked_link import ClickedLink
+from .contact_properties._contact_properties import ContactProperties
+from .contact_properties._contact_property import ContactProperty
+from .contacts._contact import Contact
+from .contacts._contact_topic import ContactTopic, TopicSubscriptionUpdate
+from .contacts._contacts import Contacts
+from .contacts._topics import Topics as ContactsTopics
+from .contacts.imports._contact_import import (ContactImport,
+                                               ContactImportCounts)
+from .contacts.imports._contact_imports import ContactImports
+from .contacts.segments._contact_segment import ContactSegment
+from .contacts.segments._contact_segments import ContactSegments
+from .domains._domain import Domain, DomainCapabilities, DomainCapabilityStatus
+from .domains._domains import Domains
+from .emails._attachment import Attachment, RemoteAttachment
+from .emails._attachments import Attachments as EmailAttachments
+from .emails._batch import Batch, BatchValidationError
+from .emails._email import Email
+from .emails._emails import Emails, EmailTemplate
+from .emails._received_email import (AttachmentWithSignedUrl, EmailAttachment,
+                                     EmailAttachmentDetails, ListReceivedEmail,
+                                     ReceivedEmail)
+from .emails._receiving import Receiving as EmailsReceiving
+from .emails._tag import Tag
+from .events._event import (Event, EventListItem, EventSchema,
+                            EventSchemaFieldType)
+from .events._events import Events
+from .http_client import HTTPClient
+from .http_client_async import \
+    AsyncHTTPClient  # Okay to import AsyncHTTPClient since it is just an interface.
+from .http_client_requests import RequestsClient
+from .logs._log import Log
+from .logs._logs import Logs
+from .mailboxes._mailbox import (Mailbox, MailboxCredentials, MailboxHealth,
+                                 MailboxImapSmtpStatus, MailboxKind,
+                                 MailboxServer)
+from .mailboxes._mailboxes import Mailboxes
+from .oauth_grants._oauth_grant import OAuthGrant, OAuthGrantClient
+from .oauth_grants._oauth_grants import OAuthGrants
+from .request import Request
+from .segments._segment import Segment
+from .segments._segments import Segments
+from .suppressions._suppression import (Suppression, SuppressionListItem,
+                                        SuppressionOrigin)
+from .suppressions._suppressions import Suppressions
+from .suppressions.batch._suppressions_batch import (BatchRemovedSuppression,
+                                                     BatchSuppression,
+                                                     SuppressionsBatch)
+from .templates._template import Template, TemplateListItem, Variable
+from .templates._templates import Templates
+from .topics._topic import Topic
+from .topics._topics import Topics
+from .usage._usage import (AiCreditsUsage, AutomationRunsUsage,
+                           BroadcastsUsage, ContactsUsage, DomainsUsage,
+                           EmailsDailyUsage, EmailsMonthlyUsage, EmailsUsage,
+                           RateLimitUsage, SegmentsUsage, Usage)
+from .version import __version__, get_version
+from .webhooks._webhook import (VerifyWebhookOptions, Webhook, WebhookEvent,
+                                WebhookHeaders, WebhookStatus)
+from .webhooks._webhook_event import (BaseEmailEventData, ContactCreatedEvent,
+                                      ContactDeletedEvent, ContactEventData,
+                                      ContactTopicsEventData,
+                                      ContactTopicSubscription,
+                                      ContactTopicsUpdatedEvent,
+                                      ContactUpdatedEvent, DomainCreatedEvent,
+                                      DomainDeletedEvent, DomainEventData,
+                                      DomainUpdatedEvent, EmailBouncedEvent,
+                                      EmailClickedEvent, EmailComplainedEvent,
+                                      EmailDeliveredEvent,
+                                      EmailDeliveryDelayedEvent,
+                                      EmailFailedEvent, EmailOpenedEvent,
+                                      EmailReceivedEvent, EmailScheduledEvent,
+                                      EmailSentEvent, EmailSuppressedEvent,
+                                      ReceivedEmailEventData,
+                                      SuppressionAddedEvent,
+                                      SuppressionEventData,
+                                      SuppressionRemovedEvent,
+                                      TopicCreatedEvent, TopicDeletedEvent,
+                                      TopicEventData, TopicUpdatedEvent,
+                                      WebhookEventPayload)
+from .webhooks._webhooks import Webhooks
+
+# Type for clients that support both sync and async
+SendioHTTPClient = Union[HTTPClient, AsyncHTTPClient]
+
+# Sync HTTP client — always set, can be overridden with a custom HTTPClient.
+default_http_client: SendioHTTPClient = RequestsClient()
+
+# Async HTTP client — auto-detected if httpx is installed, can be overridden
+# with any AsyncHTTPClient subclass. Set to None if no async library is available.
+default_async_http_client: Optional[AsyncHTTPClient] = None
+
+# Config vars
+api_key = os.environ.get("SENDIO_API_KEY")
+api_url = os.environ.get("SENDIO_BASE_URL", "https://api.send.io")
+
+
+__all__ = [
+    "__version__",
+    "get_version",
+    "Request",
+    "Emails",
+    "ApiKeys",
+    "Domains",
+    "Batch",
+    "Audiences",
+    "Automations",
+    "Contacts",
+    "ContactImports",
+    "ContactProperties",
+    "Broadcasts",
+    "Events",
+    "Segments",
+    "Templates",
+    "Webhooks",
+    "Topics",
+    "Logs",
+    "Mailboxes",
+    "OAuthGrants",
+    "Suppressions",
+    "SuppressionsBatch",
+    "Usage",
+    # Types
+    "Audience",
+    "Automation",
+    "AutomationConnection",
+    "AutomationConnectionType",
+    "AutomationListItem",
+    "AutomationResponseStep",
+    "AutomationRun",
+    "AutomationRunListItem",
+    "AutomationRunStatus",
+    "AutomationRunStep",
+    "AutomationStatus",
+    "AutomationStep",
+    "AutomationStepType",
+    "AutomationEmail",
+    "AutomationTemplate",
+    "AutomationTemplateCategory",
+    "AutomationTemplateDetail",
+    "AutomationTemplateEmail",
+    "AutomationTemplateEvent",
+    "AutomationTemplateEventDetail",
+    "AutomationTemplateKind",
+    "AutomationTemplateParam",
+    "AutomationTemplateStep",
+    "WebhookFormField",
+    "WebhookHeader",
+    "WebhookStepConfig",
+    "Event",
+    "EventListItem",
+    "EventSchema",
+    "EventSchemaFieldType",
+    "Contact",
+    "ContactImport",
+    "ContactImportCounts",
+    "ContactSegment",
+    "ContactSegments",
+    "ContactProperty",
+    "ContactTopic",
+    "TopicSubscriptionUpdate",
+    "Domain",
+    "DomainCapabilities",
+    "DomainCapabilityStatus",
+    "ApiKey",
+    "Log",
+    "Mailbox",
+    "MailboxCredentials",
+    "MailboxHealth",
+    "MailboxImapSmtpStatus",
+    "MailboxKind",
+    "MailboxServer",
+    "Email",
+    "Attachment",
+    "RemoteAttachment",
+    "EmailTemplate",
+    "Tag",
+    "Broadcast",
+    "ClickedLink",
+    "BroadcastRecipient",
+    "BroadcastRecipientBounceType",
+    "BroadcastRecipientClickedLink",
+    "BroadcastRecipientEventType",
+    "BroadcastVersion",
+    "Segment",
+    "Suppression",
+    "SuppressionListItem",
+    "SuppressionOrigin",
+    "BatchSuppression",
+    "BatchRemovedSuppression",
+    "Template",
+    "TemplateListItem",
+    "Variable",
+    "Webhook",
+    "WebhookEvent",
+    "WebhookEventPayload",
+    "WebhookHeaders",
+    "WebhookStatus",
+    "VerifyWebhookOptions",
+    "BaseEmailEventData",
+    "ReceivedEmailEventData",
+    "ContactEventData",
+    "DomainEventData",
+    "EmailSentEvent",
+    "EmailScheduledEvent",
+    "EmailDeliveredEvent",
+    "EmailDeliveryDelayedEvent",
+    "EmailComplainedEvent",
+    "EmailBouncedEvent",
+    "EmailOpenedEvent",
+    "EmailClickedEvent",
+    "EmailReceivedEvent",
+    "EmailFailedEvent",
+    "EmailSuppressedEvent",
+    "ContactCreatedEvent",
+    "ContactUpdatedEvent",
+    "ContactDeletedEvent",
+    "ContactTopicsEventData",
+    "ContactTopicsUpdatedEvent",
+    "ContactTopicSubscription",
+    "DomainCreatedEvent",
+    "DomainUpdatedEvent",
+    "DomainDeletedEvent",
+    "SuppressionEventData",
+    "SuppressionAddedEvent",
+    "SuppressionRemovedEvent",
+    "TopicEventData",
+    "TopicCreatedEvent",
+    "TopicUpdatedEvent",
+    "TopicDeletedEvent",
+    "Topic",
+    "OAuthGrant",
+    "OAuthGrantClient",
+    "BatchValidationError",
+    "ReceivedEmail",
+    "EmailAttachment",
+    "AttachmentWithSignedUrl",
+    "EmailAttachmentDetails",
+    "ListReceivedEmail",
+    # Receiving types (for type hints)
+    "EmailsReceiving",
+    "EmailAttachments",
+    "ContactsTopics",
+    "EmailsUsage",
+    "EmailsDailyUsage",
+    "EmailsMonthlyUsage",
+    "ContactsUsage",
+    "SegmentsUsage",
+    "BroadcastsUsage",
+    "AiCreditsUsage",
+    "AutomationRunsUsage",
+    "DomainsUsage",
+    "RateLimitUsage",
+    # HTTP Clients
+    "HTTPClient",
+    # Default HTTP Client
+    "RequestsClient",
+]
+
+# Add async exports and auto-detect async client if httpx is available
+try:
+    from .async_request import AsyncRequest  # noqa: F401
+    from .http_client_httpx import HTTPXClient  # noqa: F401
+
+    default_async_http_client = HTTPXClient()
+    __all__.extend(["AsyncHTTPClient", "HTTPXClient", "AsyncRequest"])
+except ImportError:
+    pass

sendio/_base_response.py

@@ -0,0 +1,16 @@
+"""Base response type for all send.io API responses."""
+
+from typing import Dict
+
+from typing_extensions import NotRequired, TypedDict
+
+
+class BaseResponse(TypedDict):
+    """Base response type that all API responses inherit from.
+
+    Attributes:
+        http_headers: HTTP response headers including rate limit info, request IDs, etc.
+                      Optional field that may not be present in all responses.
+    """
+
+    http_headers: NotRequired[Dict[str, str]]

sendio/api_keys/_api_key.py

@@ -0,0 +1,22 @@
+from typing import Optional
+
+from typing_extensions import TypedDict
+
+
+class ApiKey(TypedDict):
+    id: str
+    """
+    The API key ID
+    """
+    name: str
+    """
+    The API key name
+    """
+    created_at: str
+    """
+    The API key creation date
+    """
+    last_used_at: Optional[str]
+    """
+    The date and time the API key was last used, or None if never used
+    """

sendio/api_keys/_api_keys.py

@@ -0,0 +1,301 @@
+from typing import Any, Dict, List, Optional, cast
+
+from typing_extensions import NotRequired, TypedDict
+
+from sendio import request
+from sendio._base_response import BaseResponse
+from sendio.api_keys._api_key import ApiKey
+from sendio.pagination_helper import PaginationHelper
+
+# Async imports (optional - only available with pip install sendio[async])
+try:
+    from sendio.async_request import AsyncRequest
+except ImportError:
+    pass
+
+
+class ApiKeys:
+
+    class ListResponse(BaseResponse):
+        """
+        ListResponse type that wraps a list of API key objects with pagination metadata
+
+        Attributes:
+            object (str): The object type, always "list"
+            data (List[ApiKey]): A list of API key objects
+            has_more (bool): Whether there are more results available
+        """
+
+        object: str
+        """
+        The object type, always "list"
+        """
+        data: List[ApiKey]
+        """
+        A list of API key objects
+        """
+        has_more: bool
+        """
+        Whether there are more results available for pagination
+        """
+
+    class CreateApiKeyResponse(BaseResponse):
+        """
+        CreateApiKeyResponse is the type that wraps the response of the API key that was created
+
+        Attributes:
+            id (str): The ID of the created API key
+            token (str): The token of the created API key
+        """
+
+        id: str
+        """
+        The ID of the created API key
+        """
+        token: str
+        """
+        The token of the created API key
+        """
+
+    class DeleteApiKeyResponse(BaseResponse):
+        """
+        DeleteApiKeyResponse is the type that wraps the deleted API key response.
+
+        Attributes:
+            object (str): The object type, always "api_key"
+            id (str): The ID of the deleted API key
+            deleted (bool): Whether the API key was deleted
+        """
+
+        object: str
+        """
+        The object type, always "api_key"
+        """
+        id: str
+        """
+        The ID of the deleted API key
+        """
+        deleted: bool
+        """
+        Whether the API key was deleted
+        """
+
+    class UpdateApiKeyResponse(BaseResponse):
+        """
+        UpdateApiKeyResponse is the type that wraps the response of the API key that was updated
+
+        Attributes:
+            object (str): The object type, always "api_key"
+            id (str): The ID of the updated API key
+        """
+
+        object: str
+        """
+        The object type, always "api_key"
+        """
+        id: str
+        """
+        The ID of the updated API key
+        """
+
+    class ListParams(TypedDict):
+        limit: NotRequired[int]
+        """
+        Number of API keys to retrieve. Maximum is 100, and minimum is 1.
+        """
+        after: NotRequired[str]
+        """
+        The ID after which we'll retrieve more API keys (for pagination).
+        This ID will not be included in the returned list.
+        Cannot be used with the before parameter.
+        """
+        before: NotRequired[str]
+        """
+        The ID before which we'll retrieve more API keys (for pagination).
+        This ID will not be included in the returned list.
+        Cannot be used with the after parameter.
+        """
+
+    class CreateParams(TypedDict):
+        name: str
+        """
+        The API key name.
+        """
+        permission: NotRequired[str]
+        """
+        The API key can have full access to Sendio's API or be only
+        restricted to send emails. * full_access: Can create, delete, get,
+        and update any resource. * sending_access: Can only send emails.
+        """
+        domain_id: NotRequired[str]
+        """
+        Restrict an API key to send emails only from a specific domain.
+        This is only used when the permission is set to sending_access.
+        """
+
+    class UpdateParams(TypedDict):
+        id: str
+        """
+        The API key ID.
+        """
+        name: str
+        """
+        The API key name.
+        """
+
+    @classmethod
+    def create(cls, params: CreateParams) -> CreateApiKeyResponse:
+        """
+        Add a new API key to authenticate communications with Sendio.
+        see more: https://developer.send.io/docs/api
+
+        Args:
+            params (CreateParams): The API key creation parameters
+
+        Returns:
+            CreateApiKeyResponse: The created API key response with id and token
+        """
+        path = "/api-keys"
+        resp = request.Request[ApiKeys.CreateApiKeyResponse](
+            path=path, params=cast(Dict[Any, Any], params), verb="post"
+        ).perform_with_content()
+        return resp
+
+    @classmethod
+    def update(cls, params: UpdateParams) -> UpdateApiKeyResponse:
+        """
+        Update an existing API key's name.
+        see more: https://developer.send.io/docs/api
+
+        Args:
+            params (UpdateParams): The API key update parameters
+                - id: The API key ID
+                - name: The new API key name
+
+        Returns:
+            UpdateApiKeyResponse: The updated API key response with id
+        """
+        api_key_id = params["id"]
+        path = f"/api-keys/{api_key_id}"
+        resp = request.Request[ApiKeys.UpdateApiKeyResponse](
+            path=path, params={"name": params["name"]}, verb="patch"
+        ).perform_with_content()
+        return resp
+
+    @classmethod
+    def list(cls, params: Optional[ListParams] = None) -> ListResponse:
+        """
+        Retrieve a list of API keys for the authenticated user.
+        see more: https://developer.send.io/docs/api
+
+        Args:
+            params (Optional[ListParams]): Optional pagination parameters
+                - limit: Number of API keys to retrieve (max 100, min 1)
+                - after: ID after which to retrieve more API keys
+                - before: ID before which to retrieve more API keys
+
+        Returns:
+            ListResponse: A list of API key objects
+        """
+        base_path = "/api-keys"
+        query_params = cast(Dict[Any, Any], params) if params else None
+        path = PaginationHelper.build_paginated_path(base_path, query_params)
+        resp = request.Request[ApiKeys.ListResponse](
+            path=path, params={}, verb="get"
+        ).perform_with_content()
+        return resp
+
+    @classmethod
+    def remove(cls, api_key_id: str) -> DeleteApiKeyResponse:
+        """
+        Remove an existing API key.
+        see more: https://developer.send.io/docs/api
+
+        Args:
+            api_key_id (str): The ID of the API key to remove
+
+        Returns:
+            DeleteApiKeyResponse: The deleted API key response
+        """
+        path = f"/api-keys/{api_key_id}"
+        resp = request.Request[ApiKeys.DeleteApiKeyResponse](
+            path=path, params={}, verb="delete"
+        ).perform_with_content()
+        return resp
+
+    @classmethod
+    async def create_async(cls, params: CreateParams) -> CreateApiKeyResponse:
+        """
+        Add a new API key to authenticate communications with Sendio (async).
+        see more: https://developer.send.io/docs/api
+
+        Args:
+            params (CreateParams): The API key creation parameters
+
+        Returns:
+            CreateApiKeyResponse: The created API key response with id and token
+        """
+        path = "/api-keys"
+        resp = await AsyncRequest[ApiKeys.CreateApiKeyResponse](
+            path=path, params=cast(Dict[Any, Any], params), verb="post"
+        ).perform_with_content()
+        return resp
+
+    @classmethod
+    async def update_async(cls, params: UpdateParams) -> UpdateApiKeyResponse:
+        """
+        Update an existing API key's name (async).
+        see more: https://developer.send.io/docs/api
+
+        Args:
+            params (UpdateParams): The API key update parameters
+                - id: The API key ID
+                - name: The new API key name
+
+        Returns:
+            UpdateApiKeyResponse: The updated API key response with id
+        """
+        api_key_id = params["id"]
+        path = f"/api-keys/{api_key_id}"
+        resp = await AsyncRequest[ApiKeys.UpdateApiKeyResponse](
+            path=path, params={"name": params["name"]}, verb="patch"
+        ).perform_with_content()
+        return resp
+
+    @classmethod
+    async def list_async(cls, params: Optional[ListParams] = None) -> ListResponse:
+        """
+        Retrieve a list of API keys for the authenticated user (async).
+        see more: https://developer.send.io/docs/api
+
+        Args:
+            params (Optional[ListParams]): Optional pagination parameters
+
+        Returns:
+            ListResponse: A list of API key objects
+        """
+        base_path = "/api-keys"
+        query_params = cast(Dict[Any, Any], params) if params else None
+        path = PaginationHelper.build_paginated_path(base_path, query_params)
+        resp = await AsyncRequest[ApiKeys.ListResponse](
+            path=path, params={}, verb="get"
+        ).perform_with_content()
+        return resp
+
+    @classmethod
+    async def remove_async(cls, api_key_id: str) -> DeleteApiKeyResponse:
+        """
+        Remove an existing API key (async).
+        see more: https://developer.send.io/docs/api
+
+        Args:
+            api_key_id (str): The ID of the API key to remove
+
+        Returns:
+            DeleteApiKeyResponse: The deleted API key response
+        """
+        path = f"/api-keys/{api_key_id}"
+        resp = await AsyncRequest[ApiKeys.DeleteApiKeyResponse](
+            path=path, params={}, verb="delete"
+        ).perform_with_content()
+        return resp