FreshMail Python Client
Project description
Python API Client for Freshmail API V3
This API V3 client covers only sending transactional emails by FreshMail Application. Additional features will be added in future.
Requirements
- Python 3.5+
Installation
pip install freshmail-api
Usage
Send transactional email
from freshmail.messaging.email.mailbag import MailBag
from freshmail.sender.sender import FreshmailSender
from freshmail.transport.api.email import EmailApiTransport
token = "MY_APP_TOKEN"
transport = EmailApiTransport(bearer_token = token)
sender = FreshmailSender(transport=transport)
message = MailBag()
message.from_ = {
"email": "from@address.com",
"name": "Office"
}
message.subject = "That's my awesome first mail!"
message.contents = {
"html": "<html><body><strong>Look!</strong> its working!</body></html>"
}
message.tos = [
{
"email": "recipient email address"
}
]
response = sender.send(message=message)
Handle with response object
if response.is_success():
response_data = response.get_data()
Handle with raw Requests Response
response.get_requests_response();
Send personalized email
from freshmail.messaging.email.mailbag import MailBag
from freshmail.sender.sender import FreshmailSender
from freshmail.transport.api.email import EmailApiTransport
token = "MY_APP_TOKEN"
transport = EmailApiTransport(bearer_token = token)
sender = FreshmailSender(transport=transport)
message = MailBag()
message.from_ = {
"email": "from@address.com",
"name": "Office"
}
message.subject = "Hello $$first_name$$! I've got promotion code for You!"
message.contents = {
"html": "<html><body>Your code is <strong>$$code$$</strong></body></html>"
}
message.tos = [
{
"email": "recipient email address",
"personalization": {
"first_name": "Joshua",
"code": "CODE1234"
}
}
]
response = sender.send(message=message)
Send multiply emails
You can send multiple emails by one request. It's much faster than sending one email by one request. In one request You can send up to 100 emails.
from freshmail.messaging.email.mailbag import MailBag
from freshmail.sender.sender import FreshmailSender
from freshmail.transport.api.email import EmailApiTransport
token = "MY_APP_TOKEN"
transport = EmailApiTransport(bearer_token = token)
sender = FreshmailSender(transport=transport)
message = MailBag()
message.from_ = {
"email": "from@address.com",
"name": "Office"
}
message.subject = "Hello $$first_name$$! I've got promotion code for You!"
message.contents = {
"html": "<html><body>Your code is <strong>$$code$$</strong></body></html>"
}
message.tos = [
{
"email": "recipient email address",
"personalization": {
"first_name": "Joshua",
"code": "10percentDISCOUNT"
}
},
{
"email": "second recipient email address",
"personalization": {
"first_name": "Donald",
"code": "25percentDISCOUNT"
}
},
{
"email": "third recipient email address",
"personalization": {
"first_name": "Abbie",
"code": "FREEshippingDISCOUNT"
}
}
]
response = sender.send(message=message)
Send email from template
You can use FreshMail Templates mechanism to optimize requests to API. Additionally You can modify content of Your emails in FreshMail, not modifying the code of Your application.
from freshmail.messaging.email.mailbag import MailBag
from freshmail.sender.sender import FreshmailSender
from freshmail.transport.api.email import EmailApiTransport
token = "MY_APP_TOKEN"
transport = EmailApiTransport(bearer_token = token)
sender = FreshmailSender(transport=transport)
message = MailBag()
message.from_ = {
"email": "from@address.com",
"name": "Support"
}
message.subject = "Hello, that's my email genereted by template!"
message.template_hash = "TEMPLATE_HASH"
message.tos = [
{
"email": "recipient email address"
}
]
response = sender.send(message=message)
Send email with attachments
You can sent emails with attachments. You can upload up to 10 files. Weight of all attachments in email can't exceed 10Mb.
from freshmail.messaging.email.attachment import Base64Attachment, LocalFileAttachment
from freshmail.messaging.email.mailbag import MailBag
from freshmail.sender.sender import FreshmailSender
from freshmail.transport.api.email import EmailApiTransport
from base64 import b64encode
token = "MY_APP_TOKEN"
transport = EmailApiTransport(bearer_token = token)
sender = FreshmailSender(transport=transport)
# attachment from hard drive
local_file_attachment = LocalFileAttachment(
filepath="/my/local/path/file.extension",
name="optional file name"
)
# attachment from base64
base64_attachment = Base64Attachment(
name="base64text.txt",
content=b64encode("example content".encode())
)
message = MailBag()
message.from_ = {
"email": "from@address.com",
"name": "Support"
}
message.subject = "Hello, thats mail with attachments!!"
message.contents = {
"html": "<html><body><strong>Attachments</strong> in mail</body></html>"
}
message.tos = [
{
"email": "recipient email address"
}
]
message.attachments = [
local_file_attachment,
base64_attachment
]
response = sender.send(message=message)
Error handling
API throws exceptions for errors that occurred during requests and errors occurred before sending requests.
- If request is not sent to server because of wrong API usage, an exception that extends
freshmail.exceptions.ApiUsageExceptionis thrown. This kind of exception means, for example, wrong parameters pass to some methods or passing both content and template in transactional mail, which means request won't be accepted, so API does not make any request. - If request is sent and some network issue occurred (DNS error, connection timeout, firewall blocking requests), a
freshmail.exceptions.RequestExceptionis thrown. - If request is sent, a response is received but some server error occurred (500 level http code), a
freshmail.exceptions.ServerExceptionis thrown. - If request is sent, a response is received but some client error occurred (400 level http code), a
freshmail.exceptions.ClientExceptionis thrown.
from freshmail.exceptions import ClientException
try:
response = sender.send(message=message)
except ClientException as e:
handle_exception(e)
Set logger to level DEBUG to log request data and request response.
Proxy setup
If You need to configure proxy You can use a dictionary and pass it as an argument to Transport object.
from freshmail.transport.api.email import EmailApiTransport
token = 'MY_APP_TOKEN'
proxies = {
"http": "http://10.10.10.10:8000",
"https": "http://10.10.10.10:8000"
}
transport = EmailApiTransport(bearer_token=token, proxies=proxies)
Logging and debugging
If You need to log or debug Your requests You can pass logging.Logger object.
Example logger usage
import logging
from logging.handlers import SysLogHandler
from freshmail.transport.api.email import EmailApiTransport
def setup_logger(logger, level=logging.INFO, path="stdout"):
logger.setLevel(logging.DEBUG)
if path == 'syslog':
ch = SysLogHandler(address='/dev/log')
elif path == 'stdout':
ch = logging.StreamHandler()
else:
ch = logging.StreamHandler()
ch.setLevel(level)
formatter = logging.Formatter('%(asctime)s [%(levelname)s] %(module)s:%(lineno)d %(message)s')
ch.setFormatter(formatter)
logger.addHandler(ch)
bearer_token = "MY_APP_TOKEN"
logger = logging.getLogger("freshmail_client")
setup_logger(logger, level=logging.DEBUG)
transport = EmailApiTransport(bearer_token=bearer_token, logger=logger)
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
freshmail-api-1.2.tar.gz
(8.8 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file freshmail-api-1.2.tar.gz.
File metadata
- Download URL: freshmail-api-1.2.tar.gz
- Upload date:
- Size: 8.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.4.1 importlib_metadata/4.2.0 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.0 CPython/3.7.10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
21f9a3c54287304d3a672401b070d3c630e3bfbb6d6edd2783b6711204c0ba13
|
|
| MD5 |
6cd7648f4c3aac825300fd46e5daf478
|
|
| BLAKE2b-256 |
fc514f7caa9575061c650d04794f305eb4b42bd5fab75b43a3944999be159e6b
|
File details
Details for the file freshmail_api-1.2-py3-none-any.whl.
File metadata
- Download URL: freshmail_api-1.2-py3-none-any.whl
- Upload date:
- Size: 9.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.4.1 importlib_metadata/4.2.0 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.0 CPython/3.7.10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
0355114434aced305f81dabd8096bce1961a07464e5d7cf41248e6f91dbdc579
|
|
| MD5 |
bc13af35deb71c91231cc5eab3bfc2bc
|
|
| BLAKE2b-256 |
c7120ea9374c3971c29ffc3b766cfd940b8f975174e92a433b7c9d62d1d0c621
|
