Metadata-Version: 2.1
Name: cakemail
Version: 1.9.0
Summary: Cakemail Next-gen API client
Home-page: https://github.com/cakemail/cakemail-python
License: MIT
Platform: UNKNOWN
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: six
Requires-Dist: urllib3
Requires-Dist: certifi
Requires-Dist: python-dateutil
Requires-Dist: cakemail-openapi (==1.9.1)

# Install

Install the `cakemail` package using `pip`

```shell script
pip install cakemail
```

# Usage

Create an object from the `CakemailApi` class with your Cakemail username and password.  The object will take care of
all authorization mechanisms automatically.

```python
import cakemail

api = cakemail.Api(username='your@email.com', password='somepassword')
```

Call one of the API operations (refer to the online documentation)

```python
my_account = api.account.get_self()
```

# API operations

API operations accept the OpenAPI models as well as python dictionaries.

```python
from cakemail.models import CreateSender

sender = api.sender.create(
    create_sender=CreateSender(
        name='My Sender',
        email='someone@gmail.com'
    )
)
sender = api.sender.create(
    create_sender={
        'name': 'My Sender',
        'email': 'someone@gmail.com'    
    }
)
```

# Operation Examples

## Create a Sender
```python
from cakemail.models import CreateSender, ConfirmSender

sender = api.sender.create(
    CreateSender(name='My Sender', email='someone@gmail.com')
)
```
Look for a confirmation email in your inbox; click to the link to activate the sender.

## Create a Contact List
```python
from cakemail.models import List, Sender

my_new_list = api.list.create(
    list=List(
        name='my new list',
        default_sender=Sender(id=sender.id)
    )
)
```

## Send a transactional email

```python
from cakemail.models import Email, EmailContent

# expressed as OpenAPI models
api.transactional_email.send(
    email=Email(
        email='destination@gmail.com',
        sender=sender,
        content=EmailContent(
            subject='Subject line',
            text='Email body',
            encoding='utf-8'
        )
    )
)

# expressed as a dictionary
api.transactional_email.send(
    email={
        'email': 'destination@gmail.com',
        'sender': sender,
        'content': {
            'subject': 'Subject line',
            'text': 'Email body',
            'encoding': 'utf-8' 
        }
    }
)
```

## Accessing data

The CakemailAPI always return its data under the `data` object.  For simplicity, the resource data is accessible
from the returned response directly:

```python
my_user = api.user.get_self()

print(f'id: {my_user.id}, email: {my_user.email}')

```
## Iterate through lists

Some methods return a list of resources on which you can iterate directly:

```python
campaigns = api.campaign.list()
for campaign in campaigns:
    html = api.campaign.render(campaign_id=campaign.id).html
    print(f'id: {campaign.id}, name: {campaign.name}, html: {html}')

```

## Pagination

Pagination is stored in the `pagination` property of all methods returning a list of resources:

```python
campaigns = api.campaign.list(with_count=True)

print(f"""
  page: {campaigns.pagination.page},
  per_page: {campaigns.pagination.per_page},
  count: {campaigns.pagination.count}
  """)
```

## Dictionary representation

The API methods return response objects; if you prefer to work with a python dict representation, use the `to_dict` method:

```python
campaign_dict = api.campaign.get(campaign_id=123).to_dict()

for campaign in api.campaign.list():
    print(campaign.to_dict())
```


