Installation

$ python -m pip install mailersend

Requirements

Python > 3.6.1
Python pip
An API Key from mailersend.com

Authentication

We recommend you to define MAILERSEND_API_KEY environment variable in the .env file, and use it to store the API key.

Using environment variable

from mailersend import emails

# assigning NewEmail() without params defaults to MAILERSEND_API_KEY env var
mailer = emails.NewEmail()

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

mail_from = {
    "name": "Your Name",
    "email": "your@domain.com",
}

recipients = [
    {
        "name": "Your Client",
        "email": "your@client.com",
    }
]

reply_to = {
    "name": "Name",
    "email": "reply@domain.com",
}

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_reply_to(reply_to, mail_body)

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

Explicit declaration

from mailersend import emails

mailer = emails.NewEmail("my-api-key")

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

mail_from = {
    "name": "Your Name",
    "email": "your@domain.com",
}

recipients = [
    {
        "name": "Your Client",
        "email": "your@client.com",
    }
]

reply_to = {
    "name": "Name",
    "email": "reply@domain.com",
}

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_reply_to(reply_to, mail_body)

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

Usage

Email

Send an email

from mailersend import emails
from dotenv import load_dotenv

load_dotenv()

mailer = emails.NewEmail(os.getenv('MAILERSEND_API_KEY'))

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

mail_from = {
    "name": "Your Name",
    "email": "your@domain.com",
}

recipients = [
    {
        "name": "Your Client",
        "email": "your@client.com",
    }
]

reply_to = {
    "name": "Name",
    "email": "reply@domain.com",
}

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_reply_to(reply_to, mail_body)

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

Add CC, BCC recipients

from mailersend import emails
from dotenv import load_dotenv

load_dotenv()

mailer = emails.NewEmail(os.getenv('MAILERSEND_API_KEY'))

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

mail_from = {
    "name": "Your Name",
    "email": "your@domain.com",
}

recipients = [
    {
        "name": "Your Client",
        "email": "your@client.com",
    }
]

cc = [
    {
        "name": "CC",
        "email": "cc@client.com"
    }
]

bcc = [
    {
        "name": "BCC",
        "email": "bcc@client.com"
    }
]

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
from dotenv import load_dotenv

load_dotenv()

mailer = emails.NewEmail(os.getenv('MAILERSEND_API_KEY'))

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

mail_from = {
    "name": "Your Name",
    "email": "your@domain.com",
}

recipients = [
    {
        "name": "Your Client",
        "email": "your@client.com",
    }
]


variables = [
    {
        "email": "your@client.com",
        "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
from dotenv import load_dotenv

load_dotenv()

mailer = emails.NewEmail(os.getenv('MAILERSEND_API_KEY'))

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

mail_from = {
    "name": "Your Name",
    "email": "your@domain.com",
}

recipients = [
    {
        "name": "Your Client",
        "email": "your@client.com",
    }
]

personalization = [
    {
        "email": "test@mailersend.com",
        "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
from dotenv import load_dotenv

load_dotenv()

mailer = emails.NewEmail(os.getenv('MAILERSEND_API_KEY'))

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

mail_from = {
    "name": "Your Name",
    "email": "your@domain.com",
}

recipients = [
    {
        "name": "Your Client",
        "email": "your@client.com",
    }
]

variables = [
    {
        "email": "your@client.com",
        "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
from dotenv import load_dotenv

load_dotenv()

mailer = emails.NewEmail(os.getenv('MAILERSEND_API_KEY'))

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

mail_from = {
    "name": "Your Name",
    "email": "your@domain.com",
}

recipients = [
    {
        "name": "Your Client",
        "email": "your@client.com",
    }
]

variables = [
    {
        "email": "your@client.com",
        "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')}",
        "disposition": "attachment"
    }
]

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)

Email Verification

Get all email verification lists

from mailersend import email_verification
from dotenv import load_dotenv

load_dotenv()

mailer = email_verification.NewEmailVerification(os.getenv('MAILERSEND_API_KEY'))

mailer.get_all_lists()

Get a single email verification list

from mailersend import email_verification
from dotenv import load_dotenv

load_dotenv()

mailer = email_verification.NewEmailVerification(os.getenv('MAILERSEND_API_KEY'))

email_verification_list_id = 123456

mailer.get_list(email_verification_list_id)

Create a email verification list

from mailersend import email_verification
from dotenv import load_dotenv

load_dotenv()

mailer = email_verification.NewEmailVerification(os.getenv('MAILERSEND_API_KEY'))

name = "My List"
emails = [
    "some@email.com",
    "another@email.com"
]

mailer.create_list(name, emails)

Verify a list

from mailersend import email_verification
from dotenv import load_dotenv

load_dotenv()

mailer = email_verification.NewEmailVerification(os.getenv('MAILERSEND_API_KEY'))

email_verification_list_id = 123456

mailer.verify_list(email_verification_list_id)

Get list results

from mailersend import email_verification
from dotenv import load_dotenv

load_dotenv()

mailer = email_verification.NewEmailVerification(os.getenv('MAILERSEND_API_KEY'))

email_verification_list_id = 123456

mailer.get_list_results(email_verification_list_id)

Bulk Email

Send bulk email

from mailersend import emails
from dotenv import load_dotenv

load_dotenv()

mailer = emails.NewEmail(os.getenv('MAILERSEND_API_KEY'))

mail_list = [
  {
    "from": {
      "email": "your@domain.com",
      "name": "Your Name"
    },
    "to": [
      {
        "email": "your@client.com",
        "name": "Your Client"
      }
    ],
    "subject": "Subject",
    "text": "This is the text content",
    "html": "<p>This is the HTML content</p>",
  },
  {
    "from": {
      "email": "your@domain.com",
      "name": "Your Name"
    },
    "to": [
      {
        "email": "your@client.com",
        "name": "Your Client"
      }
    ],
    "subject": "Subject",
    "text": "This is the text content",
    "html": "<p>This is the HTML content</p>",
  }
]

print(mailer.send_bulk(mail_list))

Get bulk email status

from mailersend import emails
from dotenv import load_dotenv

load_dotenv()

mailer = emails.NewEmail(os.getenv('MAILERSEND_API_KEY'))

print(mailer.get_bulk_status_by_id("bulk-email-id"))

Activity

Get a list of activities (simple)

from mailersend import activity
from dotenv import load_dotenv

load_dotenv()

mailer = activity.NewActivity(os.getenv('MAILERSEND_API_KEY'))

mailer.get_domain_activity("domain-id")

Get a list of activities (full)

from mailersend import activity
from dotenv import load_dotenv

load_dotenv()

mailer = activity.NewActivity(os.getenv('MAILERSEND_API_KEY'))

page = 1
limit = 20
date_from = 1623073576
date_to = 1623074976
events = [
    "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
from dotenv import load_dotenv

load_dotenv()

mailer = analytics.NewAnalytics(os.getenv('MAILERSEND_API_KEY'))

date_from = 1623073576
date_to = 1623074976
events = [
    "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
from dotenv import load_dotenv

load_dotenv()

mailer = analytics.NewAnalytics(os.getenv('MAILERSEND_API_KEY'))

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
from dotenv import load_dotenv

load_dotenv()

mailer = analytics.NewAnalytics(os.getenv('MAILERSEND_API_KEY'))

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
from dotenv import load_dotenv

load_dotenv()

mailer = analytics.NewAnalytics(os.getenv('MAILERSEND_API_KEY'))

date_from = 1623073576
date_to = 1623074976

# optional arguments
domain_id = "domain-id"

mailer.get_opens_by_reading_environment(date_from, date_to, domain_id)

Inbound Routes

Get a list of inbound routes

from mailersend import inbound_routing
from dotenv import load_dotenv

load_dotenv()

mailer = inbound_routing.NewInbound(os.getenv('MAILERSEND_API_KEY'))

print(mailer.get_inbound_routes())

Get a single inbound route

from mailersend import inbound_routing
from dotenv import load_dotenv

load_dotenv()

mailer = inbound_routing.NewInbound(os.getenv('MAILERSEND_API_KEY'))

print(mailer.get_inbound_by_id("inbound-id"))

Add an inbound route

from mailersend import inbound_routing
from dotenv import load_dotenv

load_dotenv()

mailer = inbound_routing.NewInbound(os.getenv('MAILERSEND_API_KEY'))

options = {}

_catch_filter = {
    "type": "catch_recipient",
    "filters": [
        {
            "comparer": "equal",
            "value": "test"
        }
    ]
}

_match_filter = {
    "type": "match_all"
}

_forwards = [
    {
        "type": "webhook",
        "value": "https://www.mailersend.com/hook"
    }
]
mailer.set_name("Example route", options)
mailer.set_domain_enabled(True, options)
mailer.set_inbound_domain("test.mailersend.com", options)
mailer.set_catch_filter(_catch_filter, options)

print(mailer.add_inbound_route())

Update an inbound route

from mailersend import inbound_routing
from dotenv import load_dotenv

load_dotenv()

route_id = "inbound-route-id"

mailer = inbound_routing.NewInbound(os.getenv('MAILERSEND_API_KEY'))

options = {}

_catch_filter = {
    "type": "catch_recipient",
    "filters": [
        {
            "comparer": "equal",
            "value": "test"
        }
    ]
}

_match_filter = {
    "type": "match_all"
}

_forwards = [
    {
        "type": "webhook",
        "value": "https://www.mailersend.com/hook"
    }
]
mailer.set_name("Example route", options)
mailer.set_domain_enabled(True, options)
mailer.set_inbound_domain("test.mailersend.com", options)
mailer.set_catch_filter(_catch_filter, options)

print(mailer.update_inbound_route(route_id))

Delete an inbound route

from mailersend import inbound_routing
from dotenv import load_dotenv

load_dotenv()

route_id = "inbound-route-id"

mailer = inbound_routing.NewInbound(os.getenv('MAILERSEND_API_KEY'))

print(mailer.delete_inbound_route(route_id))

Domains

Get a list of domains

from mailersend import domains
from dotenv import load_dotenv

load_dotenv()

mailer = domains.NewDomain(os.getenv('MAILERSEND_API_KEY'))

mailer.get_domains()

Get a single domain

from mailersend import domains
from dotenv import load_dotenv

load_dotenv()

mailer = domains.NewDomain(os.getenv('MAILERSEND_API_KEY'))

mailer.get_domain_by_id("domain-id")

Get a single domain using helper function

from mailersend import domains
from mailersend import utils
from dotenv import load_dotenv

load_dotenv()

mailer = domains.NewDomain(os.getenv('MAILERSEND_API_KEY'))
helper = utils.NewHelper(os.getenv('MAILERSEND_API_KEY'))

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

Add a domain

You can find a full list of settings here.

from mailersend import domains
from dotenv import load_dotenv

load_dotenv()

mailer = domains.NewDomain(os.getenv('MAILERSEND_API_KEY'))

domain_data = {
    "name": "mydomain.com",
    "return_path_subdomain": "rpsubdomain",
    "custom_tracking_subdomain": "ctsubdomain",
    "inbound_routing_subdomain": "irsubdomain"
}
mailer.add_domain("name", domain_data)

Delete a domain

from mailersend import domains
from dotenv import load_dotenv

load_dotenv()

mailer = domains.NewDomain(os.getenv('MAILERSEND_API_KEY'))

mailer.delete_domain("domain-id")

Get a list of recipients per domain

from mailersend import domains
from dotenv import load_dotenv

load_dotenv()

mailer = domains.NewDomain(os.getenv('MAILERSEND_API_KEY'))

mailer.get_recipients_for_domain("domain-id")

Update domain settings

You can find a full list of settings here.

from mailersend import domains
from dotenv import load_dotenv

load_dotenv()

mailer = domains.NewDomain(os.getenv('MAILERSEND_API_KEY'))

domain_data = {
    "send_paused": True,
    "track_clicks": True,
    "track_opens": True,
    "track_unsubscribe": True,
    "track_unsubscribe_html": "<p>Click to <a href='{$unsubscribe}'>unsubscribe</a></p>",
    "track_unsubscribe_plain": "Click to unsubscribe: {$unsubscribe}",
    "track_content": True,
    "custom_tracking_enabled": True,
    "custom_tracking_subdomain": "email",
    "precedence_bulk": False
}

mailer.update_domain_setting("domain-id", domain_data)

Get DNS Records

from mailersend import domains
from dotenv import load_dotenv

load_dotenv()

mailer = domains.NewDomain(os.getenv('MAILERSEND_API_KEY'))

mailer.get_dns_records("domain-id")

Verify a domain

from mailersend import domains
from dotenv import load_dotenv

load_dotenv()

mailer = domains.NewDomain(os.getenv('MAILERSEND_API_KEY'))

mailer.verify_domain("domain-id")

Messages

Get a list of messages

from mailersend import messages
from dotenv import load_dotenv

load_dotenv()

mailer = messages.NewMessage(os.getenv('MAILERSEND_API_KEY'))

mailer.get_messages()

Get a single message

from mailersend import messages
from dotenv import load_dotenv

load_dotenv()

mailer = messages.NewMessage(os.getenv('MAILERSEND_API_KEY'))

mailer.get_message_by_id("message-id")

Scheduled messages

Get a list of scheduled messages

from mailersend import scheduled_messages
from dotenv import load_dotenv

load_dotenv()

mailer = scheduled_messages.NewMessageSchedule(os.getenv('MAILERSEND_API_KEY'))

print(mailer.get_scheduled_messages())

Get a single scheduled message

from mailersend import scheduled_messages
from dotenv import load_dotenv

load_dotenv()

mailer = scheduled_messages.NewMessageSchedule(os.getenv('MAILERSEND_API_KEY'))

print(mailer.get_scheduled_message_by_id("scheduled-message-id"))

Delete a scheduled message

from mailersend import scheduled_messages
from dotenv import load_dotenv

load_dotenv()

mailer = scheduled_messages.NewMessageSchedule(os.getenv('MAILERSEND_API_KEY'))

print(mailer.delete_scheduled_message("scheduled-message-id"))

Recipients

Get a list of recipients

from mailersend import recipients
from dotenv import load_dotenv

load_dotenv()

mailer = recipients.NewRecipient(os.getenv('MAILERSEND_API_KEY'))

mailer.get_recipients()

Get a single recipient

from mailersend import recipients
from dotenv import load_dotenv

load_dotenv()

mailer = recipients.NewRecipient(os.getenv('MAILERSEND_API_KEY'))

mailer.get_recipient_by_id("recipient-id")

Delete a recipient

from mailersend import recipients
from dotenv import load_dotenv

load_dotenv()

mailer = recipients.NewRecipient(os.getenv('MAILERSEND_API_KEY'))

mailer.delete_recipient("recipient-id")

Get recipients from a blocklist

from mailersend import recipients
from dotenv import load_dotenv

load_dotenv()

mailer = recipients.NewRecipient(os.getenv('MAILERSEND_API_KEY'))

mailer.get_recipients_from_blocklist("domain-id")

Get recipients from hard bounces

from mailersend import recipients
from dotenv import load_dotenv

load_dotenv()

mailer = recipients.NewRecipient(os.getenv('MAILERSEND_API_KEY'))

mailer.get_hard_bounces("domain-id")

Get recipients from spam complaints

from mailersend import recipients
from dotenv import load_dotenv

load_dotenv()

mailer = recipients.NewRecipient(os.getenv('MAILERSEND_API_KEY'))

mailer.get_spam_complaints("domain-id")

Get recipients from unsubscribes

from mailersend import recipients
from dotenv import load_dotenv

load_dotenv()

mailer = recipients.NewRecipient(os.getenv('MAILERSEND_API_KEY'))

mailer.get_unsubscribes("domain-id")

Add recipients to blocklist

Using recipients:

from mailersend import recipients
from dotenv import load_dotenv

load_dotenv()

mailer = recipients.NewRecipient(os.getenv('MAILERSEND_API_KEY'))

recipient_list = [
    'blocked@client.com'
]

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

Using patterns:

from mailersend import recipients
from dotenv import load_dotenv

load_dotenv()

mailer = recipients.NewRecipient(os.getenv('MAILERSEND_API_KEY'))

recipient_patterns = [
    '*@client.com'
]

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

Add hard bounced recipients

from mailersend import recipients
from dotenv import load_dotenv

load_dotenv()

mailer = recipients.NewRecipient(os.getenv('MAILERSEND_API_KEY'))

recipient_list = [
    "your@client.com"
]

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

Add spam complaints

from mailersend import recipients
from dotenv import load_dotenv

load_dotenv()

mailer = recipients.NewRecipient(os.getenv('MAILERSEND_API_KEY'))

recipient_list = [
    "your@client.com"
]

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

Add recipients to unsubscribe list

from mailersend import recipients
from dotenv import load_dotenv

load_dotenv()

mailer = recipients.NewRecipient(os.getenv('MAILERSEND_API_KEY'))

recipient_list = [
    "your@client.com"
]

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

Delete recipients from blocklist

from mailersend import recipients
from dotenv import load_dotenv

load_dotenv()

mailer = recipients.NewRecipient(os.getenv('MAILERSEND_API_KEY'))

recipient_list = [
    "your@client.com"
]

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

Delete hard bounced recipients

from mailersend import recipients
from dotenv import load_dotenv

load_dotenv()

mailer = recipients.NewRecipient(os.getenv('MAILERSEND_API_KEY'))

recipient_list = [
    "your@client.com"
]

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

Delete spam complaints

from mailersend import recipients
from dotenv import load_dotenv

load_dotenv()

mailer = recipients.NewRecipient(os.getenv('MAILERSEND_API_KEY'))

recipient_list = [
    "your@client.com"
]

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

Delete recipients from unsubscribe list

from mailersend import recipients
from dotenv import load_dotenv

load_dotenv()

mailer = recipients.NewRecipient(os.getenv('MAILERSEND_API_KEY'))

recipient_list = [
    "your@client.com"
]

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

Tokens

Create a token

from mailersend import tokens
from dotenv import load_dotenv

load_dotenv()

mailer = tokens.NewToken(os.getenv('MAILERSEND_API_KEY'))

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
from dotenv import load_dotenv

load_dotenv()

mailer = tokens.NewToken(os.getenv('MAILERSEND_API_KEY'))

scopes = ["email_full", "analytics_read"]

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

Pause / Unpause Token

from mailersend import tokens
from dotenv import load_dotenv

load_dotenv()

mailer = tokens.NewToken(os.getenv('MAILERSEND_API_KEY'))

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

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

Delete a Token

from mailersend import tokens
from dotenv import load_dotenv

load_dotenv()

mailer = tokens.NewToken(os.getenv('MAILERSEND_API_KEY'))

mailer.delete_token("token-id")

Templates

Get a list of templates

from mailersend import templates
from dotenv import load_dotenv

load_dotenv()

mailer = templates.NewTemplate(os.getenv('MAILERSEND_API_KEY'))

mailer.get_templates()

Get a single template

from mailersend import templates
from dotenv import load_dotenv

load_dotenv()

mailer = templates.NewTemplate(os.getenv('MAILERSEND_API_KEY'))
template_id = 1234

mailer.get_template_by_id()

Delete template

from mailersend import templates
from dotenv import load_dotenv

load_dotenv()

mailer = templates.NewTemplate(os.getenv('MAILERSEND_API_KEY'))
template_id = 1234

mailer.delete_template()

Webhooks

Get a list of webhooks

from mailersend import webhooks
from dotenv import load_dotenv

load_dotenv()

mailer = webhooks.NewWebhook(os.getenv('MAILERSEND_API_KEY'))

mailer.get_webhooks("domain-id")

Get a single webhook

from mailersend import webhooks
from dotenv import load_dotenv

load_dotenv()

mailer = webhooks.NewWebhook(os.getenv('MAILERSEND_API_KEY'))

mailer.get_webhook_by_id("webhook-id")

Create a Webhook

from mailersend import webhooks
from dotenv import load_dotenv

load_dotenv()

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

webhook = webhooks.NewWebhook(os.getenv('MAILERSEND_API_KEY'))
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
from dotenv import load_dotenv

load_dotenv()

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

webhook = webhooks.NewWebhook(os.getenv('MAILERSEND_API_KEY'))
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
from dotenv import load_dotenv

load_dotenv()

webhook = webhooks.NewWebhook(os.getenv('MAILERSEND_API_KEY'))

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

Disable/Enable a Webhook

from mailersend import webhooks
from dotenv import load_dotenv

load_dotenv()

webhook = webhooks.NewWebhook(os.getenv('MAILERSEND_API_KEY'))

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

Delete a Webhook

from mailersend import webhooks
from dotenv import load_dotenv

load_dotenv()

webhook = webhooks.NewWebhook(os.getenv('MAILERSEND_API_KEY'))

webhook.delete_webhook("webhook-id")

SMS

Sending SMS messages

Without personalization:

from mailersend import sms_sending
from dotenv import load_dotenv

load_dotenv()

mailer = sms_sending.NewSmsSending(os.getenv('MAILERSEND_API_KEY'))

# Number belonging to your account in E164 format
number_from = "+11234567890"

# You can add up to 50 recipient numbers
numbers_to = [
    "+11234567891",
    "+11234567892"
]
text = "This is the text content"

print(mailer.send_sms(number_from, numbers_to, text))

With personalization:

from mailersend import sms_sending
from dotenv import load_dotenv

load_dotenv()

mailer = sms_sending.NewSmsSending(os.getenv('MAILERSEND_API_KEY'))

# Number belonging to your account in E164 format
number_from = "+11234567890"

# You can add up to 50 recipient numbers
numbers_to = [
    "+11234567891",
    "+11234567892"
]
text = "Hi {{name}} how are you?"
personalization = [
    {
        "phone_number": "+11234567891",
        "data": {
            "name": "Mike"
        }
    },
    {
        "phone_number": "+11234567892",
        "data": {
            "name": "John"
        }
    }
]

print(mailer.send_sms(number_from, numbers_to, text, personalization))

SMS Activity

Get a list of activities

from mailersend import sms_activity
from dotenv import load_dotenv

load_dotenv()

mailer = sms_activity.NewSmsActivity(os.getenv('MAILERSEND_API_KEY'))

#Request parameters
sms_number_id = 1365743
date_from = 1655157601
date_to = 1655158601
status = ["queued", "failed"]
page = 1
limit = 200

print(mailer.get_activities(sms_number_id=sms_number_id, date_from=date_from, date_to=date_to, status=status, page=page, limit=limit))

Get activity of a single message

from mailersend import sms_activity
from dotenv import load_dotenv

load_dotenv()

mailer = sms_activity.NewSmsActivity(os.getenv('MAILERSEND_API_KEY'))

#Request parameters
sms_message_id = "62a9d12b07852eaf2207b417"

print(mailer.get_activity(sms_message_id))

SMS Phone Numbers

Get a list of SMS phone numbers

from mailersend import sms_phone_numbers
from dotenv import load_dotenv

load_dotenv()

mailer = sms_phone_numbers.NewSmsNumbers(os.getenv('MAILERSEND_API_KEY'))

#Request parameters
paused = False

print(mailer.get_phone_numbers(paused))

Get an SMS phone number

from mailersend import sms_phone_numbers
from dotenv import load_dotenv

load_dotenv()

mailer = sms_phone_numbers.NewSmsNumbers(os.getenv('MAILERSEND_API_KEY'))

#Request parameters
sms_number_id = "9pq3enl6842vwrzx"

print(mailer.get_phone_number(sms_number_id))

Update a single SMS phone number

from mailersend import sms_phone_numbers
from dotenv import load_dotenv

load_dotenv()

mailer = sms_phone_numbers.NewSmsNumbers(os.getenv('MAILERSEND_API_KEY'))

#Request parameters
sms_number_id = "9pq3enl6842vwrzx"
paused = True

print(mailer.update_phone_number(sms_number_id, paused))

Delete an SMS phone number

from mailersend import sms_phone_numbers
from dotenv import load_dotenv

load_dotenv()

mailer = sms_phone_numbers.NewSmsNumbers(os.getenv('MAILERSEND_API_KEY'))

#Request parameters
sms_number_id = "9pq3enl6842vwrzx"

print(mailer.delete_phone_number(sms_number_id))

SMS Recipients

Get a list of SMS recipients

from mailersend import sms_recipients
from dotenv import load_dotenv

load_dotenv()

mailer = sms_recipients.NewSmsRecipients(os.getenv('MAILERSEND_API_KEY'))

#Request parameters
sms_number_id = "9pq3enl6842vwrzx"
status = "active"

print(mailer.get_recipients(status=status, sms_number_id=sms_number_id))

Get an SMS recipient

from mailersend import sms_recipients
from dotenv import load_dotenv

load_dotenv()

mailer = sms_recipients.NewSmsRecipients(os.getenv('MAILERSEND_API_KEY'))

#Request parameters
sms_recipient_id = "627e756fd30078fb2208cc87"

print(mailer.get_recipient(sms_recipient_id))

Update a single SMS recipient

from mailersend import sms_recipients
from dotenv import load_dotenv

load_dotenv()

mailer = sms_recipients.NewSmsRecipients(os.getenv('MAILERSEND_API_KEY'))

#Request parameters
sms_recipient_id = "627e756fd30078fb2208cc87"
status = "opt_out"

print(mailer.update_recipient(sms_recipient_id, status))

SMS Messages

Get a list of SMS messages

from mailersend import sms_messages
from dotenv import load_dotenv

load_dotenv()

mailer = sms_messages.NewSmsMessages(os.getenv('MAILERSEND_API_KEY'))

print(mailer.get_messages())

Get an SMS message

from mailersend import sms_messages
from dotenv import load_dotenv

load_dotenv()

#Request parameters
sms_message_id = "627e756fd30078fb2208cc87"

mailer = sms_messages.NewSmsMessages(os.getenv('MAILERSEND_API_KEY'))

print(mailer.get_message(sms_message_id))

SMS Webhooks

Get a list of SMS webhooks

from mailersend import sms_webhooks
from dotenv import load_dotenv

load_dotenv()

mailer = sms_webhooks.NewSmsWebhooks(os.getenv('MAILERSEND_API_KEY'))

#Request parameters
sms_number_id = "9pq3enl6842vwrzx"

print(mailer.get_webhooks(sms_number_id))

Get a single SMS webhook

from mailersend import sms_webhooks
from dotenv import load_dotenv

load_dotenv()

mailer = sms_webhooks.NewSmsWebhooks(os.getenv('MAILERSEND_API_KEY'))

#Request parameters
sms_webhook_id = "aaui13enl12f2vzx"

print(mailer.get_webhook(sms_webhook_id))

Create an SMS webhook

from mailersend import sms_webhooks
from dotenv import load_dotenv

load_dotenv()

mailer = sms_webhooks.NewSmsWebhooks(os.getenv('MAILERSEND_API_KEY'))

#Request parameters
url = "https://webhook-url.com"
name = "My Webhook Name"
events = ["sms.sent"]
sms_number_id = "9pq3enl6842vwrzx"
enabled = True

print(mailer.create_webhook(url, name, events, sms_number_id, enabled))

Update a single SMS webhook

from mailersend import sms_webhooks
from dotenv import load_dotenv

load_dotenv()

mailer = sms_webhooks.NewSmsWebhooks(os.getenv('MAILERSEND_API_KEY'))

#Request parameters
url = "https://different-url.com"
name = "New Webhook Name"
events = ["sms.sent", "sms.failed"],
sms_webhook_id = "aaui13enl12f2vzx"
enabled = False

print(mailer.update_webhook(sms_webhook_id, url, name, events, enabled))

Delete an SMS webhook

from mailersend import sms_webhooks
from dotenv import load_dotenv

load_dotenv()

mailer = sms_webhooks.NewSmsWebhooks(os.getenv('MAILERSEND_API_KEY'))

#Request parameters
sms_webhook_id = "aaui13enl12f2vzx"

print(mailer.delete_webhook(sms_webhook_id))

Get a list of SMS webhooks

from mailersend import sms_webhooks
from dotenv import load_dotenv

load_dotenv()

mailer = sms_webhooks.NewSmsWebhooks(os.getenv('MAILERSEND_API_KEY'))

#Request parameters
sms_number_id = "9pq3enl6842vwrzx"

print(mailer.get_webhooks(sms_number_id))

SMS Inbouds

Get a list of SMS inbound routes

from mailersend import sms_inbounds
from dotenv import load_dotenv

load_dotenv()

mailer = sms_inbounds.NewSmsInbounds(os.getenv('MAILERSEND_API_KEY'))

#Request parameters
sms_number_id = "123456789"
enabled = True
page = 1
limit = 25

print(mailer.get_inbound_routes(sms_number_id, enabled, page, limit))

Get a single SMS inbound route

from mailersend import sms_inbounds
from dotenv import load_dotenv

load_dotenv()

mailer = sms_inbounds.NewSmsInbounds(os.getenv('MAILERSEND_API_KEY'))

#Request parameters
sms_inbound_id = "123456789"

print(mailer.get_inbound_route(sms_inbound_id))

Create an SMS inbound route

from mailersend import sms_inbounds
from dotenv import load_dotenv

load_dotenv()

mailer = sms_inbounds.NewSmsInbounds(os.getenv('MAILERSEND_API_KEY'))

#Request parameters
sms_number_id = "123456789"
name = "My route"
forward_url = "https://some.url"
filter = {
    "comparer": "equal",
    "value": "START"
}
enabled = True

print(mailer.create_inbound_route(sms_number_id, name, forward_url, filter, enabled))

Update an SMS inbound route

from mailersend import sms_inbounds
from dotenv import load_dotenv

load_dotenv()

mailer = sms_inbounds.NewSmsInbounds(os.getenv('MAILERSEND_API_KEY'))

#Request parameters
sms_number_id = "123456789"
name = "New name"
forward_url = "https://news.url"
filter = {
    "comparer": "contains",
    "value": "some-value"
}
enabled = True

print(mailer.update_inbound_route(sms_number_id, name, forward_url, filter, enabled))

Delete an SMS inbound route

from mailersend import sms_inbounds
from dotenv import load_dotenv

load_dotenv()

mailer = sms_inbounds.NewSmsInbounds(os.getenv('MAILERSEND_API_KEY'))

#Request parameters
sms_inbound_id = "123456789"

print(mailer.delete_inbound_route()(sms_inbound_id))

Sender Identities

Get a list of sender identities

from mailersend import sender_identities
from dotenv import load_dotenv

load_dotenv()

mailer = sender_identities.NewSenderIdentity(os.getenv('MAILERSEND_API_KEY'))

print(mailer.get_identities())

Get a sender identity

from mailersend import sender_identities
from dotenv import load_dotenv

load_dotenv()

mailer = sender_identities.NewSenderIdentity(os.getenv('MAILERSEND_API_KEY'))

print(mailer.get_identity(identity_id="12345"))

Create a sender identity

from mailersend import sender_identities
from dotenv import load_dotenv

load_dotenv()

mailer = sender_identities.NewSenderIdentity(os.getenv('MAILERSEND_API_KEY'))

print(mailer.create_identity(
    domain_id="123456",
    name="John Doe",
    email="email@domain.com",
    reply_to_email="reply@domain.com",
    reply_to_name="Doe John",
    add_note=True,
    personal_note="My awesome note",
))

Update a sender identity

from mailersend import sender_identities
from dotenv import load_dotenv

load_dotenv()

mailer = sender_identities.NewSenderIdentity(os.getenv('MAILERSEND_API_KEY'))

print(mailer.update_identity(
    identity_id="123456",
    domain_id="123456",
    name="Abe Doe",
    email="email@mydomain.com",
    reply_to_email="reply@mydomain.com",
    reply_to_name="Doe Abe",
    add_note=False
))

Delete a sender identity

from mailersend import sender_identities
from dotenv import load_dotenv

load_dotenv()

mailer = sender_identities.NewSenderIdentity(os.getenv('MAILERSEND_API_KEY'))

print(mailer.delete_identity(identity_id="123456"))

API Quota

Get API Quota

from mailersend import api_quota
from dotenv import load_dotenv

load_dotenv()

mailer = api_quota.NewApiQuota(os.getenv('MAILERSEND_API_KEY'))

print(mailer.get_quota())

Troubleshooting

Emails not being sent

Print the output of mailer.send() to view status code and errors.

from mailersend import emails

mailer = emails.NewEmail()

mail_body = {}

print(mailer.send(mail_body))

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`	✅
SMS Sending	`{POST} sms`	✅
SMS Activity	`{GET} sms-activity`	✅
SMS Phone numbers	`{GET, PUT, DELETE} sms-numbers`	✅
SMS Recipients	`{GET, PUT} sms-recipients`	✅
SMS Messages	`{GET} sms-messages`	✅
SMS Webhooks	`{GET, POST, PUT, DELETE} sms-webhooks`	✅
SMS Inbounds	`{GET, POST, PUT, DELETE} sms-inbounds`	✅
Sender Identities	`{GET, POST, PUT, DELETE} identities`	✅
API Quota	`{GET} api-quota`	✅

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 info@mailersend.com

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

License

The MIT License (MIT)

Name		Name	Last commit message	Last commit date
Latest commit History 292 Commits
.github		.github
mailersend		mailersend
tests		tests
.envrc		.envrc
.flake8		.flake8
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
LICENSE		LICENSE
README.md		README.md
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml
renovate.json		renovate.json