acumbamail 0.1.0__tar.gz
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.
- acumbamail-0.1.0/LICENSE +21 -0
- acumbamail-0.1.0/PKG-INFO +611 -0
- acumbamail-0.1.0/README.md +596 -0
- acumbamail-0.1.0/acumbamail/__init__.py +12 -0
- acumbamail-0.1.0/acumbamail/aclient.py +1038 -0
- acumbamail-0.1.0/acumbamail/client.py +1196 -0
- acumbamail-0.1.0/acumbamail/exceptions.py +28 -0
- acumbamail-0.1.0/acumbamail/models.py +517 -0
- acumbamail-0.1.0/acumbamail/utils.py +228 -0
- acumbamail-0.1.0/pyproject.toml +18 -0
acumbamail-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Daniel García (cr0hn) - cr0hn<-at->cr0hn.com
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,611 @@
|
|
|
1
|
+
Metadata-Version: 2.3
|
|
2
|
+
Name: acumbamail
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Acumamail SDK client for Python
|
|
5
|
+
License: MIT
|
|
6
|
+
Author: Daniel Garcia (cr0hn)
|
|
7
|
+
Requires-Python: >=3.11
|
|
8
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
9
|
+
Classifier: Programming Language :: Python :: 3
|
|
10
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
13
|
+
Requires-Dist: httpx (>=0.28.1,<0.29.0)
|
|
14
|
+
Description-Content-Type: text/markdown
|
|
15
|
+
|
|
16
|
+
# Acumbamail SDK for Python
|
|
17
|
+
|
|
18
|
+
[](https://www.python.org/downloads/)
|
|
19
|
+
[](https://opensource.org/licenses/MIT)
|
|
20
|
+
|
|
21
|
+
A modern, feature-rich Python SDK for the [Acumbamail](https://acumbamail.com/?refered=243965) API. This library provides both synchronous and asynchronous clients for managing email campaigns, mailing lists, subscribers, and analytics.
|
|
22
|
+
|
|
23
|
+
# Table of Contents
|
|
24
|
+
|
|
25
|
+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
|
26
|
+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
|
27
|
+
|
|
28
|
+
- [Referral program](#referral-program)
|
|
29
|
+
- [Features](#features)
|
|
30
|
+
- [Quick Start](#quick-start)
|
|
31
|
+
- [Installation](#installation)
|
|
32
|
+
- [Basic Usage](#basic-usage)
|
|
33
|
+
- [Postman Collection](#postman-collection)
|
|
34
|
+
- [Using the Postman Collection](#using-the-postman-collection)
|
|
35
|
+
- [Configuration](#configuration)
|
|
36
|
+
- [Client Initialization](#client-initialization)
|
|
37
|
+
- [Basic Usage](#basic-usage-1)
|
|
38
|
+
- [Mailing Lists](#mailing-lists)
|
|
39
|
+
- [Subscribers](#subscribers)
|
|
40
|
+
- [Campaigns](#campaigns)
|
|
41
|
+
- [Single Emails](#single-emails)
|
|
42
|
+
- [Asynchronous Usage](#asynchronous-usage)
|
|
43
|
+
- [Analytics and Statistics](#analytics-and-statistics)
|
|
44
|
+
- [Campaign Analytics](#campaign-analytics)
|
|
45
|
+
- [Click Analysis](#click-analysis)
|
|
46
|
+
- [Opener Analysis](#opener-analysis)
|
|
47
|
+
- [Browser and OS Statistics](#browser-and-os-statistics)
|
|
48
|
+
- [Advanced Examples](#advanced-examples)
|
|
49
|
+
- [Bulk Subscriber Management](#bulk-subscriber-management)
|
|
50
|
+
- [Campaign Performance Monitoring](#campaign-performance-monitoring)
|
|
51
|
+
- [Automated Newsletter System](#automated-newsletter-system)
|
|
52
|
+
- [A/B Testing Framework](#ab-testing-framework)
|
|
53
|
+
- [API Reference](#api-reference)
|
|
54
|
+
- [Client Classes](#client-classes)
|
|
55
|
+
- [AcumbamailClient (Synchronous)](#acumbamailclient-synchronous)
|
|
56
|
+
- [AsyncAcumbamailClient (Asynchronous)](#asyncacumbamailclient-asynchronous)
|
|
57
|
+
- [Core Methods](#core-methods)
|
|
58
|
+
- [List Management](#list-management)
|
|
59
|
+
- [Subscriber Management](#subscriber-management)
|
|
60
|
+
- [Campaign Management](#campaign-management)
|
|
61
|
+
- [Analytics](#analytics)
|
|
62
|
+
- [Error Handling](#error-handling)
|
|
63
|
+
- [Examples](#examples)
|
|
64
|
+
- [Contributing](#contributing)
|
|
65
|
+
- [License](#license)
|
|
66
|
+
- [Support](#support)
|
|
67
|
+
|
|
68
|
+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
|
69
|
+
|
|
70
|
+
## Referral program
|
|
71
|
+
|
|
72
|
+
If you sign up using this link, you'll get 15% off.
|
|
73
|
+
|
|
74
|
+
[https://acumbamail.com/?refered=243965](https://acumbamail.com/?refered=243965)
|
|
75
|
+
|
|
76
|
+
## Features
|
|
77
|
+
|
|
78
|
+
- **Dual Client Support**: Both synchronous (`AcumbamailClient`) and asynchronous (`AsyncAcumbamailClient`) clients
|
|
79
|
+
- **Modern HTTP Client**: Built on `httpx` for better performance and HTTP/2 support
|
|
80
|
+
- **Type Hints**: Full type annotation support for better IDE integration
|
|
81
|
+
- **Comprehensive API Coverage**: All major Acumbamail API endpoints supported
|
|
82
|
+
- **Error Handling**: Robust exception handling with specific error types
|
|
83
|
+
- **Rate Limiting**: Built-in rate limit handling with exponential backoff
|
|
84
|
+
- **Data Models**: Structured data models for all API responses
|
|
85
|
+
- **Documentation**: Extensive docstrings and examples
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
## Quick Start
|
|
89
|
+
|
|
90
|
+
### Installation
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
pip install acumbamail
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### Basic Usage
|
|
97
|
+
|
|
98
|
+
```python
|
|
99
|
+
from acumbamail import AcumbamailClient
|
|
100
|
+
|
|
101
|
+
# Initialize the client
|
|
102
|
+
client = AcumbamailClient(
|
|
103
|
+
auth_token='your-api-token',
|
|
104
|
+
default_sender_name='Your Company',
|
|
105
|
+
default_sender_email='noreply@yourcompany.com'
|
|
106
|
+
)
|
|
107
|
+
|
|
108
|
+
# Create a mailing list
|
|
109
|
+
mailing_list = client.create_list(
|
|
110
|
+
name="Newsletter Subscribers",
|
|
111
|
+
description="Our monthly newsletter list"
|
|
112
|
+
)
|
|
113
|
+
|
|
114
|
+
# Add a subscriber
|
|
115
|
+
subscriber = client.add_subscriber(
|
|
116
|
+
email="user@example.com",
|
|
117
|
+
list_id=mailing_list.id,
|
|
118
|
+
fields={"name": "John Doe", "company": "Acme Corp"}
|
|
119
|
+
)
|
|
120
|
+
|
|
121
|
+
# Create and send a campaign
|
|
122
|
+
campaign = client.create_campaign(
|
|
123
|
+
name="Welcome Campaign",
|
|
124
|
+
subject="Welcome to our newsletter!",
|
|
125
|
+
content="<h1>Welcome!</h1><p>Thank you for subscribing.</p>",
|
|
126
|
+
list_ids=[mailing_list.id]
|
|
127
|
+
)
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
## Postman Collection
|
|
132
|
+
|
|
133
|
+
For testing and exploring the API, you can use the included Postman collection:
|
|
134
|
+
|
|
135
|
+
- **Acumbamail.postman_collection.json**: Complete collection with all API endpoints pre-configured
|
|
136
|
+
|
|
137
|
+
The collection includes:
|
|
138
|
+
- **Campaigns**: All campaign-related endpoints (getCampaignBasicInformation, getCampaignClicks, getCampaignLinks, etc.)
|
|
139
|
+
- **Subscribers**: All subscriber and list management endpoints (getLists, getSubscribers, getListStats, etc.)
|
|
140
|
+
|
|
141
|
+
### Using the Postman Collection
|
|
142
|
+
|
|
143
|
+
1. Import the `Acumbamail.postman_collection.json` file into Postman
|
|
144
|
+
2. Set up your environment variables:
|
|
145
|
+
- `token`: Your Acumbamail API token
|
|
146
|
+
- `basepath`: `https://acumbamail.com/api/1/`
|
|
147
|
+
- `campaign_id`: Your campaign ID (for campaign-specific endpoints)
|
|
148
|
+
- `list_id`: Your list ID (for list-specific endpoints)
|
|
149
|
+
3. Start testing the API endpoints directly from Postman
|
|
150
|
+
|
|
151
|
+
## Configuration
|
|
152
|
+
|
|
153
|
+
### Client Initialization
|
|
154
|
+
|
|
155
|
+
```python
|
|
156
|
+
from acumbamail import AcumbamailClient
|
|
157
|
+
|
|
158
|
+
# Basic configuration
|
|
159
|
+
client = AcumbamailClient(auth_token='your-token')
|
|
160
|
+
|
|
161
|
+
# Full configuration (optional)
|
|
162
|
+
client = AcumbamailClient(
|
|
163
|
+
auth_token='your-token',
|
|
164
|
+
default_sender_name='Your Company',
|
|
165
|
+
default_sender_email='noreply@yourcompany.com',
|
|
166
|
+
sender_company='Your Company Inc.',
|
|
167
|
+
sender_country='US'
|
|
168
|
+
)
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
## Basic Usage
|
|
172
|
+
|
|
173
|
+
### Mailing Lists
|
|
174
|
+
|
|
175
|
+
```python
|
|
176
|
+
# Get all lists
|
|
177
|
+
lists = client.get_lists()
|
|
178
|
+
for mail_list in lists:
|
|
179
|
+
print(f"{mail_list.name}: {mail_list.subscribers_count} subscribers")
|
|
180
|
+
|
|
181
|
+
# Create a new list
|
|
182
|
+
new_list = client.create_list(
|
|
183
|
+
name="Product Updates",
|
|
184
|
+
description="List for product announcements"
|
|
185
|
+
)
|
|
186
|
+
|
|
187
|
+
# Get list statistics
|
|
188
|
+
stats = client.get_list_stats(new_list.id)
|
|
189
|
+
print(f"Total subscribers: {stats['total_subscribers']}")
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### Subscribers
|
|
193
|
+
|
|
194
|
+
```python
|
|
195
|
+
# Add a subscriber
|
|
196
|
+
subscriber = client.add_subscriber(
|
|
197
|
+
email="user@example.com",
|
|
198
|
+
list_id=mailing_list.id,
|
|
199
|
+
fields={
|
|
200
|
+
"name": "John Doe",
|
|
201
|
+
"company": "Acme Corp",
|
|
202
|
+
"preferences": "weekly"
|
|
203
|
+
}
|
|
204
|
+
)
|
|
205
|
+
|
|
206
|
+
# Get all subscribers
|
|
207
|
+
subscribers = client.get_subscribers(mailing_list.id)
|
|
208
|
+
for subscriber in subscribers:
|
|
209
|
+
print(f"Email: {subscriber.email}")
|
|
210
|
+
print(f"Fields: {subscriber.fields}")
|
|
211
|
+
|
|
212
|
+
# Remove a subscriber
|
|
213
|
+
client.delete_subscriber("user@example.com", mailing_list.id)
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
### Campaigns
|
|
217
|
+
|
|
218
|
+
```python
|
|
219
|
+
# Create a campaign
|
|
220
|
+
campaign = client.create_campaign(
|
|
221
|
+
name="Monthly Newsletter",
|
|
222
|
+
subject="This month's updates",
|
|
223
|
+
content="""
|
|
224
|
+
<h1>Monthly Newsletter</h1>
|
|
225
|
+
<p>Here are the latest updates:</p>
|
|
226
|
+
<ul>
|
|
227
|
+
<li>New feature released</li>
|
|
228
|
+
<li>Upcoming events</li>
|
|
229
|
+
<li>Special offers</li>
|
|
230
|
+
</ul>
|
|
231
|
+
""",
|
|
232
|
+
list_ids=[mailing_list.id],
|
|
233
|
+
pre_header="Stay updated with our latest news"
|
|
234
|
+
)
|
|
235
|
+
|
|
236
|
+
# Schedule a campaign
|
|
237
|
+
from datetime import datetime, timedelta
|
|
238
|
+
scheduled_time = datetime.now() + timedelta(days=1)
|
|
239
|
+
scheduled_campaign = client.create_campaign(
|
|
240
|
+
name="Scheduled Campaign",
|
|
241
|
+
subject="Scheduled message",
|
|
242
|
+
content="<p>This will be sent tomorrow</p>",
|
|
243
|
+
list_ids=[mailing_list.id],
|
|
244
|
+
scheduled_at=scheduled_time
|
|
245
|
+
)
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
### Single Emails
|
|
249
|
+
|
|
250
|
+
```python
|
|
251
|
+
# Send a single email
|
|
252
|
+
email_id = client.send_single_email(
|
|
253
|
+
to_email="customer@example.com",
|
|
254
|
+
subject="Order Confirmation",
|
|
255
|
+
content="<h1>Thank you for your order!</h1><p>Order #12345</p>",
|
|
256
|
+
category="order_confirmation"
|
|
257
|
+
)
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
## Asynchronous Usage
|
|
261
|
+
|
|
262
|
+
```python
|
|
263
|
+
import asyncio
|
|
264
|
+
from acumbamail import AsyncAcumbamailClient
|
|
265
|
+
|
|
266
|
+
async def main():
|
|
267
|
+
# Using context manager (recommended)
|
|
268
|
+
async with AsyncAcumbamailClient(
|
|
269
|
+
auth_token='your-token',
|
|
270
|
+
default_sender_name='Your Company',
|
|
271
|
+
default_sender_email='noreply@yourcompany.com'
|
|
272
|
+
) as client:
|
|
273
|
+
|
|
274
|
+
# Get lists
|
|
275
|
+
lists = await client.get_lists()
|
|
276
|
+
|
|
277
|
+
# Create campaign
|
|
278
|
+
campaign = await client.create_campaign(
|
|
279
|
+
name="Async Campaign",
|
|
280
|
+
subject="Hello from async!",
|
|
281
|
+
content="<p>This was sent asynchronously</p>",
|
|
282
|
+
list_ids=[lists[0].id]
|
|
283
|
+
)
|
|
284
|
+
|
|
285
|
+
# Get campaign statistics
|
|
286
|
+
stats = await client.get_campaign_total_information(campaign.id)
|
|
287
|
+
print(f"Opened: {stats.opened}")
|
|
288
|
+
|
|
289
|
+
# Run the async function
|
|
290
|
+
asyncio.run(main())
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
## Analytics and Statistics
|
|
294
|
+
|
|
295
|
+
### Campaign Analytics
|
|
296
|
+
|
|
297
|
+
```python
|
|
298
|
+
# Get comprehensive campaign statistics
|
|
299
|
+
stats = client.get_campaign_total_information(campaign_id)
|
|
300
|
+
|
|
301
|
+
print(f"Total delivered: {stats.total_delivered}")
|
|
302
|
+
print(f"Opened: {stats.opened}")
|
|
303
|
+
print(f"Unique clicks: {stats.unique_clicks}")
|
|
304
|
+
print(f"Hard bounces: {stats.hard_bounces}")
|
|
305
|
+
print(f"Unsubscribes: {stats.unsubscribes}")
|
|
306
|
+
|
|
307
|
+
# Calculate rates
|
|
308
|
+
if stats.total_delivered > 0:
|
|
309
|
+
open_rate = (stats.opened / stats.total_delivered) * 100
|
|
310
|
+
click_rate = (stats.unique_clicks / stats.total_delivered) * 100
|
|
311
|
+
print(f"Open rate: {open_rate:.2f}%")
|
|
312
|
+
print(f"Click rate: {click_rate:.2f}%")
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
### Click Analysis
|
|
316
|
+
|
|
317
|
+
```python
|
|
318
|
+
# Get detailed click statistics
|
|
319
|
+
clicks = client.get_campaign_clicks(campaign_id)
|
|
320
|
+
|
|
321
|
+
for click in clicks:
|
|
322
|
+
print(f"URL: {click.url}")
|
|
323
|
+
print(f"Total clicks: {click.clicks}")
|
|
324
|
+
print(f"Unique clicks: {click.unique_clicks}")
|
|
325
|
+
print(f"Click rate: {click.click_rate:.2%}")
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
### Opener Analysis
|
|
329
|
+
|
|
330
|
+
```python
|
|
331
|
+
# Get information about who opened the campaign
|
|
332
|
+
openers = client.get_campaign_openers(campaign_id)
|
|
333
|
+
|
|
334
|
+
for opener in openers:
|
|
335
|
+
print(f"Email: {opener.email}")
|
|
336
|
+
print(f"Opened at: {opener.opened_at}")
|
|
337
|
+
print(f"Country: {opener.country}")
|
|
338
|
+
print(f"Browser: {opener.browser}")
|
|
339
|
+
print(f"OS: {opener.os}")
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
### Browser and OS Statistics
|
|
343
|
+
|
|
344
|
+
```python
|
|
345
|
+
# Get statistics by browser
|
|
346
|
+
browser_stats = client.get_campaign_openers_by_browser(campaign_id)
|
|
347
|
+
for browser, count in browser_stats.items():
|
|
348
|
+
print(f"{browser}: {count} opens")
|
|
349
|
+
|
|
350
|
+
# Get statistics by operating system
|
|
351
|
+
os_stats = client.get_campaign_openers_by_os(campaign_id)
|
|
352
|
+
for os_name, count in os_stats.items():
|
|
353
|
+
print(f"{os_name}: {count} opens")
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
## Advanced Examples
|
|
357
|
+
|
|
358
|
+
### Bulk Subscriber Management
|
|
359
|
+
|
|
360
|
+
```python
|
|
361
|
+
# Add multiple subscribers efficiently
|
|
362
|
+
subscribers_data = [
|
|
363
|
+
("user1@example.com", {"name": "User One", "company": "Corp A"}),
|
|
364
|
+
("user2@example.com", {"name": "User Two", "company": "Corp B"}),
|
|
365
|
+
("user3@example.com", {"name": "User Three", "company": "Corp C"})
|
|
366
|
+
]
|
|
367
|
+
|
|
368
|
+
for email, fields in subscribers_data:
|
|
369
|
+
try:
|
|
370
|
+
subscriber = client.add_subscriber(
|
|
371
|
+
email=email,
|
|
372
|
+
list_id=mailing_list.id,
|
|
373
|
+
fields=fields
|
|
374
|
+
)
|
|
375
|
+
print(f"Added: {subscriber.email}")
|
|
376
|
+
except Exception as e:
|
|
377
|
+
print(f"Failed to add {email}: {e}")
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
### Campaign Performance Monitoring
|
|
381
|
+
|
|
382
|
+
```python
|
|
383
|
+
def monitor_campaign_performance(campaign_id):
|
|
384
|
+
"""Monitor campaign performance and alert on issues."""
|
|
385
|
+
stats = client.get_campaign_total_information(campaign_id)
|
|
386
|
+
|
|
387
|
+
# Calculate key metrics
|
|
388
|
+
if stats.total_delivered > 0:
|
|
389
|
+
open_rate = (stats.opened / stats.total_delivered) * 100
|
|
390
|
+
click_rate = (stats.unique_clicks / stats.total_delivered) * 100
|
|
391
|
+
bounce_rate = (stats.hard_bounces / stats.total_delivered) * 100
|
|
392
|
+
|
|
393
|
+
print(f"Campaign Performance:")
|
|
394
|
+
print(f" Open rate: {open_rate:.2f}%")
|
|
395
|
+
print(f" Click rate: {click_rate:.2f}%")
|
|
396
|
+
print(f" Bounce rate: {bounce_rate:.2f}%")
|
|
397
|
+
|
|
398
|
+
# Alert on poor performance
|
|
399
|
+
if open_rate < 15:
|
|
400
|
+
print("⚠️ Warning: Low open rate detected")
|
|
401
|
+
if bounce_rate > 5:
|
|
402
|
+
print("⚠️ Warning: High bounce rate detected")
|
|
403
|
+
if stats.complaints > 0:
|
|
404
|
+
print("⚠️ Warning: Complaints detected")
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
### Automated Newsletter System
|
|
408
|
+
|
|
409
|
+
```python
|
|
410
|
+
from datetime import datetime, timedelta
|
|
411
|
+
|
|
412
|
+
def send_weekly_newsletter():
|
|
413
|
+
"""Send weekly newsletter to all active subscribers."""
|
|
414
|
+
|
|
415
|
+
# Get the newsletter list
|
|
416
|
+
lists = client.get_lists()
|
|
417
|
+
newsletter_list = next((l for l in lists if "newsletter" in l.name.lower()), None)
|
|
418
|
+
|
|
419
|
+
if not newsletter_list:
|
|
420
|
+
print("Newsletter list not found")
|
|
421
|
+
return
|
|
422
|
+
|
|
423
|
+
# Create newsletter content
|
|
424
|
+
content = """
|
|
425
|
+
<h1>Weekly Newsletter</h1>
|
|
426
|
+
<p>Here's what happened this week:</p>
|
|
427
|
+
<ul>
|
|
428
|
+
<li>New product features</li>
|
|
429
|
+
<li>Upcoming events</li>
|
|
430
|
+
<li>Community highlights</li>
|
|
431
|
+
</ul>
|
|
432
|
+
<p>Stay tuned for more updates!</p>
|
|
433
|
+
"""
|
|
434
|
+
|
|
435
|
+
# Create and send campaign
|
|
436
|
+
campaign = client.create_campaign(
|
|
437
|
+
name=f"Weekly Newsletter - {datetime.now().strftime('%Y-%m-%d')}",
|
|
438
|
+
subject="Your weekly update is here!",
|
|
439
|
+
content=content,
|
|
440
|
+
list_ids=[newsletter_list.id],
|
|
441
|
+
pre_header="Your weekly dose of updates and insights"
|
|
442
|
+
)
|
|
443
|
+
|
|
444
|
+
print(f"Newsletter sent! Campaign ID: {campaign.id}")
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
### A/B Testing Framework
|
|
448
|
+
|
|
449
|
+
```python
|
|
450
|
+
def run_ab_test(subject_a, subject_b, content_a, content_b, list_id):
|
|
451
|
+
"""Run A/B test with two different subject lines and content."""
|
|
452
|
+
|
|
453
|
+
# Create two campaigns
|
|
454
|
+
campaign_a = client.create_campaign(
|
|
455
|
+
name="A/B Test - Version A",
|
|
456
|
+
subject=subject_a,
|
|
457
|
+
content=content_a,
|
|
458
|
+
list_ids=[list_id]
|
|
459
|
+
)
|
|
460
|
+
|
|
461
|
+
campaign_b = client.create_campaign(
|
|
462
|
+
name="A/B Test - Version B",
|
|
463
|
+
subject=subject_b,
|
|
464
|
+
content=content_b,
|
|
465
|
+
list_ids=[list_id]
|
|
466
|
+
)
|
|
467
|
+
|
|
468
|
+
print(f"Created A/B test campaigns:")
|
|
469
|
+
print(f" Version A: {campaign_a.id}")
|
|
470
|
+
print(f" Version B: {campaign_b.id}")
|
|
471
|
+
|
|
472
|
+
return campaign_a.id, campaign_b.id
|
|
473
|
+
|
|
474
|
+
def analyze_ab_test(campaign_a_id, campaign_b_id):
|
|
475
|
+
"""Analyze A/B test results."""
|
|
476
|
+
|
|
477
|
+
stats_a = client.get_campaign_total_information(campaign_a_id)
|
|
478
|
+
stats_b = client.get_campaign_total_information(campaign_b_id)
|
|
479
|
+
|
|
480
|
+
# Calculate performance metrics
|
|
481
|
+
open_rate_a = (stats_a.opened / stats_a.total_delivered) * 100 if stats_a.total_delivered > 0 else 0
|
|
482
|
+
open_rate_b = (stats_b.opened / stats_b.total_delivered) * 100 if stats_b.total_delivered > 0 else 0
|
|
483
|
+
|
|
484
|
+
click_rate_a = (stats_a.unique_clicks / stats_a.total_delivered) * 100 if stats_a.total_delivered > 0 else 0
|
|
485
|
+
click_rate_b = (stats_b.unique_clicks / stats_b.total_delivered) * 100 if stats_b.total_delivered > 0 else 0
|
|
486
|
+
|
|
487
|
+
print("A/B Test Results:")
|
|
488
|
+
print(f"Version A - Open rate: {open_rate_a:.2f}%, Click rate: {click_rate_a:.2f}%")
|
|
489
|
+
print(f"Version B - Open rate: {open_rate_b:.2f}%, Click rate: {click_rate_b:.2f}%")
|
|
490
|
+
|
|
491
|
+
# Determine winner
|
|
492
|
+
if open_rate_b > open_rate_a:
|
|
493
|
+
print("🎉 Version B wins for open rate!")
|
|
494
|
+
elif open_rate_a > open_rate_b:
|
|
495
|
+
print("🎉 Version A wins for open rate!")
|
|
496
|
+
else:
|
|
497
|
+
print("🤝 Tie for open rate")
|
|
498
|
+
```
|
|
499
|
+
|
|
500
|
+
## API Reference
|
|
501
|
+
|
|
502
|
+
### Client Classes
|
|
503
|
+
|
|
504
|
+
#### AcumbamailClient (Synchronous)
|
|
505
|
+
|
|
506
|
+
```python
|
|
507
|
+
class AcumbamailClient:
|
|
508
|
+
def __init__(
|
|
509
|
+
self,
|
|
510
|
+
auth_token: str,
|
|
511
|
+
default_sender_name: str = None,
|
|
512
|
+
default_sender_email: str = None,
|
|
513
|
+
*,
|
|
514
|
+
sender_company: str = None,
|
|
515
|
+
sender_country: str = None
|
|
516
|
+
)
|
|
517
|
+
```
|
|
518
|
+
|
|
519
|
+
#### AsyncAcumbamailClient (Asynchronous)
|
|
520
|
+
|
|
521
|
+
```python
|
|
522
|
+
class AsyncAcumbamailClient:
|
|
523
|
+
def __init__(
|
|
524
|
+
self,
|
|
525
|
+
auth_token: str,
|
|
526
|
+
default_sender_name: str = None,
|
|
527
|
+
default_sender_email: str = None,
|
|
528
|
+
*,
|
|
529
|
+
sender_company: str = None,
|
|
530
|
+
sender_country: str = None,
|
|
531
|
+
timeout: float = 30.0
|
|
532
|
+
)
|
|
533
|
+
```
|
|
534
|
+
|
|
535
|
+
### Core Methods
|
|
536
|
+
|
|
537
|
+
#### List Management
|
|
538
|
+
|
|
539
|
+
- `get_lists()` - Retrieve all mailing lists
|
|
540
|
+
- `create_list(name, description)` - Create a new mailing list
|
|
541
|
+
- `get_list_stats(list_id)` - Get list statistics
|
|
542
|
+
- `get_list_fields(list_id)` - Get custom fields
|
|
543
|
+
- `get_list_segments(list_id)` - Get list segments
|
|
544
|
+
|
|
545
|
+
#### Subscriber Management
|
|
546
|
+
|
|
547
|
+
- `get_subscribers(list_id)` - Get all subscribers
|
|
548
|
+
- `add_subscriber(email, list_id, fields)` - Add a subscriber
|
|
549
|
+
- `delete_subscriber(email, list_id)` - Remove a subscriber
|
|
550
|
+
|
|
551
|
+
#### Campaign Management
|
|
552
|
+
|
|
553
|
+
- `create_campaign(name, subject, content, list_ids, ...)` - Create a campaign
|
|
554
|
+
- `get_campaigns(complete_json)` - Get all campaigns
|
|
555
|
+
- `send_single_email(to_email, subject, content, ...)` - Send single email
|
|
556
|
+
|
|
557
|
+
#### Analytics
|
|
558
|
+
|
|
559
|
+
- `get_campaign_total_information(campaign_id)` - Get comprehensive stats
|
|
560
|
+
- `get_campaign_clicks(campaign_id)` - Get click statistics
|
|
561
|
+
- `get_campaign_openers(campaign_id)` - Get opener information
|
|
562
|
+
- `get_campaign_soft_bounces(campaign_id)` - Get bounce information
|
|
563
|
+
|
|
564
|
+
## Error Handling
|
|
565
|
+
|
|
566
|
+
The SDK provides specific exception types for different error scenarios:
|
|
567
|
+
|
|
568
|
+
```python
|
|
569
|
+
from acumbamail import (
|
|
570
|
+
AcumbamailError,
|
|
571
|
+
AcumbamailRateLimitError,
|
|
572
|
+
AcumbamailAPIError,
|
|
573
|
+
AcumbamailValidationError
|
|
574
|
+
)
|
|
575
|
+
|
|
576
|
+
try:
|
|
577
|
+
campaign = client.create_campaign(
|
|
578
|
+
name="Test Campaign",
|
|
579
|
+
subject="Hello",
|
|
580
|
+
content="<p>Test</p>",
|
|
581
|
+
list_ids=[123]
|
|
582
|
+
)
|
|
583
|
+
except AcumbamailValidationError as e:
|
|
584
|
+
print(f"Validation error: {e}")
|
|
585
|
+
except AcumbamailRateLimitError as e:
|
|
586
|
+
print(f"Rate limit exceeded: {e}")
|
|
587
|
+
except AcumbamailAPIError as e:
|
|
588
|
+
print(f"API error: {e}")
|
|
589
|
+
except AcumbamailError as e:
|
|
590
|
+
print(f"General error: {e}")
|
|
591
|
+
```
|
|
592
|
+
|
|
593
|
+
## Examples
|
|
594
|
+
|
|
595
|
+
You can find examples in the [examples](examples) directory.
|
|
596
|
+
|
|
597
|
+
## Contributing
|
|
598
|
+
|
|
599
|
+
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
|
|
600
|
+
|
|
601
|
+
## License
|
|
602
|
+
|
|
603
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
604
|
+
|
|
605
|
+
## Support
|
|
606
|
+
|
|
607
|
+
I don't offer support for this project apart from the free time I can dedicate to it. If you find a bug, please report it in the [GitHub Issues](https://github.com/cr0hn/py-acumbamail/issues) section.
|
|
608
|
+
|
|
609
|
+
[GitHub Issues](https://github.com/cr0hn/py-acumbamail/issues)
|
|
610
|
+
|
|
611
|
+
> [!NOTE] If you need commercial support for this project, please contact me at [cr0hn<-at->cr0hn.com](mailto:cr0hn<-at->cr0hn.com).
|