MailerSend Python SDK

Installation

$ python -m pip install mailersend

Requirements

Python > 3.6.1
Python pip
An API Key from mailersend.com
A MAILERSEND_API_KEY environment variable

Usage

Email

Send an email

from mailersend import emails

mailer = emails.NewEmail()

# define an empty dict to populate with mail values
mail_body = {}

mail_from = {
    "name": "Your Name",
    "email": "[email protected]",
}

recipients = [
    {
        "name": "Your Client",
        "email": "[email protected]",
    }
]

mailer.set_mail_from(mail_from, mail_body)
mailer.set_mail_to(recipients, mail_body)
mailer.set_subject("Hello!", mail_body)
mailer.set_html_content("This is the HTML content", mail_body)
mailer.set_plaintext_content("This is the text content", mail_body)

# using print() will also return status code and data
mailer.send(mail_body)

Add CC, BCC recipients

from mailersend import emails

mailer = emails.NewEmail()

# define an empty dict to populate with mail values
mail_body = {}

mail_from = {
    "name": "Your Name",
    "email": "[email protected]",
}

recipients = [
    {
        "name": "Your Client",
        "email": "[email protected]",
    }
]

cc = [
    {
        "name": "CC",
        "email": "[email protected]" 
    }
]

bcc = [
    {
        "name": "BCC",
        "email": "[email protected]"
    }
]

mailer.set_mail_from(mail_from, mail_body)
mailer.set_mail_to(recipients, mail_body)
mailer.set_subject("Hello!", mail_body)
mailer.set_html_content("This is the HTML content", mail_body)
mailer.set_plaintext_content("This is the text content", mail_body)
mailer.set_cc_recipients(cc, mail_body)
mailer.set_bcc_recipients(bcc, mail_body)

mailer.send(mail_body)

Send a template-based email

from mailersend import emails

mailer = emails.NewEmail()

# define an empty dict to populate with mail values
mail_body = {}

mail_from = {
    "name": "Your Name",
    "email": "[email protected]",
}

recipients = [
    {
        "name": "Your Client",
        "email": "[email protected]",
    }
]


variables = [
    {
        "email": "[email protected]",
        "substitutions": [
            {
                "var": "foo",
                "value": "bar"
            },
        ]
    }
]


mailer.set_mail_from(mail_from, mail_body)
mailer.set_mail_to(recipients, mail_body)
mailer.set_subject("Hello from {$company}", mail_body)
mailer.set_template("templateID", mail_body)
mailer.set_simple_personalization(variables, mail_body)

mailer.send(mail_body)

Advanced personalization

from mailersend import emails

mailer = emails.NewEmail()

# define an empty dict to populate with mail values
mail_body = {}

mail_from = {
    "name": "Your Name",
    "email": "[email protected]",
}

recipients = [
    {
        "name": "Your Client",
        "email": "[email protected]",
    }
]

personalization = [
    {
        "email": "[email protected]",
        "data": {
        "var": "value",
        "boolean": True,
        "object": {
            "key" : "object-value"
        },
        "number": 2,
        "array": [
            1,
            2,
            3
        ]
        }
    }
    ]


mailer.set_mail_from(mail_from, mail_body)
mailer.set_mail_to(recipients, mail_body)
mailer.set_subject("Hello from {$company}", mail_body)
mailer.set_html_content("This is the HTML content, {$name}", mail_body)
mailer.set_plaintext_content("This is the text content, {$name}", mail_body)
mailer.set_advanced_personalization(personalization, mail_body)

mailer.send(mail_body)

Simple personalization

from mailersend import emails

mailer = emails.NewEmail()

# define an empty dict to populate with mail values
mail_body = {}

mail_from = {
    "name": "Your Name",
    "email": "[email protected]",
}

recipients = [
    {
        "name": "Your Client",
        "email": "[email protected]",
    }
]

variables = [
    {
        "email": "[email protected]",
        "substitutions": [
            {
                "var": "foo",
                "value": "bar"
            },
        ]
    }
]


mailer.set_mail_from(mail_from, mail_body)
mailer.set_mail_to(recipients, mail_body)
mailer.set_subject("Hello from {$foo}", mail_body)
mailer.set_html_content("This is the HTML content, {$foo}", mail_body)
mailer.set_plaintext_content("This is the text content, {$foo}", mail_body)
mailer.set_simple_personalization(variables, mail_body)

mailer.send(mail_body)

Send email with attachment

from mailersend import emails
import base64

mailer = emails.NewEmail()

# define an empty dict to populate with mail values
mail_body = {}

mail_from = {
    "name": "Your Name",
    "email": "[email protected]",
}

recipients = [
    {
        "name": "Your Client",
        "email": "[email protected]",
    }
]

variables = [
    {
        "email": "[email protected]",
        "substitutions": [
            {
                "var": "foo",
                "value": "bar"
            },
        ]
    }
]

attachment = open('path-to-file', 'rb')
att_read = attachment.read()
att_base64 = base64.b64encode(bytes(att_read))
attachments = [
    {
        "id": "my-attached-file",
        "filename": "file.jpg",
        "content": f"{att_base64.decode('ascii')}"
    }
]

mailer.set_mail_from(mail_from, mail_body)
mailer.set_mail_to(recipients, mail_body)
mailer.set_subject("Hello from {$foo}", mail_body)
mailer.set_html_content("This is the HTML content, {$foo}", mail_body)
mailer.set_plaintext_content("This is the text content, {$foo}", mail_body)
mailer.set_simple_personalization(variables, mail_body)
mailer.set_attachments(attachments, mail_body)

mailer.send(mail_body)

Activity

Get a list of activities (simple)

from mailersend import activity

mailer = activity.NewActivity()

mailer.get_domain_activity("domain-id")

Get a list of activities (full)

from mailersend import activity

mailer = activity.NewActivity()

page = 1
limit = 20
date_from = 1623073576
date_to = 1623074976
events = [
    "processed",
    "queued",
    "sent",
    "delivered",
    "soft-bounced",
    "hard-bounced",
    "junk",
    "opened",
    "clicked",
    "unsubscribed",
    "spam_complaints",
]

mailer.get_domain_activity("domain-id", page, limit, date_from, date_to, events)

Analytics

Activity data by date

from mailersend import analytics

mailer = analytics.NewAnalytics()

date_from = 1623073576
date_to = 1623074976
events = [
    "processed",
    "sent",
]

# optional arguments
domain_id = "domain-id"
group_by = "days"

mailer.get_activity_by_date(date_from, date_to, events, domain_id, group_by)

Opens by country

from mailersend import analytics

mailer = analytics.NewAnalytics()

date_from = 1623073576
date_to = 1623074976

# optional arguments
domain_id = "domain-id"

mailer.get_opens_by_country(date_from, date_to, domain_id)

Opens by user-agent name

from mailersend import analytics

mailer = analytics.NewAnalytics()

date_from = 1623073576
date_to = 1623074976

# optional arguments
domain_id = "domain-id"

mailer.get_opens_by_user_agent(date_from, date_to, domain_id)

Opens by reading environment

from mailersend import analytics

mailer = analytics.NewAnalytics()

date_from = 1623073576
date_to = 1623074976

# optional arguments
domain_id = "domain-id"

mailer.get_opens_by_reading_environment(date_from, date_to, domain_id)

Domains

Get a list of domains

from mailersend import domains

mailer = domains.NewDomain()

mailer.get_domains()

Get a single domain

from mailersend import domains

mailer = domains.NewDomain()

mailer.get_domain_by_id("domain-id")

Get a single domain using helper function

from mailersend import domains
from mailersend import utils

mailer = domains.NewDomain()
helper = utils.NewHelper()

mailer.get_domain_by_id(helper.get_id_by_name("domains","domain-name"))

Delete a domain

from mailersend import domains

mailer = domains.NewDomain()

mailer.delete_domain("domain-id")

Get a list of recipients per domain

from mailersend import domains

mailer = domains.NewDomain()

mailer.get_recipients_for_domain("domain-id")

Update domain settings

You can find a full list of settings here.

from mailersend import domains

mailer = domains.NewDomain()

mailer.update_domain_setting("domain-id", "send_paused", True)

Messages

Get a list of messages

from mailersend import messages

mailer = messages.NewMessage()

mailer.get_messages()

Get a single message

from mailersend import messages

mailer = messages.NewMessage()

mailer.get_message_by_id("message-id")

Recipients

Get a list of recipients

from mailersend import recipients

mailer = recipients.NewRecipient()

mailer.get_recipients()

Get a single recipient

from mailersend import recipients

mailer = recipients.NewRecipient()

mailer.get_recipient_by_id("recipient-id")

Delete a recipient

from mailersend import recipients

mailer = recipients.NewRecipient()

mailer.delete_recipient("recipient-id")

Get recipients from a blocklist

from mailersend import recipients

mailer = recipients.NewRecipient()

mailer.get_recipients_from_blocklist("domain-id")

Get recipients from hard bounces

from mailersend import recipients

mailer = recipients.NewRecipient()

mailer.get_hard_bounces("domain-id")

Get recipients from spam complaints

from mailersend import recipients

mailer = recipients.NewRecipient()

mailer.get_spam_complaints("domain-id")

Get recipients from unsubscribes

from mailersend import recipients

mailer = recipients.NewRecipient()

mailer.get_unsubscribes("domain-id")

Add recipients to blocklist

Using recipients:

from mailersend import recipients

mailer = recipients.NewRecipient()

recipient_list = [
    '[email protected]'
]

mailer.add_to_blocklist("domain-id", recipients=recipient_list)

Using patterns:

from mailersend import recipients

mailer = recipients.NewRecipient()

recipient_patterns = [
    '*@client.com'
]

mailer.add_to_blocklist("domain-id", patterns=recipient_patterns)

Add hard bounced recipients

from mailersend import recipients

mailer = recipients.NewRecipient()

recipient_list = [
    "[email protected]"
]

mailer.add_hard_bounces("domain-id", recipient_list)

Add spam complaints

from mailersend import recipients

mailer = recipients.NewRecipient()

recipient_list = [
    "[email protected]"
]

mailer.add_spam_complaints("domain-id", recipient_list)

Add recipients to unsubscribe list

from mailersend import recipients

mailer = recipients.NewRecipient()

recipient_list = [
    "[email protected]"
]

mailer.add_unsubscribes("domain-id", recipient_list)

Delete recipients from blocklist

from mailersend import recipients

mailer = recipients.NewRecipient()

recipient_list = [
    "[email protected]"
]

mailer.delete_from_blocklist("domain-id", recipient_list)

Delete hard bounced recipients

from mailersend import recipients

mailer = recipients.NewRecipient()

recipient_list = [
    "[email protected]"
]

mailer.delete_hard_bounces("domain-id", recipient_list)

Delete spam complaints

from mailersend import recipients

mailer = recipients.NewRecipient()

recipient_list = [
    "[email protected]"
]

mailer.delete_spam_complaints("domain-id", recipient_list)

Delete recipients from unsubscribe list

from mailersend import recipients

mailer = recipients.NewRecipient()

recipient_list = [
    "[email protected]"
]

mailer.delete_unsubscribes("domain-id", recipient_list)

Tokens

Create a token

from mailersend import tokens

mailer = tokens.NewToken()

scopes = ["email_full", "analytics_read"]

mailer.create_token("my-token", scopes)

Because of security reasons, we only allow access token appearance once during creation. In order to see the access token created you can do:

from mailersend import tokens

mailer = tokens.NewToken()

scopes = ["email_full", "analytics_read"]

print(mailer.create_token("my-token", scopes))

Pause / Unpause Token

from mailersend import tokens

mailer = tokens.NewToken()

# pause
mailer.update_token("my-token")

# unpause
mailer.update_token("my-token", pause=False)

Delete a Token

from mailersend import tokens

mailer = tokens.NewToken()

mailer.delete_token("token-id")

Webhooks

Get a list of webhooks

from mailersend import webhooks

mailer = webhooks.NewWebhook()

mailer.get_webhooks("domain-id")

Get a single webhook

from mailersend import webhooks

mailer = webhooks.NewWebhook()

mailer.get_webhook_by_id("webhook-id")

Create a Webhook

from mailersend import webhooks

webhookEvents = ['activity.sent', 'activity.delivered']

webhook = webhooks.NewWebhook()
webhook.set_webhook_url("https://webhooks.mysite.com")
webhook.set_webhook_name("my first webhook")
webhook.set_webhook_events(webhookEvents)
webhook.set_webhook_domain("domain-id")

webhook.create_webhook()

Create a disabled webhook

from mailersend import webhooks

webhookEvents = ['activity.sent', 'activity.delivered']

webhook = webhooks.NewWebhook()
webhook.set_webhook_url("https://webhooks.mysite.com")
webhook.set_webhook_name("my first webhook")
webhook.set_webhook_events(webhookEvents)
webhook.set_webhook_domain("domain-id")
webhook.set_webhook_enabled(False)

webhook.create_webhook()

Update a Webhook

from mailersend import webhooks

webhook = webhooks.NewWebhook()

webhook.update_webhook("webhook-id", "name", "a new webhook name")

Disable/Enable a Webhook

from mailersend import webhooks

webhook = webhooks.NewWebhook()

webhook.update_webhook("webhook-id", "enabled", False)

Delete a Webhook

from mailersend import webhooks

webhook = webhooks.NewWebhook()

webhook.delete_webhook("webhook-id")

Testing

TBD

Available endpoints

Feature group	Endpoint	Available
Activity	`GET activity`	✅
Analytics	`GET analytics`	✅
Domains	`{GET,PUT,DELETE} domains`	✅
Emails	`POST send`	✅
Messages	`GET messages`	✅
Recipients	`{GET,DELETE} recipients`	✅
Templates	`{GET,DELETE} templates`	✅
Tokens	`{POST,PUT,DELETE} tokens`	✅
Webhooks	`{GET,POST,PUT,DELETE} webhooks`	✅

If, at the moment, some endpoint is not available, please use other available tools to access it. Refer to official API docs for more info.

Support and Feedback

In case you find any bugs, submit an issue directly here in GitHub.

You are welcome to create SDK for any other programming language.

If you have any troubles using our API or SDK free to contact our support by email [email protected]

The official documentation is at https://developers.mailersend.com

License

The MIT License (MIT)

sitedata / mailersend-python Goto Github PK

mailersend-python's Introduction

Table of Contents