[mailjet]:(http://www.mailjet.com/)
[api_credential]: https://app.mailjet.com/account/api_keys
[doc]: http://dev.mailjet.com/guides/?python#
[api_doc]: https://github.com/mailjet/api-documentation
# Official Mailjet Python Wrapper
[](https://travis-ci.org/mailjet/mailjet-apiv3-python)
## Overview
Welcome to the [Mailjet][mailjet] official Python API wrapper!
Check out all the resources and Python code examples in the official [Mailjet Documentation][doc].
## Table of contents
- [Compatibility](#compatibility)
- [Installation](#installation)
- [Authentication](#authentication)
- [Make your first call](#make-your-first-call)
- [Client / Call configuration specifics](#client--call-configuration-specifics)
- [API versioning](#api-versioning)
- [Base URL](#base-url)
- [Request examples](#request-examples)
- [POST request](#post-request)
- [Simple POST request](#simple-post-request)
- [Using actions](#using-actions)
- [GET request](#get-request)
- [Retrieve all objects](#retrieve-all-objects)
- [Use filtering](#use-filtering)
- [Retrieve a single object](#retrieve-a-single-object)
- [PUT request](#put-request)
- [DELETE request](#delete-request)
- [Contribute](#contribute)
## Compatibility
This library officially supports the following Python versions:
- v2.7
- v3.5
- v3.6
## Installation
Use the below code to install the wrapper:
``` bash
(sudo) pip install mailjet_rest
```
## Authentication
The Mailjet Email API uses your API and Secret keys for authentication. [Grab][api_credential] and save your Mailjet API credentials.
```bash
export MJ_APIKEY_PUBLIC='your api key'
export MJ_APIKEY_PRIVATE='your api secret'
```
Initialize your [Mailjet][mailjet] client:
```python
# 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:
```python
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), version='v3.1')
data = {
'Messages': [
{
"From": {
"Email": "$SENDER_EMAIL",
"Name": "Me"
},
"To": [
{
"Email": "$RECIPIENT_EMAIL",
"Name": "You"
}
],
"Subject": "My first Mailjet Email!",
"TextPart": "Greetings from Mailjet!",
"HTMLPart": "<h3>Dear passenger 1, welcome to <a href=\"https://www.mailjet.com/\">Mailjet</a>!</h3><br />May the delivery force be with you!"
}
]
}
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 API
- `v3.1` - Email Send API v3.1, which is the latest version of our Send API
- `v4` - 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`:
``` python
# 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](https://dev.preprod.mailjet.com/reference/overview/versioning/).
### 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:
```python
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`.
## Request examples
### POST request
#### Simple POST request
```python
"""
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
```python
"""
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
```python
"""
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
```python
"""
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()
```
#### Retrieve a single object
```python
"""
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:
```python
"""
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:
```python
"""
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()
```
## 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](https://github.com/mailjet/api-documentation).
Raw data
{
"_id": null,
"home_page": "https://github.com/mailjet/mailjet-apiv3-python",
"name": "mailjet-rest",
"maintainer": "Mailjet",
"docs_url": null,
"requires_python": "",
"maintainer_email": "api@mailjet.com",
"keywords": "Mailjet API v3 / v3.1 Python Wrapper",
"author": "starenka",
"author_email": "starenka0@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ad/68/e72ee94650da7cfd902bfdde3f019a5ae9b86dc31ba58c806055fa12e537/mailjet_rest-1.3.4.tar.gz",
"platform": "",
"description": "\n[mailjet]:(http://www.mailjet.com/)\n[api_credential]: https://app.mailjet.com/account/api_keys\n[doc]: http://dev.mailjet.com/guides/?python#\n[api_doc]: https://github.com/mailjet/api-documentation\n\n![alt text](https://www.mailjet.com/images/email/transac/logo_header.png \"Mailjet\")\n\n# Official Mailjet Python Wrapper\n\n[](https://travis-ci.org/mailjet/mailjet-apiv3-python)\n\n\n## Overview\n\nWelcome to the [Mailjet][mailjet] official Python API wrapper!\n\nCheck out all the resources and Python code examples in the official [Mailjet Documentation][doc].\n\n## Table of contents\n\n- [Compatibility](#compatibility)\n- [Installation](#installation)\n- [Authentication](#authentication)\n- [Make your first call](#make-your-first-call)\n- [Client / Call configuration specifics](#client--call-configuration-specifics)\n - [API versioning](#api-versioning)\n - [Base URL](#base-url)\n- [Request examples](#request-examples)\n - [POST request](#post-request)\n - [Simple POST request](#simple-post-request)\n - [Using actions](#using-actions)\n - [GET request](#get-request)\n - [Retrieve all objects](#retrieve-all-objects)\n - [Use filtering](#use-filtering)\n - [Retrieve a single object](#retrieve-a-single-object)\n - [PUT request](#put-request)\n - [DELETE request](#delete-request)\n- [Contribute](#contribute)\n\n## Compatibility\n\nThis library officially supports the following Python versions:\n\n - v2.7\n - v3.5\n - v3.6\n\n## Installation\n\nUse the below code to install the wrapper:\n\n``` bash\n(sudo) pip install mailjet_rest\n```\n\n## Authentication\n\nThe Mailjet Email API uses your API and Secret keys for authentication. [Grab][api_credential] and save your Mailjet API credentials.\n\n```bash\nexport MJ_APIKEY_PUBLIC='your api key'\nexport MJ_APIKEY_PRIVATE='your api secret'\n```\n\nInitialize your [Mailjet][mailjet] client:\n\n```python\n# import the mailjet wrapper\nfrom mailjet_rest import Client\nimport os\n\n# Get your environment Mailjet keys\nAPI_KEY = os.environ['MJ_APIKEY_PUBLIC']\nAPI_SECRET = os.environ['MJ_APIKEY_PRIVATE']\n\nmailjet = Client(auth=(API_KEY, API_SECRET))\n```\n\n## Make your first call\n\nHere's an example on how to send an email:\n\n```python\nfrom mailjet_rest import Client\nimport os\napi_key = os.environ['MJ_APIKEY_PUBLIC']\napi_secret = os.environ['MJ_APIKEY_PRIVATE']\nmailjet = Client(auth=(api_key, api_secret), version='v3.1')\ndata = {\n 'Messages': [\n {\n \"From\": {\n \"Email\": \"$SENDER_EMAIL\",\n \"Name\": \"Me\"\n },\n \"To\": [\n {\n \"Email\": \"$RECIPIENT_EMAIL\",\n \"Name\": \"You\"\n }\n ],\n \"Subject\": \"My first Mailjet Email!\",\n \"TextPart\": \"Greetings from Mailjet!\",\n \"HTMLPart\": \"<h3>Dear passenger 1, welcome to <a href=\\\"https://www.mailjet.com/\\\">Mailjet</a>!</h3><br />May the delivery force be with you!\"\n }\n ]\n}\nresult = mailjet.send.create(data=data)\nprint result.status_code\nprint result.json()\n```\n\n## Client / Call Configuration Specifics\n\n### API Versioning\n\nThe Mailjet API is spread among three distinct versions:\n\n- `v3` - The Email API\n- `v3.1` - Email Send API v3.1, which is the latest version of our Send API\n- `v4` - SMS API (not supported in Python)\n\nSince 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`:\n\n``` python\n# import the mailjet wrapper\nfrom mailjet_rest import Client\nimport os\n\n# Get your environment Mailjet keys\nAPI_KEY = os.environ['MJ_APIKEY_PUBLIC']\nAPI_SECRET = os.environ['MJ_APIKEY_PRIVATE']\n\nmailjet = Client(auth=(API_KEY, API_SECRET), version='v3.1')\n```\n\nFor additional information refer to our [API Reference](https://dev.preprod.mailjet.com/reference/overview/versioning/).\n\n### Base URL\n\nThe 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:\n\n```python\nmailjet = Client(auth=(api_key, api_secret),api_url=\"https://api.us.mailjet.com/\")\n```\n\nIf your account has been moved to Mailjet's **US architecture**, the URL value you need to set is `https://api.us.mailjet.com`.\n\n## Request examples\n\n### POST request\n\n#### Simple POST request\n\n```python\n\"\"\"\nCreate a new contact:\n\"\"\"\nfrom mailjet_rest import Client\nimport os\napi_key = os.environ['MJ_APIKEY_PUBLIC']\napi_secret = os.environ['MJ_APIKEY_PRIVATE']\nmailjet = Client(auth=(api_key, api_secret))\ndata = {\n 'Email': 'Mister@mailjet.com'\n}\nresult = mailjet.contact.create(data=data)\nprint result.status_code\nprint result.json()\n```\n\n#### Using actions\n\n```python\n\"\"\"\nManage the subscription status of a contact to multiple lists:\n\"\"\"\nfrom mailjet_rest import Client\nimport os\napi_key = os.environ['MJ_APIKEY_PUBLIC']\napi_secret = os.environ['MJ_APIKEY_PRIVATE']\nmailjet = Client(auth=(api_key, api_secret))\nid = '$ID'\ndata = {\n 'ContactsLists': [\n {\n \"ListID\": \"$ListID_1\",\n \"Action\": \"addnoforce\"\n },\n {\n \"ListID\": \"$ListID_2\",\n \"Action\": \"addforce\"\n }\n ]\n}\nresult = mailjet.contact_managecontactslists.create(id=id, data=data)\nprint result.status_code\nprint result.json()\n```\n\n### GET Request\n\n#### Retrieve all objects\n\n```python\n\"\"\"\nRetrieve all contacts:\n\"\"\"\nfrom mailjet_rest import Client\nimport os\napi_key = os.environ['MJ_APIKEY_PUBLIC']\napi_secret = os.environ['MJ_APIKEY_PRIVATE']\nmailjet = Client(auth=(api_key, api_secret))\nresult = mailjet.contact.get()\nprint result.status_code\nprint result.json()\n```\n\n#### Using filtering\n\n```python\n\"\"\"\nRetrieve all contacts that are not in the campaign exclusion list:\n\"\"\"\nfrom mailjet_rest import Client\nimport os\napi_key = os.environ['MJ_APIKEY_PUBLIC']\napi_secret = os.environ['MJ_APIKEY_PRIVATE']\nmailjet = Client(auth=(api_key, api_secret))\nfilters = {\n 'IsExcludedFromCampaigns': false,\n}\nresult = mailjet.contact.get(filters=filters)\nprint result.status_code\nprint result.json()\n```\n\n#### Retrieve a single object\n\n```python\n\"\"\"\nRetrieve a specific contact ID:\n\"\"\"\nfrom mailjet_rest import Client\nimport os\napi_key = os.environ['MJ_APIKEY_PUBLIC']\napi_secret = os.environ['MJ_APIKEY_PRIVATE']\nmailjet = Client(auth=(api_key, api_secret))\nid = 'Contact_ID'\nresult = mailjet.contact.get(id=id)\nprint result.status_code\nprint result.json()\n```\n\n### PUT request\n\nA `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.\n\nHere's an example of a `PUT` request:\n\n```python\n\"\"\"\nUpdate the contact properties for a contact:\n\"\"\"\nfrom mailjet_rest import Client\nimport os\napi_key = os.environ['MJ_APIKEY_PUBLIC']\napi_secret = os.environ['MJ_APIKEY_PRIVATE']\nmailjet = Client(auth=(api_key, api_secret))\nid = '$CONTACT_ID'\ndata = {\n 'Data': [\n {\n \"Name\": \"first_name\",\n \"value\": \"John\"\n },\n {\n \"Name\": \"last_name\",\n \"value\": \"Smith\"\n }\n ]\n}\nresult = mailjet.contactdata.update(id=id, data=data)\nprint result.status_code\nprint result.json()\n```\n\n### DELETE request\n\nUpon a successful `DELETE` request the response will not include a response body, but only a `204 No Content` response code.\n\nHere's an example of a `DELETE` request:\n\n```python\n\"\"\"\nDelete an email template:\n\"\"\"\nfrom mailjet_rest import Client\nimport os\napi_key = os.environ['MJ_APIKEY_PUBLIC']\napi_secret = os.environ['MJ_APIKEY_PRIVATE']\nmailjet = Client(auth=(api_key, api_secret))\nid = 'Template_ID'\nresult = mailjet.template.delete(id=id)\nprint result.status_code\nprint result.json()\n```\n\n## Contribute\n\nMailjet loves developers. You can be part of this project!\n\nThis wrapper is a great introduction to the open source world, check out the code!\n\nFeel free to ask anything, and contribute:\n\n- Fork the project.\n- Create a new branch.\n- Implement your feature or bug fix.\n- Add documentation to it.\n- Commit, push, open a pull request and voila.\n\nIf you have suggestions on how to improve the guides, please submit an issue in our [Official API Documentation repo](https://github.com/mailjet/api-documentation).\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Mailjet V3 API wrapper",
"version": "1.3.4",
"project_urls": {
"Download": "https://github.com/mailjet/mailjet-apiv3-python/releases/latest",
"Homepage": "https://github.com/mailjet/mailjet-apiv3-python"
},
"split_keywords": [
"mailjet",
"api",
"v3",
"/",
"v3.1",
"python",
"wrapper"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7d818340d01990d888e4a8af2a07dcc335475119b211abf7c773de387a7b7efe",
"md5": "54c41511dac1c727570ffb856518e168",
"sha256": "635d53ac3fd61020f309c24ee977ae3458654ab39f9c36fc4b50c74e5d8ad410"
},
"downloads": -1,
"filename": "mailjet_rest-1.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "54c41511dac1c727570ffb856518e168",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7525,
"upload_time": "2020-10-20T15:22:33",
"upload_time_iso_8601": "2020-10-20T15:22:33.951004Z",
"url": "https://files.pythonhosted.org/packages/7d/81/8340d01990d888e4a8af2a07dcc335475119b211abf7c773de387a7b7efe/mailjet_rest-1.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ad68e72ee94650da7cfd902bfdde3f019a5ae9b86dc31ba58c806055fa12e537",
"md5": "65594b8c80d6440a10eb877bcad468b3",
"sha256": "e02663fa0369543bcd48c37a146e8143bb12b9f3512af2d5ba6dfbcc99e64a2d"
},
"downloads": -1,
"filename": "mailjet_rest-1.3.4.tar.gz",
"has_sig": false,
"md5_digest": "65594b8c80d6440a10eb877bcad468b3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6761,
"upload_time": "2020-10-20T15:22:35",
"upload_time_iso_8601": "2020-10-20T15:22:35.899108Z",
"url": "https://files.pythonhosted.org/packages/ad/68/e72ee94650da7cfd902bfdde3f019a5ae9b86dc31ba58c806055fa12e537/mailjet_rest-1.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-10-20 15:22:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mailjet",
"github_project": "mailjet-apiv3-python",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"lcname": "mailjet-rest"
}
JSON
