def create(self, title, field_type='TEXT'):
"""Create new custom field in account.
https://developers.mailerlite.com/v2/reference#create-field
Parameters
----------
title : str
Title of field
field_type: str
Type of field. Available values: TEXT , NUMBER, DATE
(default: TEXT)
Returns
-------
field : :class:Field
field object updated
"""
if field_type.upper() not in ['TEXT', 'NUMBER', 'DATE']:
raise ValueError('Incorrect field_type. Available values'
' are: TEXT , NUMBER, DATE')
url = client.build_url('fields')
data = {'title': title, 'type': field_type.upper()}
return client.post(url, body=data, headers=self.headers)
def cancel(self, campaign_id, as_json=False):
"""Cancel a campaign which is in outbox.
https://developers.mailerlite.com/reference#campaign-actions-and-triggers
Parameters
----------
campaign_id : int
campaign id
as_json : bool
return result as json format
Returns
-------
content : dict
The JSON output from the API
"""
# TODO: Check if campaign is in Outbox otherwise raise an issue
url = client.build_url('campaigns', campaign_id, "actions/cancel")
code, res_json = client.post(url, headers=self.headers)
# TODO: Check new attribute to campaign object.
# if as_json or not res_json or code != 200:
# return res_json
# res_json['opened'] = Stats(**res_json.pop('opened'))
# res_json['clicked'] = Stats(**res_json.pop('clicked'))
# return Campaign(**res_json)
return code, res_json
def create(self, name, as_json=False):
"""Create new group.
https://developers.mailerlite.com/v2/reference#create-group
Parameters
----------
name : str
group name
as_json : bool
return result as json format
Returns
-------
group: :class:Group
group object
"""
url = client.build_url('groups')
data = {'name': name}
_, res_json = client.post(url, body=data, headers=self.headers)
if as_json or not res_json:
return res_json
return Group(**res_json)
def batch(self, batch_requests):
"""Execute a list of command. Dedicated for experts.
https://developers.mailerlite.com/v2/reference#batch-api-requests
Parameters
----------
batch_requests : list of dict
all you command. E.g:
batch_requests = {"requests": [{"method":"GET",
"path": "/api/v2/groups"
},
{"method":"POST",
"path": "/api/v2/groups",
"body": {"name": "New group"}
}
]
}
Returns
-------
results : list
list of all desired object
Notes
-----
* There is a limit of maximum 50 requests per single batch.
* The order of response objects are the same as sent requests.
* requests parameter should not be empty
"""
url = client.build_url('batch')
return client.post(url, body=batch_requests, headers=self.headers)
def add_subscribers(self,
group_id,
subscribers_data,
resubscribe=False,
autoresponders=False,
as_json=False):
"""Add one or many new subscribers to specified group at once.
https://developers.mailerlite.com/v2/reference#add-single-subscriber
https://developers.mailerlite.com/v2/reference#add-many-subscribers
Parameters
----------
group_id : int
group id
subscribers_data : dict, list of dict
subscribers element that contains email and name
resubscribe : bool
reactivate subscriber if value is true (default False)
autoresponders : bool
autoresponders will be sent if value is true (default False)
as_json : bool
return result as json format
Returns
-------
group: :class:Group
group object
"""
url = client.build_url('groups', group_id, 'subscribers', 'import')
body = {'resubscribe': resubscribe, 'autoresponders': autoresponders}
if isinstance(subscribers_data, dict):
body['subscribers'] = [
subscribers_data,
]
elif isinstance(subscribers_data, list):
body['subscribers'] = subscribers_data
else:
raise ValueError('subscribers_data should be a dict or a list of'
' dict that contains the following keys: email,'
' name')
errors = [
d for d in body['subscribers']
if not {'email', 'name'}.issubset(d.keys())
]
if errors:
raise ValueError('All subscribers_data should contain the'
' following keys: email, name')
_, res_json = client.post(url, body=body, headers=self.headers)
if as_json or not res_json:
return res_json
return [Subscriber(**subs) for subs in res_json['imported']]
def create(self, data, as_json=False):
"""Add new single subscriber.
https://developers.mailerlite.com/v2/reference#create-a-subscriber
Parameters
----------
data : dict
subscriber object. only the email is required.
you can use the following example:
data = {'name' : 'John',
'email' : '*****@*****.**',
'fields' : {'company': 'MailerLite'}
}
as_json : bool
return result as json format
Returns
-------
subscriber: :class:Subscriber
a single subscriber
"""
if not isinstance(data, dict):
raise ValueError('In data should be a dictionary.')
required_keys = [
'email',
]
optional_keys = [
'name', 'fields', 'resubscribe', 'type', 'signup_ip',
'signup_timestamp', 'confirmation_ip', 'confirmation_timestamp'
]
available_keys = required_keys + optional_keys
errors = [rk for rk in required_keys if rk not in data.keys()]
if errors:
raise ValueError("The following keys are missing and they"
" are required : {}".format(errors))
unknown_keys = [
d for d in data.keys() if d not in available_keys
if d not in ['groups', 'segments']
]
if unknown_keys:
raise ValueError(
"The following keys are unknown: {}".format(unknown_keys))
url = client.build_url('subscribers')
res_code, res_json = client.post(url, body=data, headers=self.headers)
if as_json or not res_json:
return res_json
return Subscriber(**res_json)
def add_single_subscriber(self,
group_id,
subscribers_data: dict,
resubscribe=False,
autoresponders=False,
as_json=False):
"""Add single new subscriber to specified group.
https://developers.mailerlite.com/v2/reference#add-single-subscriber
Parameters
----------
group_id : int
group id
subscribers_data : dict,
subscribers data
resubscribe : bool
reactivate subscriber if value is true (default False)
autoresponders : bool
autoresponders will be sent if value is true (default False)
as_json : bool
return result as json format
Returns
-------
subscriber: :class:Subscriber
subscriber object
"""
url = client.build_url('groups', group_id, 'subscribers')
body = {
'resubscribe': resubscribe,
'autoresponders': autoresponders,
**subscribers_data
}
if not {'email', 'name'}.issubset(subscribers_data.keys()):
raise ValueError('Subscribers_data should contain the'
' following keys: email, name')
_, res_json = client.post(url, body=body, headers=self.headers)
if as_json or not res_json:
return res_json
return Subscriber(**res_json)
def send(self, campaign_id):
"""Send out a campaign.
https://developers.mailerlite.com/reference#campaign-actions-and-triggers
Parameters
----------
campaign_id : int
campaign id
Returns
-------
content : dict
The JSON output from the API
"""
# TODO: Check if campaign is in Draft otherwise raise an issue
# Add parameters like followup / send later / etc...
url = client.build_url('campaigns', campaign_id, "actions/send")
return client.post(url, headers=self.headers)
def set_double_optin(self, enable):
"""Enable/disabled double opt-in for API and integrations.
https://developers.mailerlite.com/v2/reference#change-double-optin-status
Parameters
----------
enable : bool
status
Returns
-------
status : dict
action result
"""
url = client.build_url('settings', 'double_optin')
body = {'enable': enable}
res_code, res_json = client.post(url, body=body, headers=self.headers)
return res_json
def create(self, url, event):
"""Create a webhook.
https://developers.mailerlite.com/v2/reference#create-a-webhook
Parameters
----------
url : str
Your URL where callbacks are sent
event : str
Subscribed event
Returns
-------
field : :class:Field
field object updated
"""
url = client.build_url('webhooks')
body = {"url": url, 'event': event}
_, res_json = client.post(url, body=body, headers=self.headers)
return res_json
def create(self, data):
"""Create campaign where you will use your custom HTML template.
https://developers.mailerlite.com/v2/reference#campaigns
Parameters
----------
data : dict
campaign object. For a regular campaign, you can use the
following example:
data = {"subject": "Regular campaign subject",
"name": "Regular campaign name",
"groups": [2984475, 3237221],
"type": "regular"}
For a/b campaign type, you need more fields, Here an example:
data = {"groups": [2984475, 3237221],
"type": "ab",
"ab_settings": {"send_type": "subject",
"values": ["Email subject A",
"Email subject B"],
"ab_win_type": "opens",
"winner_after": 1,
"winner_after_type": "h",
"split_part": "10"
}}
Returns
-------
response : int
response value
content : dict
The JSON output from the API
"""
if not isinstance(data, dict):
raise ValueError('In data should be a dictionary.')
required_keys = [
'type',
]
optional_keys = [
'subject', 'name', 'from', 'from_name', 'language', 'ab_settings'
]
ab_settings_keys = [
'values', 'send_type', 'ab_win_type', 'winner_after',
'winner_after_type', 'split_part'
]
available_keys = required_keys + optional_keys
errors = [rk for rk in required_keys if rk not in data.keys()]
if errors:
raise ValueError("The following keys are missing and they"
" are required : {}".format(errors))
if ('groups' not in data.keys()) and ('segments' not in data.keys()):
raise ValueError("'groups' key is required if 'segments' key"
" are not specified. If specified, 'groups'"
" are ignored")
unknown_keys = [
d for d in data.keys() if d not in available_keys
if d not in ['groups', 'segments']
]
if unknown_keys:
raise ValueError(
"The following keys are unknown: {}".format(unknown_keys))
if 'ab_settings' in data.keys():
errors = [
rk for rk in ab_settings_keys
if rk not in data['ab_settings'].keys()
]
if errors:
raise ValueError("The following keys are missing in the"
" ab_settings and they are required : "
"{}".format(errors))
url = client.build_url('campaigns')
return client.post(url, body=data, headers=self.headers)