Skip to content

Commit 9072375

Browse files
authored
docs: update README for v2 API (#14)
1 parent f9d697f commit 9072375

1 file changed

Lines changed: 76 additions & 18 deletions

File tree

README.md

Lines changed: 76 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
[![License](https://img.shields.io/github/license/lettermint/lettermint-python?style=flat-square)](https://github.com/lettermint/lettermint-python/blob/main/LICENSE)
88
[![Join our Discord server](https://img.shields.io/discord/1305510095588819035?logo=discord&logoColor=eee&label=Discord&labelColor=464ce5&color=0D0E28&cacheSeconds=43200)](https://lettermint.co/r/discord)
99

10-
Official Python SDK for the [Lettermint](https://lettermint.co) email API.
10+
Official Python SDK for the [Lettermint](https://lettermint.co) sending and team APIs.
1111

1212
## Installation
1313

@@ -22,10 +22,10 @@ pip install lettermint
2222
```python
2323
from lettermint import Lettermint
2424

25-
client = Lettermint(api_token="your-api-token")
25+
email = Lettermint.email("your-sending-token")
2626

2727
response = (
28-
client.email
28+
email
2929
.from_("sender@example.com")
3030
.to("recipient@example.com")
3131
.subject("Hello from Python!")
@@ -42,16 +42,24 @@ print(response["message_id"])
4242
```python
4343
from lettermint import AsyncLettermint
4444

45-
async with AsyncLettermint(api_token="your-api-token") as client:
46-
response = await (
47-
client.email
48-
.from_("sender@example.com")
49-
.to("recipient@example.com")
50-
.subject("Hello from Python!")
51-
.html("<h1>Welcome!</h1>")
52-
.send()
53-
)
54-
print(response["message_id"])
45+
email = AsyncLettermint.email("your-sending-token")
46+
47+
response = await (
48+
email
49+
.from_("sender@example.com")
50+
.to("recipient@example.com")
51+
.subject("Hello from Python!")
52+
.html("<h1>Welcome!</h1>")
53+
.send()
54+
)
55+
print(response["message_id"])
56+
```
57+
58+
The legacy constructor still works for sending-only usage:
59+
60+
```python
61+
client = Lettermint(api_token="your-sending-token")
62+
client.email.from_("sender@example.com").to("recipient@example.com").subject("Hello").send()
5563
```
5664

5765
## Email Options
@@ -146,6 +154,56 @@ client.email.from_("sender@example.com").to("recipient@example.com").subject(
146154
).idempotency_key("unique-request-id").send()
147155
```
148156

157+
### Batch Sending
158+
159+
```python
160+
email = Lettermint.email("your-sending-token")
161+
162+
response = email.send_batch([
163+
{
164+
"from": "sender@example.com",
165+
"to": ["recipient@example.com"],
166+
"subject": "Hello from Python!",
167+
"text": "This is a batch email.",
168+
}
169+
])
170+
```
171+
172+
Both sync and async sending clients support `ping()`:
173+
174+
```python
175+
email.ping()
176+
await AsyncLettermint.email("your-sending-token").ping()
177+
```
178+
179+
## Team API
180+
181+
Use a team API token with `Lettermint.api(...)`. API tokens authenticate with `Authorization: Bearer ...` and are separate from project sending tokens.
182+
183+
```python
184+
from lettermint import Lettermint
185+
186+
api = Lettermint.api("your-api-token")
187+
188+
domains = api.domains.list({"page[size]": "10"})
189+
team = api.team.retrieve()
190+
message_html = api.messages.html("message-id")
191+
pong = api.ping()
192+
```
193+
194+
The async Team API client is available through `AsyncLettermint.api(...)`:
195+
196+
```python
197+
from lettermint import AsyncLettermint
198+
199+
api = AsyncLettermint.api("your-api-token")
200+
201+
domains = await api.domains.list({"page[size]": "10"})
202+
message_html = await api.messages.html("message-id")
203+
```
204+
205+
Endpoint groups are available as `domains`, `messages`, `projects`, `routes`, `stats`, `suppressions`, `team`, and `webhooks`.
206+
149207
## Webhook Verification
150208

151209
Verify webhook signatures to ensure authenticity:
@@ -201,7 +259,7 @@ from lettermint.exceptions import (
201259
TimeoutError,
202260
)
203261

204-
client = Lettermint(api_token="your-api-token")
262+
client = Lettermint(api_token="your-sending-token")
205263

206264
try:
207265
response = client.email.from_("sender@example.com").to("recipient@example.com").subject(
@@ -251,7 +309,7 @@ except WebhookVerificationError as e:
251309

252310
```python
253311
client = Lettermint(
254-
api_token="your-api-token",
312+
api_token="your-sending-token",
255313
base_url="https://custom.api.com/v1",
256314
)
257315
```
@@ -260,7 +318,7 @@ client = Lettermint(
260318

261319
```python
262320
client = Lettermint(
263-
api_token="your-api-token",
321+
api_token="your-sending-token",
264322
timeout=60.0, # 60 seconds
265323
)
266324
```
@@ -271,11 +329,11 @@ Both sync and async clients support context managers for proper resource cleanup
271329

272330
```python
273331
# Sync
274-
with Lettermint(api_token="your-api-token") as client:
332+
with Lettermint(api_token="your-sending-token") as client:
275333
client.email.from_("sender@example.com").to("recipient@example.com").send()
276334

277335
# Async
278-
async with AsyncLettermint(api_token="your-api-token") as client:
336+
async with AsyncLettermint(api_token="your-sending-token") as client:
279337
await client.email.from_("sender@example.com").to("recipient@example.com").send()
280338
```
281339

0 commit comments

Comments
 (0)