canitsend-client 1.0.0__tar.gz

canitsend_client-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+.wrangler/
+data/kv-bulk.json
+data/verified.json
+data/discrepancies.json
+*.log
+.dev.vars
+public/

canitsend_client-1.0.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: canitsend-client
+Version: 1.0.0
+Summary: Client for the CanItSend API — SPF/DKIM/DMARC audit from live DNS, SPF flattening, and email validation.
+Project-URL: Homepage, https://canitsend.com
+Project-URL: Documentation, https://canitsend.com/docs
+Project-URL: Changelog, https://canitsend.com/docs
+Author: CanItSend
+License: MIT
+Keywords: deliverability,dkim,dmarc,dns,email,email-validation,smtp,spf
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Internet :: Name Service (DNS)
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# canitsend-client
+
+Zero-dependency Python client for the [CanItSend API](https://canitsend.com). Two questions, one API.
+
+```bash
+pip install canitsend-client
+```
+
+Every endpoint needs an API key. The **free tier includes 100 audits/month** — instant and self-serve: https://canitsend.com/#pricing
+
+```python
+from canitsend import CanItSendClient
+cis = CanItSendClient(api_key="snd_live_...")
+```
+
+## 1. Can my domain send?
+
+```python
+a = cis.check("acme.com")          # also accepts "you@acme.com" or a URL
+print(a["grade"], a["score"])      # F 40
+
+# Plain-language answer to "but my email works!"
+print(a["explanation"]["headline"])
+# -> "Your mail works — but you can't prove you sent it."
+
+# The exact records to paste, chosen for YOUR detected mail provider
+for r in a["suggestedRecords"]:
+    print(r["type"], r["host"], r["value"])
+# -> TXT @       v=spf1 include:_spf.google.com ~all
+# -> TXT _dmarc  v=DMARC1; p=none; rua=mailto:dmarc@acme.com
+```
+
+### The SPF 10-lookup limit
+
+Over 10 DNS lookups means **PermError — SPF fails entirely**, not partially.
+We count it correctly: `mx` costs **1**, not one per MX host. Most tools get this wrong.
+
+```python
+spf = cis.spf_check("acme.com")
+print(spf["lookupCount"], "/ 10", "PermError!" if spf["lookupLimitExceeded"] else "")
+
+print(cis.spf_flatten("acme.com")["flattened"])   # zero include-lookups
+```
+
+## 2. Should I send to this address?
+
+```python
+v = cis.validate("jane@gmial.com")
+print(v["verdict"])      # risky
+print(v["didYouMean"])   # jane@gmail.com
+
+cis.validate("test@mailinator.com")   # risky   - disposable
+cis.validate("support@acme.com")      # risky   - role account
+cis.validate("x@no-such.dev")         # invalid - no MX, will bounce
+```
+
+> **What we don't claim:** we do **not** verify the mailbox exists and do **not**
+> detect catch-alls. Both require an SMTP probe on port 25, which we deliberately
+> do not run. `mailboxVerified` is always `False`. The strongest verdict is
+> `deliverable_domain` — the *domain* accepts mail.
+
+**Bulk** (Agency+): `audit_bulk([...])` up to 100 domains · `validate_bulk([...])` up to 1,000 addresses.
+
+Errors raise `CanItSendError` with `.status` and `.problem` (RFC 9457).

canitsend_client-1.0.0/README.md

@@ -0,0 +1,64 @@
+# canitsend-client
+
+Zero-dependency Python client for the [CanItSend API](https://canitsend.com). Two questions, one API.
+
+```bash
+pip install canitsend-client
+```
+
+Every endpoint needs an API key. The **free tier includes 100 audits/month** — instant and self-serve: https://canitsend.com/#pricing
+
+```python
+from canitsend import CanItSendClient
+cis = CanItSendClient(api_key="snd_live_...")
+```
+
+## 1. Can my domain send?
+
+```python
+a = cis.check("acme.com")          # also accepts "you@acme.com" or a URL
+print(a["grade"], a["score"])      # F 40
+
+# Plain-language answer to "but my email works!"
+print(a["explanation"]["headline"])
+# -> "Your mail works — but you can't prove you sent it."
+
+# The exact records to paste, chosen for YOUR detected mail provider
+for r in a["suggestedRecords"]:
+    print(r["type"], r["host"], r["value"])
+# -> TXT @       v=spf1 include:_spf.google.com ~all
+# -> TXT _dmarc  v=DMARC1; p=none; rua=mailto:dmarc@acme.com
+```
+
+### The SPF 10-lookup limit
+
+Over 10 DNS lookups means **PermError — SPF fails entirely**, not partially.
+We count it correctly: `mx` costs **1**, not one per MX host. Most tools get this wrong.
+
+```python
+spf = cis.spf_check("acme.com")
+print(spf["lookupCount"], "/ 10", "PermError!" if spf["lookupLimitExceeded"] else "")
+
+print(cis.spf_flatten("acme.com")["flattened"])   # zero include-lookups
+```
+
+## 2. Should I send to this address?
+
+```python
+v = cis.validate("jane@gmial.com")
+print(v["verdict"])      # risky
+print(v["didYouMean"])   # jane@gmail.com
+
+cis.validate("test@mailinator.com")   # risky   - disposable
+cis.validate("support@acme.com")      # risky   - role account
+cis.validate("x@no-such.dev")         # invalid - no MX, will bounce
+```
+
+> **What we don't claim:** we do **not** verify the mailbox exists and do **not**
+> detect catch-alls. Both require an SMTP probe on port 25, which we deliberately
+> do not run. `mailboxVerified` is always `False`. The strongest verdict is
+> `deliverable_domain` — the *domain* accepts mail.
+
+**Bulk** (Agency+): `audit_bulk([...])` up to 100 domains · `validate_bulk([...])` up to 1,000 addresses.
+
+Errors raise `CanItSendError` with `.status` and `.problem` (RFC 9457).

canitsend_client-1.0.0/canitsend/__init__.py

@@ -0,0 +1,126 @@
+"""Client for the CanItSend API.
+
+Two questions, one API:
+
+  1. Can my domain send?      -> check() / audit() / spf_flatten()
+  2. Should I send to this?   -> validate() / validate_bulk()
+
+Every data endpoint needs an API key. The free tier includes 100 audits/month:
+https://canitsend.com/#pricing
+
+Standard library only (urllib) — no dependencies.
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Optional
+
+DEFAULT_BASE = "https://api.canitsend.com"
+
+__all__ = ["CanItSendClient", "CanItSendError"]
+
+
+class CanItSendError(Exception):
+    def __init__(self, status: int, problem: dict):
+        self.status = status
+        self.problem = problem
+        super().__init__(problem.get("detail") or problem.get("title") or f"HTTP {status}")
+
+
+class CanItSendClient:
+    def __init__(self, api_key: Optional[str] = None, base_url: str = DEFAULT_BASE):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+
+    def _request(self, method: str, path: str,
+                 params: Optional[dict] = None, body: Optional[dict] = None) -> Any:
+        url = self.base_url + path
+        if params:
+            clean = {k: v for k, v in params.items() if v not in (None, "")}
+            if clean:
+                url += "?" + urllib.parse.urlencode(clean)
+        data = json.dumps(body).encode() if body is not None else None
+        headers = {"accept": "application/json"}
+        if body is not None:
+            headers["content-type"] = "application/json"
+        if self.api_key:
+            headers["authorization"] = f"Bearer {self.api_key}"
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                return json.loads(resp.read().decode())
+        except urllib.error.HTTPError as e:
+            try:
+                problem = json.loads(e.read().decode())
+            except Exception:
+                problem = {"title": e.reason}
+            raise CanItSendError(e.code, problem) from None
+
+    # ── 1. Can my domain send? ───────────────────────────────────────────────
+
+    def check(self, domain: str, selectors: Optional[list[str]] = None) -> dict:
+        """Full audit: score, grade, explanation, and paste-in DNS records.
+
+        Accepts a domain, an email address, or a URL.
+        """
+        return self._request("GET", "/v1/check",
+                             {"domain": domain, "selectors": ",".join(selectors or [])})
+
+    def audit(self, domain: str, selectors: Optional[list[str]] = None) -> dict:
+        """Same payload as check(), on the metered audit route."""
+        return self._request("GET", "/v1/audit",
+                             {"domain": domain, "selectors": ",".join(selectors or [])})
+
+    def audit_bulk(self, domains: list[str]) -> dict:
+        """Up to 100 domains. Agency plan and above."""
+        return self._request("POST", "/v1/audit/bulk", body={"domains": domains})
+
+    def spf_check(self, domain: str) -> dict:
+        return self._request("GET", "/v1/spf/check", {"domain": domain})
+
+    def spf_flatten(self, domain: str) -> dict:
+        """Resolve every include: down to raw IPs — fixes the 10-lookup PermError."""
+        return self._request("GET", "/v1/spf/flatten", {"domain": domain})
+
+    def dmarc_parse(self, domain: str) -> dict:
+        return self._request("GET", "/v1/dmarc/parse", {"domain": domain})
+
+    def dkim_check(self, domain: str, selector: Optional[str] = None) -> dict:
+        return self._request("GET", "/v1/dkim/check", {"domain": domain, "selector": selector})
+
+    # ── 2. Should I send to this address? ────────────────────────────────────
+
+    def validate(self, email: str) -> dict:
+        """Pre-send validation: syntax, MX, disposable, role account, typo hint.
+
+        Verdicts: "invalid" | "risky" | "deliverable_domain".
+
+        NOTE: does NOT verify the mailbox exists and does NOT detect catch-alls.
+        Both require an SMTP probe on port 25, which we deliberately do not run.
+        ``mailboxVerified`` is always False.
+        """
+        return self._request("POST", "/v1/validate", body={"email": email})
+
+    def validate_bulk(self, emails: list[str]) -> dict:
+        """Up to 1,000 addresses. Agency plan and above."""
+        return self._request("POST", "/v1/validate/bulk", body={"emails": emails})
+
+    # ── Monitoring & account ─────────────────────────────────────────────────
+
+    def list_monitors(self) -> dict:
+        return self._request("GET", "/v1/monitor")
+
+    def create_monitor(self, domain: str, webhook_url: Optional[str] = None,
+                       frequency: str = "daily") -> dict:
+        return self._request("POST", "/v1/monitor",
+                             body={"domain": domain, "webhookUrl": webhook_url,
+                                   "frequency": frequency})
+
+    def delete_monitor(self, monitor_id: str) -> dict:
+        return self._request("DELETE", f"/v1/monitor/{monitor_id}")
+
+    def usage(self) -> dict:
+        return self._request("GET", "/v1/usage")

canitsend_client-1.0.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "canitsend-client"
+version = "1.0.0"
+description = "Client for the CanItSend API — SPF/DKIM/DMARC audit from live DNS, SPF flattening, and email validation."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["spf", "dkim", "dmarc", "email", "deliverability", "email-validation", "dns", "smtp"]
+authors = [{ name = "CanItSend" }]
+dependencies = []
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Communications :: Email",
+  "Topic :: Internet :: Name Service (DNS)",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://canitsend.com"
+Documentation = "https://canitsend.com/docs"
+Changelog = "https://canitsend.com/docs"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["canitsend"]