Mailjet V3 API wrapper
Project description
Official Mailjet Python Wrapper
Overview
Welcome to the Mailjet official Python API wrapper!
Check out all the resources and Python code examples in the official Mailjet Documentation.
Table of contents
- Compatibility
- Requirements
- Installation
- Authentication
- Make your first call
- Client / Call configuration specifics
- Request examples
- License
- Contribute
- Contributors
Compatibility
This library mailjet_rest
officially supports the following Python versions:
- Python >=3.10,<3.14
It's tested up to 3.13 (including).
Requirements
Build backend dependencies
To build the mailjet_rest
package from the sources you need setuptools
(as a build backend), wheel
, and setuptools-scm
.
Runtime dependencies
At runtime the package requires only requests >=2.32.4
.
Test dependencies
For running test you need pytest >=7.0.0
at least.
Make sure to provide the environment variables from Authentication.
Installation
pip install
Use the below code to install the the wrapper:
pip install mailjet-rest
git clone & pip install locally
Use the below code to install the wrapper locally by cloning this repository:
git clone https://github.com/mailjet/mailjet-apiv3-python
cd mailjet-apiv3-python
pip install .
conda & make
Use the below code to install it locally by conda
and make
on Unix platforms:
make install
For development
Using conda
on Linux or macOS:
- A basic environment with a minimum number of dependencies:
make dev
conda activate mailjet
- A full dev environment:
make dev-full
conda activate mailjet-dev
Authentication
The Mailjet Email API uses your API and Secret keys for authentication. Grab and save your Mailjet API credentials.
export MJ_APIKEY_PUBLIC='your api key'
export MJ_APIKEY_PRIVATE='your api secret'
Initialize your Mailjet client:
# import the mailjet wrapper
from mailjet_rest import Client
import os
# Get your environment Mailjet keys
api_key = os.environ["MJ_APIKEY_PUBLIC"]
api_secret = os.environ["MJ_APIKEY_PRIVATE"]
mailjet = Client(auth=(api_key, api_secret))
Make your first call
Here's an example on how to send an email:
from mailjet_rest import Client
import os
api_key = os.environ["MJ_APIKEY_PUBLIC"]
api_secret = os.environ["MJ_APIKEY_PRIVATE"]
mailjet = Client(auth=(api_key, api_secret))
data = {
"FromEmail": "$SENDER_EMAIL",
"FromName": "$SENDER_NAME",
"Subject": "Your email flight plan!",
"Text-part": "Dear passenger, welcome to Mailjet! May the delivery force be with you!",
"Html-part": '<h3>Dear passenger, welcome to <a href="https://www.mailjet.com/">Mailjet</a>!<br />May the delivery force be with you!',
"Recipients": [{"Email": "$RECIPIENT_EMAIL"}],
}
result = mailjet.send.create(data=data)
print(result.status_code)
print(result.json())
Client / Call Configuration Specifics
API Versioning
The Mailjet API is spread among three distinct versions:
v3
- The Email APIv3.1
- Email Send API v3.1, which is the latest version of our Send APIv4
- SMS API (not supported in Python)
Since most Email API endpoints are located under v3
, it is set as the default one and does not need to be specified when making your request. For the others you need to specify the version using version
. For example, if using Send API v3.1
:
# import the mailjet wrapper
from mailjet_rest import Client
import os
# Get your environment Mailjet keys
api_key = os.environ["MJ_APIKEY_PUBLIC"]
api_secret = os.environ["MJ_APIKEY_PRIVATE"]
mailjet = Client(auth=(api_key, api_secret), version="v3.1")
For additional information refer to our API Reference.
Base URL
The default base domain name for the Mailjet API is api.mailjet.com
. You can modify this base URL by setting a value for api_url
in your call:
mailjet = Client(auth=(api_key, api_secret), api_url="https://api.us.mailjet.com/")
If your account has been moved to Mailjet's US architecture, the URL value you need to set is https://api.us.mailjet.com
.
URL path
According to python special characters limitations we can't use slashes /
and dashes -
which is acceptable for URL path building. Instead python client uses another way for path building. You should replace slashes /
by underscore _
and dashes -
by capitalizing next letter in path.
For example, to reach statistics/link-click
path you should call statistics_linkClick
attribute of python client.
# GET `statistics/link-click`
mailjet = Client(auth=(api_key, api_secret))
filters = {"CampaignId": "xxxxxxx"}
result = mailjet.statistics_linkClick.get(filters=filters)
print(result.status_code)
print(result.json())
Request examples
Full list of supported endpoints
[!IMPORTANT]
This is a full list of supported endpoints this wrapper provides samples
POST request
Simple POST request
"""
Create a new contact:
"""
from mailjet_rest import Client
import os
api_key = os.environ["MJ_APIKEY_PUBLIC"]
api_secret = os.environ["MJ_APIKEY_PRIVATE"]
mailjet = Client(auth=(api_key, api_secret))
data = {"Email": "Mister@mailjet.com"}
result = mailjet.contact.create(data=data)
print(result.status_code)
print(result.json())
Using actions
"""
Manage the subscription status of a contact to multiple lists:
"""
from mailjet_rest import Client
import os
api_key = os.environ["MJ_APIKEY_PUBLIC"]
api_secret = os.environ["MJ_APIKEY_PRIVATE"]
mailjet = Client(auth=(api_key, api_secret))
id = "$ID"
data = {
"ContactsLists": [
{"ListID": "$ListID_1", "Action": "addnoforce"},
{"ListID": "$ListID_2", "Action": "addforce"},
]
}
result = mailjet.contact_managecontactslists.create(id=id, data=data)
print(result.status_code)
print(result.json())
GET Request
Retrieve all objects
"""
Retrieve all contacts:
"""
from mailjet_rest import Client
import os
api_key = os.environ["MJ_APIKEY_PUBLIC"]
api_secret = os.environ["MJ_APIKEY_PRIVATE"]
mailjet = Client(auth=(api_key, api_secret))
result = mailjet.contact.get()
print(result.status_code)
print(result.json())
Using filtering
"""
Retrieve all contacts that are not in the campaign exclusion list:
"""
from mailjet_rest import Client
import os
api_key = os.environ["MJ_APIKEY_PUBLIC"]
api_secret = os.environ["MJ_APIKEY_PRIVATE"]
mailjet = Client(auth=(api_key, api_secret))
filters = {
"IsExcludedFromCampaigns": "false",
}
result = mailjet.contact.get(filters=filters)
print(result.status_code)
print(result.json())
Using pagination
Some requests (for example GET /contact) has limit
, offset
and sort
query string parameters. These parameters could be used for pagination.
limit
int
Limit the response to a select number of returned objects. Default value: 10
. Maximum value: 1000
offset
int
Retrieve a list of objects starting from a certain offset. Combine this query parameter with limit
to retrieve a specific section of the list of objects. Default value: 0
sort
str
Sort the results by a property and select ascending (ASC) or descending (DESC) order. The default order is ascending. Keep in mind that this is not available for all properties. Default value: ID asc
Next example returns 40 contacts starting from 51th record sorted by Email
field descendally:
import os
from mailjet_rest import Client
api_key = os.environ["MJ_APIKEY_PUBLIC"]
api_secret = os.environ["MJ_APIKEY_PRIVATE"]
mailjet = Client(auth=(api_key, api_secret))
filters = {
"limit": 40,
"offset": 50,
"sort": "Email desc",
}
result = mailjet.contact.get(filters=filters)
print(result.status_code)
print(result.json())
Retrieve a single object
"""
Retrieve a specific contact ID:
"""
from mailjet_rest import Client
import os
api_key = os.environ["MJ_APIKEY_PUBLIC"]
api_secret = os.environ["MJ_APIKEY_PRIVATE"]
mailjet = Client(auth=(api_key, api_secret))
id_ = "Contact_ID"
result = mailjet.contact.get(id=id_)
print(result.status_code)
print(result.json())
PUT request
A PUT
request in the Mailjet API will work as a PATCH
request - the update will affect only the specified properties. The other properties of an existing resource will neither be modified, nor deleted. It also means that all non-mandatory properties can be omitted from your payload.
Here's an example of a PUT
request:
"""
Update the contact properties for a contact:
"""
from mailjet_rest import Client
import os
api_key = os.environ["MJ_APIKEY_PUBLIC"]
api_secret = os.environ["MJ_APIKEY_PRIVATE"]
mailjet = Client(auth=(api_key, api_secret))
id_ = "$CONTACT_ID"
data = {
"Data": [
{"Name": "first_name", "value": "John"},
{"Name": "last_name", "value": "Smith"},
]
}
result = mailjet.contactdata.update(id=id_, data=data)
print(result.status_code)
print(result.json())
DELETE request
Upon a successful DELETE
request the response will not include a response body, but only a 204 No Content
response code.
Here's an example of a DELETE
request:
"""
Delete an email template:
"""
from mailjet_rest import Client
import os
api_key = os.environ["MJ_APIKEY_PUBLIC"]
api_secret = os.environ["MJ_APIKEY_PRIVATE"]
mailjet = Client(auth=(api_key, api_secret))
id_ = "Template_ID"
result = mailjet.template.delete(id=id_)
print(result.status_code)
print(result.json())
License
Contribute
Mailjet loves developers. You can be part of this project!
This wrapper is a great introduction to the open source world, check out the code!
Feel free to ask anything, and contribute:
- Fork the project.
- Create a new branch.
- Implement your feature or bug fix.
- Add documentation to it.
- Commit, push, open a pull request and voila.
If you have suggestions on how to improve the guides, please submit an issue in our Official API Documentation repo.
Contributors
Project details
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
Built Distribution
File details
Details for the file mailjet_rest-1.5.0.tar.gz
.
File metadata
- Download URL: mailjet_rest-1.5.0.tar.gz
- Upload date:
- Size: 42.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
e1f50255415c57508313b1ec0be143d942e6e147318cb56532d1ecbf9b97f332
|
|
MD5 |
99bc9d56ef55df1b6c18ad08ee5d8993
|
|
BLAKE2b-256 |
7766b6ff0ed1c8cde8b07ea7ae42ea3ce0dda86f2d07537185b6e6569b410777
|
File details
Details for the file mailjet_rest-1.5.0-py3-none-any.whl
.
File metadata
- Download URL: mailjet_rest-1.5.0-py3-none-any.whl
- Upload date:
- Size: 28.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
bf30aefe12b9b3adb370d839e3fa24f7a7bfbbcf7ce04d018fb613d9c2e8a122
|
|
MD5 |
a3e23409ba7ba44bf1b9a3d6c5776f24
|
|
BLAKE2b-256 |
df55aa3eebf9607c81cc0bbec55ee9d76f6eddc76cf2f44e5b19225ec06858ea
|