Skip to main content

adsefid

CI PyPI

A Python client for the adsefid.com SMS Web Service API. It sends SMS and Messenger messages (single, bulk, P2P and template), checks delivery status, cancels unsent messages, reads inbound SMS, looks up account data, and verifies signed webhooks. There is a sync client and an async client with the same methods.

It needs Python 3.10 or later and httpx, its only dependency. It is fully typed (py.typed) and verified against API documentation v1.14.0. Sibling SDKs exist for .NET, Go, JavaScript and PHP with the same shape.

Install

pip install adsefid

Quickstart

import os

from adsefid import AdsefidClient, LineSelector, SendSingleSmsRequest

with AdsefidClient(api_key=os.environ["ADSEFID_API_KEY"]) as client:
    result = client.sms.send_single(
        SendSingleSmsRequest(
            receptor="989120000000",
            line_number="983000",
            line_selector=LineSelector.BULK_SERVICE_SEND_BASED,
            message="Hello from adsefid",
        )
    )
    print(result.message_id, result.status)

The async client has the same surface with await:

import asyncio
import os

from adsefid import AdsefidAsyncClient, LineSelector, SendSingleSmsRequest


async def main() -> None:
    async with AdsefidAsyncClient(api_key=os.environ["ADSEFID_API_KEY"]) as client:
        result = await client.sms.send_single(
            SendSingleSmsRequest(
                receptor="989120000000",
                line_number="983000",
                line_selector=LineSelector.BULK_SERVICE_SEND_BASED,
                message="Hello",
            )
        )
        print(result.message_id, result.status)


asyncio.run(main())

The SDK never reads environment variables. Pass the API key yourself. It goes out as the X-API-KEY header on every request. Every request and response model is importable from the top level adsefid package.

Line selector. An account can own several lines with the same number, each with its own selector (see client.user.get_lines()). When it does, line_selector is required on every SMS send; without it the service answers LINE_NOT_FOUND.

Configuration

client = AdsefidClient(
    api_key="...",
    base_url="https://api.adsefid.com",  # default; must be an absolute http(s) URL
    timeout=30.0,  # seconds; positive and finite
    user_agent="my-service/1.0.0",  # default: adsefid-python/<SDK_VERSION>
    http_client=httpx.Client(...),  # optional; you own its lifecycle
)

ClientConfig validation raises AdsefidValidationError for a blank key, a bad URL, a bad timeout or a bad user agent. A client you pass in is never closed by the SDK.

To bound a single call, derive a client with its own timeout. It shares the connection pool, and closing it never closes the shared httpx client:

client.with_options(timeout=5).sms.send_single(request)

Money fields (cost, total_cost, credit_left) are decimal.Decimal, so you keep the exact amount the service sent.

Methods

Resource Methods Endpoint
client.sms send_single, send_bulk, send_p2p, send_template POST /v1/sms/{single,bulk,p2p,template}
client.sms get_status(message_ids=, local_ids=), cancel, get_received(line_number=, count=, since=) GET /v1/sms/status, POST /v1/sms/cancel, GET /v1/sms/receive
client.messenger send_single, send_bulk, send_p2p, send_template POST /v1/messenger/{single,bulk,p2p,template}
client.messenger upload_file(file, filename=, content_type=) POST /v1/messenger/file
client.messenger get_status(message_ids=, local_ids=), cancel GET /v1/messenger/status, POST /v1/messenger/cancel
client.user get_info, get_lines, get_profiles, get_templates(state=, skip=, take=) GET /v1/user/{info,lines,profiles,templates}

Request and response types are frozen dataclasses whose fields mirror the API's snake_case JSON. Cancel accepts messages that are awaiting approval, queued or scheduled, with no refund, and at most 2,000 distinct IDs across both lists. Status lookups are GET requests, so the URL caps them at about 200 IDs per call. The SDK raises a validation error past 8,000 URL characters instead of letting the gateway answer HTTP 414.

Bulk and P2P: partial success is not an error

A bulk or P2P call returns normally even when some items are rejected. Each item has raw_status, either a message status (1000 to 1999) or an error code (2000 and up). status is the typed message status and error_code is the typed error code. Each is None for the other range or for a code this SDK does not know yet:

from adsefid import BulkReceptor, SendBulkSmsRequest

result = client.sms.send_bulk(
    SendBulkSmsRequest(
        receptors=[BulkReceptor(receptor="989120000000"), BulkReceptor(receptor="989130000000")],
        message="Hello",
        line_number="983000",
        line_selector=LineSelector.BULK_SERVICE_SEND_BASED,
    )
)
for item in result.receptors:
    if item.error_code is not None:
        print(item.receptor, "rejected:", item.error_code.name)
    else:
        print(item.receptor, "accepted as", item.message_id)

Item values reach the API unchanged, so valid items still go out. If every item is rejected, the call raises AdsefidApiError with details.items listing each rejected index. Only request-level fields are checked locally.

Template parameters

A parameter the template declares as number can be sent as a number or a string. The service substitutes a numeric string as written, so a string is the only way to keep exact digits. A Decimal is sent as its exact decimal string:

from decimal import Decimal

client.sms.send_template(
    SendTemplateSmsRequest(
        template_id="invoice_notice",
        parameters={
            "invoice": "001234",  # renders 001234, not 1234
            "amount": Decimal("1.50"),  # renders 1.50, not 1.5
            "count": 2,
            "rate": 19.99,  # a float, so rounding is possible
        },
        receptor="09120000000",
        line_number="983000",
        line_selector=LineSelector.BULK_SERVICE_SEND_BASED,
    )
)

File upload

uploaded = client.messenger.upload_file("./brochure.pdf", content_type="application/pdf")
print(uploaded.file_id)

with open("./brochure.pdf", "rb") as f:  # bytes and open files work too
    uploaded = client.messenger.upload_file(
        f, filename="brochure.pdf", content_type="application/pdf"
    )

content_type is required. Content is limited to 15 MiB inclusive (MAX_MESSENGER_FILE_BYTES). A larger file raises AdsefidValidationError before any request is sent. The service also enforces a MIME allowlist and answers FILE_TOO_LARGE (2047) if it still objects to the size.

Errors

Every method raises on failure. All errors extend AdsefidError.

Error Meaning
AdsefidValidationError A local check failed. No request was sent.
AdsefidApiError The API returned an error envelope, or a non-2xx status without one. Has code, name, http_status_code and optional details.
AdsefidRateLimitError Subclass of AdsefidApiError. Codes 2035 and 2036, or any HTTP 429.
AdsefidTransportError Network failure, timeout, or a response that was not valid JSON or had a missing field.
AdsefidWebhookVerificationError A webhook failed verification.
from adsefid import (
    AdsefidApiError,
    AdsefidRateLimitError,
    AdsefidTransportError,
    AdsefidValidationError,
)

try:
    result = client.sms.send_single(request)
except AdsefidValidationError as e:
    print("invalid request:", e)
except AdsefidRateLimitError as e:  # catch before AdsefidApiError
    print("rate limited:", e.name)
except AdsefidApiError as e:
    print("API error:", e.code, e.name, e.http_status_code, e.details)
except AdsefidTransportError as e:
    print("transport failure:", e)

e.code is a WebServiceResponseCode when known and a plain int otherwise. A non-2xx response with no error envelope has code -1 and name UNKNOWN_ERROR. A bare 429 has code 2036 and name RATE_LIMITED. details.errors maps field names (or rejected cancel IDs) to field errors, and details.items carries indexed bulk/P2P errors. The SDK sends each request once and never retries. Pass an httpx client with a retrying transport if you want backoff.

Enums and unknown values

LineSelector, WebServiceMessageStatus, WebServiceResponseCode, TemplateState and TemplateParameterType live in adsefid.enums and the top-level package. A value the service adds later never raises: an unknown line selector stays an int, an unknown template state or parameter type stays a str, and an unknown status or error code is None next to its raw_status.

Webhooks

verify_and_parse_webhook checks the signature and timestamp, then returns a typed event. Give it the exact raw request bytes. A body that a framework already parsed will not verify.

import os

from flask import Flask, request

from adsefid import AdsefidWebhookVerificationError, verify_and_parse_webhook
from adsefid.webhooks import WebhookEventType, WebhookHeaders

app = Flask(__name__)


@app.post("/webhooks/adsefid")
def handle_webhook():
    try:
        event = verify_and_parse_webhook(
            raw_body=request.get_data(),  # raw bytes, not request.json
            signature_header=request.headers.get(WebhookHeaders.SIGNATURE, ""),
            timestamp_header=request.headers.get(WebhookHeaders.TIMESTAMP, ""),
            secret=os.environ["ADSEFID_WEBHOOK_SECRET"],
        )
    except AdsefidWebhookVerificationError:
        return "", 401  # do not say why

    match event.type:
        case WebhookEventType.RECEIVE:
            for item in event.data:
                print("SMS from", item.sender, item.message)
        case WebhookEventType.STATUS | WebhookEventType.MESSENGER_STATUS:
            for item in event.data:
                print("status", item.id, item.status_delivery)
    return {"ok": True}

The panel shows the signing secret Base64-encoded, and the service signs with the decoded bytes. Pass the secret exactly as shown, or pass the decoded key as bytes. An empty secret or key is always rejected. A stale timestamp (default 300 seconds, change it with max_age_seconds) or a bad signature raises AdsefidWebhookVerificationError.

In an ASGI framework, read the body with await request.body(). See examples/webhook_server.py (Flask) and examples/webhook_server_fastapi.py (FastAPI). Each endpoint only receives the event types you subscribed it to in the panel. Deliveries can repeat, so key your handler on WebhookHeaders.ID plus each item's id, and return a 2xx quickly.

Using this SDK with coding agents

AGENTS.md holds the repository rules. These points prevent most wrong guesses:

  • Pass the API key and webhook secret explicitly. The SDK reads no environment variables.
  • Treat a bulk or P2P response as data, not an error. Check each item.
  • Send exact numeric text ("001234", Decimal("1.50")) as a string or Decimal.
  • Give verify_and_parse_webhook raw bytes, never a re-serialized model.
  • There are no retries and no automatic batching. Split large requests yourself.
  • Catch AdsefidRateLimitError before AdsefidApiError, and branch on e.code.

Examples and contributing

Runnable samples are in examples/: account, quickstart, quickstart_async, bulk_and_p2p, templates, status_and_cancel, messenger, webhook_server and webhook_server_fastapi. account.py sends nothing, so try it first.

pip install "adsefid[examples]"
export ADSEFID_API_KEY=...
export ADSEFID_LINE_NUMBER=983000
python examples/quickstart.py

To work on the SDK: make deps (uses uv), then make lint, make test and make build. See AGENTS.md.

Versioning and license

Semantic Versioning, independent of the API documentation. SDK version 1.0.0, verified against API documentation v1.14.0. Releases use v<version> tags. See CHANGELOG.md. MIT licensed, see LICENSE.

Metadata

Release files for adsefid 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for adsefid 1.0.0
File Size Uploaded Provenance Actions
adsefid-1.0.0.tar.gz 32.4 kB With provenance Details for adsefid-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for adsefid 1.0.0
File Interpreter ABI Platform Actions
adsefid-1.0.0-py3-none-any.whl Python 3 none any Details for adsefid-1.0.0-py3-none-any.whl

Total release size: 69.7 kB

Release files / adsefid-1.0.0.tar.gz

Download URL adsefid-1.0.0.tar.gz
Size 32.4 kB
Tags Source
SHA-256 checksum
How to use checksums
b80b4807e070920c3c8aa8955a4d8520adeef486882fcdca7fb2a0f0738d3ab3
BLAKE2b-256 checksum
How to use checksums
480c76f768741d24b8852b7beeaef68575ed7934276fe5312c987f6c810b7954
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / adsefid-1.0.0-py3-none-any.whl

Download URL adsefid-1.0.0-py3-none-any.whl
Size 37.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
96a500ce9b19024b4b5d3e879005a7aa2a0a7b040a94d633a03b61d5361d9d9d
BLAKE2b-256 checksum
How to use checksums
c722f3e612a8467fac60b70d5454f3774429e75ed29b86c7e5917feaf9981096
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Security for adsefid 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for adsefid-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page