notletters-client 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- notletters/__init__.py +41 -0
- notletters/client.py +301 -0
- notletters/errors.py +88 -0
- notletters/py.typed +0 -0
- notletters/types.py +95 -0
- notletters_client-0.1.0.dist-info/METADATA +186 -0
- notletters_client-0.1.0.dist-info/RECORD +9 -0
- notletters_client-0.1.0.dist-info/WHEEL +4 -0
- notletters_client-0.1.0.dist-info/licenses/LICENSE +15 -0
notletters/__init__.py
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
from .client import NotLetters
|
|
2
|
+
from .errors import (
|
|
3
|
+
NotLettersBadRequestError,
|
|
4
|
+
NotLettersError,
|
|
5
|
+
NotLettersForbiddenError,
|
|
6
|
+
NotLettersInternalServerError,
|
|
7
|
+
NotLettersNotFoundError,
|
|
8
|
+
NotLettersPaymentRequiredError,
|
|
9
|
+
NotLettersUnauthorizedError,
|
|
10
|
+
create_notletters_error,
|
|
11
|
+
)
|
|
12
|
+
from .types import (
|
|
13
|
+
ChangePasswordResult,
|
|
14
|
+
EmailType,
|
|
15
|
+
Letter,
|
|
16
|
+
LetterBody,
|
|
17
|
+
LetterFilters,
|
|
18
|
+
Mail,
|
|
19
|
+
UserData,
|
|
20
|
+
parse_mail,
|
|
21
|
+
)
|
|
22
|
+
|
|
23
|
+
__all__ = [
|
|
24
|
+
"ChangePasswordResult",
|
|
25
|
+
"EmailType",
|
|
26
|
+
"Letter",
|
|
27
|
+
"LetterBody",
|
|
28
|
+
"LetterFilters",
|
|
29
|
+
"Mail",
|
|
30
|
+
"NotLetters",
|
|
31
|
+
"NotLettersBadRequestError",
|
|
32
|
+
"NotLettersError",
|
|
33
|
+
"NotLettersForbiddenError",
|
|
34
|
+
"NotLettersInternalServerError",
|
|
35
|
+
"NotLettersNotFoundError",
|
|
36
|
+
"NotLettersPaymentRequiredError",
|
|
37
|
+
"NotLettersUnauthorizedError",
|
|
38
|
+
"UserData",
|
|
39
|
+
"create_notletters_error",
|
|
40
|
+
"parse_mail",
|
|
41
|
+
]
|
notletters/client.py
ADDED
|
@@ -0,0 +1,301 @@
|
|
|
1
|
+
import os
|
|
2
|
+
from typing import Any
|
|
3
|
+
|
|
4
|
+
import httpx
|
|
5
|
+
|
|
6
|
+
from .errors import NotLettersError, create_notletters_error
|
|
7
|
+
from .types import (
|
|
8
|
+
ChangePasswordResult,
|
|
9
|
+
EmailType,
|
|
10
|
+
Letter,
|
|
11
|
+
LetterFilters,
|
|
12
|
+
Mail,
|
|
13
|
+
UserData,
|
|
14
|
+
parse_mail,
|
|
15
|
+
)
|
|
16
|
+
|
|
17
|
+
DEFAULT_BASE_URL = "https://api.notletters.com/v1"
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class NotLetters:
|
|
21
|
+
"""Client for the NotLetters email receiving and mailbox API.
|
|
22
|
+
|
|
23
|
+
Attributes:
|
|
24
|
+
api_token: API authentication token.
|
|
25
|
+
base_url: Base URL of the API.
|
|
26
|
+
"""
|
|
27
|
+
|
|
28
|
+
def __init__(
|
|
29
|
+
self,
|
|
30
|
+
api_token: str | None = None,
|
|
31
|
+
base_url: str | None = None,
|
|
32
|
+
timeout: float = 30.0,
|
|
33
|
+
user_agent: str | None = None,
|
|
34
|
+
) -> None:
|
|
35
|
+
"""Initializes the NotLetters client.
|
|
36
|
+
|
|
37
|
+
Args:
|
|
38
|
+
api_token: NotLetters API token. Defaults to NOTLETTERS_API_TOKEN
|
|
39
|
+
environment variable.
|
|
40
|
+
base_url: API base URL. Defaults to https://api.notletters.com/v1.
|
|
41
|
+
timeout: Timeout in seconds for HTTP requests. Defaults to 30.0.
|
|
42
|
+
user_agent: Custom User-Agent header string.
|
|
43
|
+
|
|
44
|
+
Examples:
|
|
45
|
+
>>> from notletters import NotLetters
|
|
46
|
+
>>> client = NotLetters(api_token="your-token")
|
|
47
|
+
>>> profile = client.get_me()
|
|
48
|
+
>>> print(profile["username"], profile["balance"])
|
|
49
|
+
"""
|
|
50
|
+
self.api_token = api_token or os.environ.get("NOTLETTERS_API_TOKEN")
|
|
51
|
+
self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
|
|
52
|
+
ua = user_agent or "notletters-client/0.1.0"
|
|
53
|
+
|
|
54
|
+
headers: dict[str, str] = {
|
|
55
|
+
"User-Agent": ua,
|
|
56
|
+
"Accept": "application/json",
|
|
57
|
+
"Content-Type": "application/json",
|
|
58
|
+
}
|
|
59
|
+
if self.api_token:
|
|
60
|
+
headers["Authorization"] = f"Bearer {self.api_token}"
|
|
61
|
+
|
|
62
|
+
self._client = httpx.Client(
|
|
63
|
+
base_url=self.base_url,
|
|
64
|
+
timeout=timeout,
|
|
65
|
+
headers=headers,
|
|
66
|
+
)
|
|
67
|
+
|
|
68
|
+
def close(self) -> None:
|
|
69
|
+
"""Closes the underlying HTTP client session."""
|
|
70
|
+
self._client.close()
|
|
71
|
+
|
|
72
|
+
def __enter__(self) -> "NotLetters":
|
|
73
|
+
return self
|
|
74
|
+
|
|
75
|
+
def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
|
|
76
|
+
self.close()
|
|
77
|
+
|
|
78
|
+
def _request(
|
|
79
|
+
self,
|
|
80
|
+
method: str,
|
|
81
|
+
path: str,
|
|
82
|
+
json_data: dict[str, Any] | None = None,
|
|
83
|
+
) -> Any:
|
|
84
|
+
try:
|
|
85
|
+
response = self._client.request(
|
|
86
|
+
method,
|
|
87
|
+
path,
|
|
88
|
+
json=json_data,
|
|
89
|
+
)
|
|
90
|
+
|
|
91
|
+
try:
|
|
92
|
+
data = response.json()
|
|
93
|
+
except Exception:
|
|
94
|
+
data = response.text
|
|
95
|
+
|
|
96
|
+
if response.status_code >= 400:
|
|
97
|
+
raise create_notletters_error(
|
|
98
|
+
status_code=response.status_code,
|
|
99
|
+
data=data,
|
|
100
|
+
fallback_message=f"HTTP {response.status_code} error",
|
|
101
|
+
)
|
|
102
|
+
|
|
103
|
+
if isinstance(data, dict) and "code" in data:
|
|
104
|
+
try:
|
|
105
|
+
code_num = int(data["code"])
|
|
106
|
+
if code_num >= 400:
|
|
107
|
+
raise create_notletters_error(
|
|
108
|
+
status_code=code_num,
|
|
109
|
+
data=data,
|
|
110
|
+
)
|
|
111
|
+
except (ValueError, TypeError):
|
|
112
|
+
pass
|
|
113
|
+
|
|
114
|
+
return data
|
|
115
|
+
except httpx.HTTPStatusError as e:
|
|
116
|
+
try:
|
|
117
|
+
data = e.response.json()
|
|
118
|
+
except Exception:
|
|
119
|
+
data = e.response.text
|
|
120
|
+
raise create_notletters_error(
|
|
121
|
+
status_code=e.response.status_code,
|
|
122
|
+
data=data,
|
|
123
|
+
fallback_message=str(e),
|
|
124
|
+
) from e
|
|
125
|
+
except httpx.RequestError as e:
|
|
126
|
+
raise NotLettersError(f"HTTP request failed: {e}") from e
|
|
127
|
+
|
|
128
|
+
def get_me(self) -> UserData:
|
|
129
|
+
"""Retrieves profile information and current balance for the authenticated user.
|
|
130
|
+
|
|
131
|
+
Returns:
|
|
132
|
+
Dictionary containing user ID, username, balance, and rate limit.
|
|
133
|
+
|
|
134
|
+
Examples:
|
|
135
|
+
>>> with NotLetters("your-token") as client:
|
|
136
|
+
... profile = client.get_me()
|
|
137
|
+
... print(f"User: {profile['username']}, Balance: {profile['balance']}")
|
|
138
|
+
"""
|
|
139
|
+
res = self._request("GET", "/me")
|
|
140
|
+
if not isinstance(res, dict) or "data" not in res:
|
|
141
|
+
raise NotLettersError(
|
|
142
|
+
"Invalid response format: missing data property",
|
|
143
|
+
response_body=res,
|
|
144
|
+
)
|
|
145
|
+
return res["data"]
|
|
146
|
+
|
|
147
|
+
def get_balance(self) -> float:
|
|
148
|
+
"""Convenience method to retrieve the current account balance.
|
|
149
|
+
|
|
150
|
+
Returns:
|
|
151
|
+
Current balance in rubles / account currency.
|
|
152
|
+
|
|
153
|
+
Examples:
|
|
154
|
+
>>> with NotLetters("your-token") as client:
|
|
155
|
+
... balance = client.get_balance()
|
|
156
|
+
... print(f"Balance: {balance}")
|
|
157
|
+
"""
|
|
158
|
+
profile = self.get_me()
|
|
159
|
+
return float(profile["balance"])
|
|
160
|
+
|
|
161
|
+
def get_letters(
|
|
162
|
+
self,
|
|
163
|
+
email: str,
|
|
164
|
+
password: str,
|
|
165
|
+
*,
|
|
166
|
+
search: str | None = None,
|
|
167
|
+
star: bool | None = None,
|
|
168
|
+
filters: LetterFilters | None = None,
|
|
169
|
+
) -> list[Letter]:
|
|
170
|
+
"""Retrieves email messages from a specific mailbox, with optional filters.
|
|
171
|
+
|
|
172
|
+
Args:
|
|
173
|
+
email: Mailbox email address.
|
|
174
|
+
password: Mailbox password.
|
|
175
|
+
search: Optional text query to search across message content, subject, and sender.
|
|
176
|
+
star: Optional flag to filter by starred status.
|
|
177
|
+
filters: Optional dictionary with 'search' and 'star' keys.
|
|
178
|
+
|
|
179
|
+
Returns:
|
|
180
|
+
List of retrieved email messages.
|
|
181
|
+
|
|
182
|
+
Examples:
|
|
183
|
+
>>> with NotLetters("your-token") as client:
|
|
184
|
+
... letters = client.get_letters(
|
|
185
|
+
... email="user@notletters.com",
|
|
186
|
+
... password="secret-password",
|
|
187
|
+
... search="Verification code",
|
|
188
|
+
... )
|
|
189
|
+
... for letter in letters:
|
|
190
|
+
... print(letter["subject"], letter["letter"]["text"])
|
|
191
|
+
"""
|
|
192
|
+
if not email:
|
|
193
|
+
raise NotLettersError("email is required")
|
|
194
|
+
if not password:
|
|
195
|
+
raise NotLettersError("password is required")
|
|
196
|
+
|
|
197
|
+
payload: dict[str, Any] = {
|
|
198
|
+
"email": email,
|
|
199
|
+
"password": password,
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
active_filters: dict[str, Any] = {}
|
|
203
|
+
if filters:
|
|
204
|
+
active_filters.update(filters)
|
|
205
|
+
if search is not None:
|
|
206
|
+
active_filters["search"] = search
|
|
207
|
+
if star is not None:
|
|
208
|
+
active_filters["star"] = star
|
|
209
|
+
|
|
210
|
+
if active_filters:
|
|
211
|
+
payload["filters"] = active_filters
|
|
212
|
+
|
|
213
|
+
res = self._request("POST", "/letters", json_data=payload)
|
|
214
|
+
if (
|
|
215
|
+
not isinstance(res, dict)
|
|
216
|
+
or "data" not in res
|
|
217
|
+
or not isinstance(res["data"], dict)
|
|
218
|
+
or "letters" not in res["data"]
|
|
219
|
+
or not isinstance(res["data"]["letters"], list)
|
|
220
|
+
):
|
|
221
|
+
raise NotLettersError(
|
|
222
|
+
"Invalid response format: missing letters list",
|
|
223
|
+
response_body=res,
|
|
224
|
+
)
|
|
225
|
+
|
|
226
|
+
return res["data"]["letters"]
|
|
227
|
+
|
|
228
|
+
def change_password(
|
|
229
|
+
self,
|
|
230
|
+
email: str,
|
|
231
|
+
new_password: str,
|
|
232
|
+
old_password: str,
|
|
233
|
+
) -> ChangePasswordResult:
|
|
234
|
+
"""Changes the password of an existing mailbox.
|
|
235
|
+
|
|
236
|
+
Args:
|
|
237
|
+
email: Mailbox email address.
|
|
238
|
+
new_password: New mailbox password.
|
|
239
|
+
old_password: Current mailbox password.
|
|
240
|
+
|
|
241
|
+
Returns:
|
|
242
|
+
Dictionary with response code and confirmation message.
|
|
243
|
+
|
|
244
|
+
Examples:
|
|
245
|
+
>>> with NotLetters("your-token") as client:
|
|
246
|
+
... res = client.change_password(
|
|
247
|
+
... email="user@notletters.com",
|
|
248
|
+
... old_password="old-password",
|
|
249
|
+
... new_password="new-password",
|
|
250
|
+
... )
|
|
251
|
+
... print(res["data"])
|
|
252
|
+
"""
|
|
253
|
+
if not email:
|
|
254
|
+
raise NotLettersError("email is required")
|
|
255
|
+
if not old_password:
|
|
256
|
+
raise NotLettersError("old_password is required")
|
|
257
|
+
if not new_password:
|
|
258
|
+
raise NotLettersError("new_password is required")
|
|
259
|
+
|
|
260
|
+
payload = {
|
|
261
|
+
"email": email,
|
|
262
|
+
"old_password": old_password,
|
|
263
|
+
"new_password": new_password,
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
return self._request("POST", "/change-password", json_data=payload)
|
|
267
|
+
|
|
268
|
+
def buy_emails(
|
|
269
|
+
self,
|
|
270
|
+
count: int,
|
|
271
|
+
type_email: int | EmailType = EmailType.LIMIT,
|
|
272
|
+
) -> list[Mail]:
|
|
273
|
+
"""Purchases email mailboxes. Note: this method charges the account balance.
|
|
274
|
+
|
|
275
|
+
Args:
|
|
276
|
+
count: Number of emails to buy (minimum 1).
|
|
277
|
+
type_email: Mailbox type code (LIMIT=0, UNLIMITED=1, RU_ZONE=2, PERSONAL=3).
|
|
278
|
+
|
|
279
|
+
Returns:
|
|
280
|
+
List of Mail objects containing email and password credentials.
|
|
281
|
+
|
|
282
|
+
Examples:
|
|
283
|
+
>>> from notletters import EmailType, NotLetters
|
|
284
|
+
>>> with NotLetters("your-token") as client:
|
|
285
|
+
... accounts = client.buy_emails(count=1, type_email=EmailType.LIMIT)
|
|
286
|
+
... for acc in accounts:
|
|
287
|
+
... print(f"Email: {acc.email}, Password: {acc.password}")
|
|
288
|
+
"""
|
|
289
|
+
if not isinstance(count, int) or count < 1:
|
|
290
|
+
raise NotLettersError("count must be an integer greater than or equal to 1")
|
|
291
|
+
|
|
292
|
+
payload = {
|
|
293
|
+
"count": count,
|
|
294
|
+
"type_email": int(type_email),
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
res = self._request("POST", "/buy-emails", json_data=payload)
|
|
298
|
+
if not isinstance(res, dict) or "data" not in res or not isinstance(res["data"], list):
|
|
299
|
+
raise NotLettersError("Invalid response format: missing data array", response_body=res)
|
|
300
|
+
|
|
301
|
+
return [parse_mail(item) for item in res["data"]]
|
notletters/errors.py
ADDED
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
from typing import Any
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
class NotLettersError(Exception):
|
|
5
|
+
"""Base exception for all NotLetters API errors."""
|
|
6
|
+
|
|
7
|
+
def __init__(
|
|
8
|
+
self,
|
|
9
|
+
message: str,
|
|
10
|
+
status_code: int | None = None,
|
|
11
|
+
code: str | None = None,
|
|
12
|
+
response_body: Any = None,
|
|
13
|
+
) -> None:
|
|
14
|
+
super().__init__(message)
|
|
15
|
+
self.message = message
|
|
16
|
+
self.status_code = status_code
|
|
17
|
+
self.code = code
|
|
18
|
+
self.response_body = response_body
|
|
19
|
+
|
|
20
|
+
def __str__(self) -> str:
|
|
21
|
+
if self.status_code:
|
|
22
|
+
return f"[{self.status_code}] {self.message}"
|
|
23
|
+
return self.message
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class NotLettersBadRequestError(NotLettersError):
|
|
27
|
+
"""Raised on 400 Bad Request."""
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class NotLettersUnauthorizedError(NotLettersError):
|
|
31
|
+
"""Raised on 401 Unauthorized."""
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
class NotLettersPaymentRequiredError(NotLettersError):
|
|
35
|
+
"""Raised on 402 Payment Required (e.g. insufficient funds)."""
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
class NotLettersForbiddenError(NotLettersError):
|
|
39
|
+
"""Raised on 403 Forbidden."""
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class NotLettersNotFoundError(NotLettersError):
|
|
43
|
+
"""Raised on 404 Not Found."""
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
class NotLettersInternalServerError(NotLettersError):
|
|
47
|
+
"""Raised on 500 Internal Server Error."""
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def create_notletters_error(
|
|
51
|
+
status_code: int | None = None,
|
|
52
|
+
data: Any = None,
|
|
53
|
+
fallback_message: str = "NotLetters API error",
|
|
54
|
+
) -> NotLettersError:
|
|
55
|
+
"""Creates the appropriate NotLettersError instance from an HTTP status and payload."""
|
|
56
|
+
message = fallback_message
|
|
57
|
+
code: str | None = None
|
|
58
|
+
|
|
59
|
+
if isinstance(data, str) and data.strip():
|
|
60
|
+
message = data.strip()
|
|
61
|
+
elif isinstance(data, dict):
|
|
62
|
+
raw_msg = data.get("error") or data.get("message") or data.get("detail")
|
|
63
|
+
if isinstance(raw_msg, str) and raw_msg.strip():
|
|
64
|
+
message = raw_msg.strip()
|
|
65
|
+
elif raw_msg is not None:
|
|
66
|
+
message = str(raw_msg)
|
|
67
|
+
|
|
68
|
+
if data.get("code") is not None:
|
|
69
|
+
code = str(data["code"])
|
|
70
|
+
elif isinstance(data.get("error"), str):
|
|
71
|
+
code = data["error"]
|
|
72
|
+
|
|
73
|
+
error_classes: dict[int, type[NotLettersError]] = {
|
|
74
|
+
400: NotLettersBadRequestError,
|
|
75
|
+
401: NotLettersUnauthorizedError,
|
|
76
|
+
402: NotLettersPaymentRequiredError,
|
|
77
|
+
403: NotLettersForbiddenError,
|
|
78
|
+
404: NotLettersNotFoundError,
|
|
79
|
+
500: NotLettersInternalServerError,
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
cls = error_classes.get(status_code, NotLettersError) if status_code else NotLettersError
|
|
83
|
+
return cls(
|
|
84
|
+
message=message,
|
|
85
|
+
status_code=status_code,
|
|
86
|
+
code=code,
|
|
87
|
+
response_body=data,
|
|
88
|
+
)
|
notletters/py.typed
ADDED
|
File without changes
|
notletters/types.py
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
from enum import IntEnum
|
|
2
|
+
from typing import TypedDict
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
class EmailType(IntEnum):
|
|
6
|
+
"""Types of emails available for purchase on NotLetters."""
|
|
7
|
+
|
|
8
|
+
LIMIT = 0
|
|
9
|
+
UNLIMITED = 1
|
|
10
|
+
RU_ZONE = 2
|
|
11
|
+
PERSONAL = 3
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class LetterFilters(TypedDict, total=False):
|
|
15
|
+
"""Filter criteria for searching emails."""
|
|
16
|
+
|
|
17
|
+
search: str
|
|
18
|
+
star: bool
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class LetterBody(TypedDict):
|
|
22
|
+
"""Body contents of an email message."""
|
|
23
|
+
|
|
24
|
+
html: str
|
|
25
|
+
text: str
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class Letter(TypedDict):
|
|
29
|
+
"""A retrieved email message."""
|
|
30
|
+
|
|
31
|
+
id: str
|
|
32
|
+
sender: str
|
|
33
|
+
sender_name: str
|
|
34
|
+
subject: str
|
|
35
|
+
letter: LetterBody
|
|
36
|
+
star: bool
|
|
37
|
+
date: int
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class UserData(TypedDict):
|
|
41
|
+
"""User profile information and balance."""
|
|
42
|
+
|
|
43
|
+
id: str
|
|
44
|
+
username: str
|
|
45
|
+
balance: float
|
|
46
|
+
rate_limit: int
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
class ChangePasswordResult(TypedDict):
|
|
50
|
+
"""Response returned when changing a mailbox password."""
|
|
51
|
+
|
|
52
|
+
code: int
|
|
53
|
+
data: str
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
class Mail(dict):
|
|
57
|
+
"""Purchased email account credentials."""
|
|
58
|
+
|
|
59
|
+
def __init__(self, raw: str) -> None:
|
|
60
|
+
raw_clean = raw.strip()
|
|
61
|
+
if ":" in raw_clean:
|
|
62
|
+
email, password = raw_clean.split(":", 1)
|
|
63
|
+
else:
|
|
64
|
+
email, password = raw_clean, ""
|
|
65
|
+
super().__init__(email=email, password=password, raw=raw_clean)
|
|
66
|
+
|
|
67
|
+
@property
|
|
68
|
+
def email(self) -> str:
|
|
69
|
+
"""The email address."""
|
|
70
|
+
return self["email"]
|
|
71
|
+
|
|
72
|
+
@property
|
|
73
|
+
def password(self) -> str:
|
|
74
|
+
"""The mailbox password."""
|
|
75
|
+
return self["password"]
|
|
76
|
+
|
|
77
|
+
@property
|
|
78
|
+
def raw(self) -> str:
|
|
79
|
+
"""The raw email:password string."""
|
|
80
|
+
return self["raw"]
|
|
81
|
+
|
|
82
|
+
def __str__(self) -> str:
|
|
83
|
+
return self["raw"]
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def parse_mail(raw: str) -> Mail:
|
|
87
|
+
"""Parses an email:password string into a Mail object.
|
|
88
|
+
|
|
89
|
+
Args:
|
|
90
|
+
raw: Raw credentials string (e.g. "user@notletters.com:pass123").
|
|
91
|
+
|
|
92
|
+
Returns:
|
|
93
|
+
A Mail object with email and password attributes and dict access.
|
|
94
|
+
"""
|
|
95
|
+
return Mail(raw)
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: notletters-client
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Python client for the NotLetters email receiving and mailbox API
|
|
5
|
+
Project-URL: Repository, https://github.com/TysikGG/api-kit
|
|
6
|
+
Project-URL: Documentation, https://notletters.com/user/documentation
|
|
7
|
+
License-Expression: ISC
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Requires-Python: >=3.10
|
|
10
|
+
Requires-Dist: httpx>=0.27
|
|
11
|
+
Description-Content-Type: text/markdown
|
|
12
|
+
|
|
13
|
+
# notletters-client
|
|
14
|
+
|
|
15
|
+
[](https://pypi.org/project/notletters-client/)
|
|
16
|
+
[](https://pypi.org/project/notletters-client/)
|
|
17
|
+
[](https://opensource.org/licenses/ISC)
|
|
18
|
+
|
|
19
|
+
Modern, typed Python client for the [NotLetters API](https://notletters.com). Manage disposable email mailboxes, retrieve incoming messages, search message contents, change mailbox passwords, and purchase mail accounts in bulk. Built on [HTTPX](https://www.python-httpx.org).
|
|
20
|
+
|
|
21
|
+
Official API documentation: <https://notletters.com/user/documentation>
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## Features
|
|
26
|
+
|
|
27
|
+
- ✉️ **Message Retrieval & Search** — Fetch incoming emails with full HTML and plain text bodies, search queries, and star filters.
|
|
28
|
+
- 📬 **Bulk Mailbox Purchase** — Order mailboxes programmatically across limit, unlimited, RU zone, and personal categories.
|
|
29
|
+
- 🔑 **Password Management** — Change passwords for managed mailboxes.
|
|
30
|
+
- 💰 **Account Information** — Check your account balance and rate limits.
|
|
31
|
+
- 🐍 **Modern Python** — Type-annotated, Google-style docstrings, context manager support (`with NotLetters(...) as client:`).
|
|
32
|
+
- 🚨 **Structured Errors** — Clear `NotLettersError` exceptions with subclasses for common HTTP status codes.
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Installation
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
pip install notletters-client
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Requires Python 3.10 or higher.
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## Quick Start (Safe Check)
|
|
47
|
+
|
|
48
|
+
The quick check only inspects your account balance and user profile. It does not purchase mailboxes or spend money.
|
|
49
|
+
|
|
50
|
+
```python
|
|
51
|
+
import os
|
|
52
|
+
from notletters import NotLetters
|
|
53
|
+
|
|
54
|
+
api_token = os.environ["NOTLETTERS_API_TOKEN"]
|
|
55
|
+
|
|
56
|
+
with NotLetters(api_token) as client:
|
|
57
|
+
profile = client.get_me()
|
|
58
|
+
print(f"Authenticated as: {profile['username']}")
|
|
59
|
+
print(f"Balance: {profile['balance']} RUB")
|
|
60
|
+
print(f"Rate limit: {profile['rate_limit']} req/min")
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Usage Guide
|
|
66
|
+
|
|
67
|
+
### 1. Retrieving Emails from a Mailbox
|
|
68
|
+
|
|
69
|
+
Retrieve incoming messages for a mailbox with optional text search and star filtering:
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
import os
|
|
73
|
+
from notletters import NotLetters
|
|
74
|
+
|
|
75
|
+
with NotLetters(os.environ["NOTLETTERS_API_TOKEN"]) as client:
|
|
76
|
+
letters = client.get_letters(
|
|
77
|
+
email="test@notletters.com",
|
|
78
|
+
password="mailbox-password",
|
|
79
|
+
search="Confirmation Code",
|
|
80
|
+
star=False,
|
|
81
|
+
)
|
|
82
|
+
|
|
83
|
+
for letter in letters:
|
|
84
|
+
print(f"ID: {letter['id']}")
|
|
85
|
+
print(f"From: {letter['sender_name']} <{letter['sender']}>")
|
|
86
|
+
print(f"Subject: {letter['subject']}")
|
|
87
|
+
print(f"Text body: {letter['letter']['text']}")
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### 2. Changing Mailbox Password
|
|
91
|
+
|
|
92
|
+
Update the password of an existing mailbox:
|
|
93
|
+
|
|
94
|
+
```python
|
|
95
|
+
import os
|
|
96
|
+
from notletters import NotLetters
|
|
97
|
+
|
|
98
|
+
with NotLetters(os.environ["NOTLETTERS_API_TOKEN"]) as client:
|
|
99
|
+
res = client.change_password(
|
|
100
|
+
email="test@notletters.com",
|
|
101
|
+
old_password="old-password",
|
|
102
|
+
new_password="new-password",
|
|
103
|
+
)
|
|
104
|
+
print(res["data"]) # "password successful changed"
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### 3. Purchasing Mailboxes
|
|
108
|
+
|
|
109
|
+
> [!WARNING]
|
|
110
|
+
> Purchasing mailboxes charges your NotLetters account balance.
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
import os
|
|
114
|
+
from notletters import EmailType, NotLetters
|
|
115
|
+
|
|
116
|
+
# EmailType:
|
|
117
|
+
# - EmailType.LIMIT (0) - Limited emails
|
|
118
|
+
# - EmailType.UNLIMITED (1) - Unlimited emails
|
|
119
|
+
# - EmailType.RU_ZONE (2) - Russian zone emails
|
|
120
|
+
# - EmailType.PERSONAL (3) - Personal emails
|
|
121
|
+
|
|
122
|
+
with NotLetters(os.environ["NOTLETTERS_API_TOKEN"]) as client:
|
|
123
|
+
accounts = client.buy_emails(count=2, type_email=EmailType.LIMIT)
|
|
124
|
+
|
|
125
|
+
for account in accounts:
|
|
126
|
+
print(f"Email: {account.email}")
|
|
127
|
+
print(f"Password: {account.password}")
|
|
128
|
+
print(f"Raw: {account.raw}")
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### 4. Parsing Credentials
|
|
132
|
+
|
|
133
|
+
Parse any raw `"email:password"` string into a structured object:
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
from notletters import parse_mail
|
|
137
|
+
|
|
138
|
+
account = parse_mail("user@notletters.com:pass123")
|
|
139
|
+
print(account.email) # "user@notletters.com"
|
|
140
|
+
print(account.password) # "pass123"
|
|
141
|
+
print(str(account)) # "user@notletters.com:pass123"
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## Error Handling
|
|
147
|
+
|
|
148
|
+
When the API returns an error, the client raises a `NotLettersError` with status code and payload details:
|
|
149
|
+
|
|
150
|
+
```python
|
|
151
|
+
import os
|
|
152
|
+
from notletters import (
|
|
153
|
+
NotLetters,
|
|
154
|
+
NotLettersBadRequestError,
|
|
155
|
+
NotLettersError,
|
|
156
|
+
NotLettersPaymentRequiredError,
|
|
157
|
+
NotLettersUnauthorizedError,
|
|
158
|
+
)
|
|
159
|
+
|
|
160
|
+
with NotLetters("invalid-token") as client:
|
|
161
|
+
try:
|
|
162
|
+
client.get_me()
|
|
163
|
+
except NotLettersUnauthorizedError:
|
|
164
|
+
print("Invalid or expired API token")
|
|
165
|
+
except NotLettersPaymentRequiredError:
|
|
166
|
+
print("Insufficient balance for operation")
|
|
167
|
+
except NotLettersError as err:
|
|
168
|
+
print(f"NotLetters API error [{err.status_code}]: {err.message}")
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
---
|
|
172
|
+
|
|
173
|
+
## Configuration Options
|
|
174
|
+
|
|
175
|
+
| Option | Type | Default | Description |
|
|
176
|
+
| :--- | :--- | :--- | :--- |
|
|
177
|
+
| `api_token` | `str \| None` | `os.environ.get("NOTLETTERS_API_TOKEN")` | Bearer token for API authentication |
|
|
178
|
+
| `base_url` | `str \| None` | `https://api.notletters.com/v1` | Custom base URL for the API |
|
|
179
|
+
| `timeout` | `float` | `30.0` | Request timeout in seconds |
|
|
180
|
+
| `user_agent` | `str \| None` | `notletters-client/0.1.0` | Custom User-Agent header |
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
184
|
+
## License
|
|
185
|
+
|
|
186
|
+
[ISC](LICENSE)
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
notletters/__init__.py,sha256=ksBdWxQJWoI25ZIVN1my3UpRM-IpeuR57CnRTpwWDmM,887
|
|
2
|
+
notletters/client.py,sha256=T6ZaQ-MMiELr-Iet7GM2lzGzuKO3rl0rMxVBHcGLIZs,9856
|
|
3
|
+
notletters/errors.py,sha256=WaPGg5qAEpcFladRcVr4Ed21iPlhPquWLI9b4ZRLDSY,2556
|
|
4
|
+
notletters/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
5
|
+
notletters/types.py,sha256=EGODuz8qUs3eKxPK9VhVcbl_cFPoVVVk278tX6oaux8,1948
|
|
6
|
+
notletters_client-0.1.0.dist-info/METADATA,sha256=S_66-x74rTm4aPCrPaiIKhsdlp9FQKHv6LoqaOr1O3s,5668
|
|
7
|
+
notletters_client-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
8
|
+
notletters_client-0.1.0.dist-info/licenses/LICENSE,sha256=8S0uYmn_aeljwFudfBoV91HcIo79yab9s0yhMVsOHJ0,751
|
|
9
|
+
notletters_client-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
ISC License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 api-kit contributors
|
|
4
|
+
|
|
5
|
+
Permission to use, copy, modify, and/or distribute this software for any
|
|
6
|
+
purpose with or without fee is hereby granted, provided that the above
|
|
7
|
+
copyright notice and this permission notice appear in all copies.
|
|
8
|
+
|
|
9
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
10
|
+
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
11
|
+
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
12
|
+
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
13
|
+
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
14
|
+
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
15
|
+
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|