Skip to content

Commit 153743d

Browse files
author
Atanas Damyanliev
authored
Merge pull request #42 from mailjet/readme_revamp
new readme version with standartized content
2 parents 54b8bd4 + a5e3542 commit 153743d

File tree

1 file changed

+241
-52
lines changed

1 file changed

+241
-52
lines changed

‎README.md‎

Lines changed: 241 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,125 @@
1+
2+
[mailjet]:(http://www.mailjet.com/)
13
[api_credential]: https://app.mailjet.com/account/api_keys
24
[doc]: http://dev.mailjet.com/guides/?python#
35
[api_doc]: https://github.com/mailjet/api-documentation
4-
[smsDashboard]: https://app.mailjet.com/sms?_ga=2.81581655.1972348350.1522654521-1279766791.1506937572
5-
[smsInfo]: https://app.mailjet.com/docs/transactional-sms?_ga=2.183303910.1972348350.1522654521-1279766791.1506937572#trans-sms-token
66

77
![alt text](https://www.mailjet.com/images/email/transac/logo_header.png "Mailjet")
88

99
# Official Mailjet Python Wrapper
1010

1111
[![Build Status](https://travis-ci.org/mailjet/mailjet-apiv3-python.svg?branch=master)](https://travis-ci.org/mailjet/mailjet-apiv3-python)
12+
![Current Version](https://img.shields.io/badge/version-1.3.2-green.svg)
13+
14+
## Overview
15+
16+
Welcome to the [Mailjet][mailjet] official Python API wrapper!
17+
18+
Check out all the resources and Python code examples in the official [Mailjet Documentation][doc].
1219

13-
### API documentation
20+
## Table of contents
1421

15-
All code examples can be found on the [Mailjet Documentation][doc].
22+
- [Compatibility](#compatibility)
23+
- [Installation](#installation)
24+
- [Authentication](#authentication)
25+
- [Make your first call](#make-your-first-call)
26+
- [Client / Call configuration specifics](#client--call-configuration-specifics)
27+
- [API versioning](#api-versioning)
28+
- [Base URL](#base-url)
29+
- [Request examples](#request-examples)
30+
- [POST request](#post-request)
31+
- [Simple POST request](#simple-post-request)
32+
- [Using actions](#using-actions)
33+
- [GET request](#get-request)
34+
- [Retrieve all objects](#retrieve-all-objects)
35+
- [Use filtering](#use-filtering)
36+
- [Retrieve a single object](#retrieve-a-single-object)
37+
- [PUT request](#put-request)
38+
- [DELETE request](#delete-request)
39+
- [Contribute](#contribute)
1640

17-
(Please refer to the [Mailjet Documentation Repository][api_doc] to contribute to the documentation examples)
41+
## Compatibility
42+
43+
This library officially supports the following Node.js versions:
44+
45+
- v2.7
46+
- v3.5
47+
- v3.6
1848

1949
## Installation
2050

51+
Use the below code to install the wrapper:
52+
2153
``` bash
2254
(sudo) pip install mailjet_rest
2355
```
2456

25-
## Getting Started
57+
## Authentication
2658

27-
Grab your API and Secret Keys [here][api_credential]. You need them for authentication when using the Email API:
59+
The Mailjet Email API uses your API and Secret keys for authentication. [Grab][api_credential] and save your Mailjet API credentials.
2860

2961
```bash
3062
export MJ_APIKEY_PUBLIC='your api key'
3163
export MJ_APIKEY_PRIVATE='your api secret'
3264
```
3365

34-
## API Versioning
66+
Initialize your [Mailjet][mailjet] client:
67+
68+
```python
69+
# import the mailjet wrapper
70+
from mailjet_rest import Client
71+
import os
72+
73+
# Get your environment Mailjet keys
74+
API_KEY = os.environ['MJ_APIKEY_PUBLIC']
75+
API_SECRET = os.environ['MJ_APIKEY_PRIVATE']
76+
77+
mailjet = Client(auth=(API_KEY, API_SECRET))
78+
```
79+
80+
## Make your first call
81+
82+
Here's an example on how to send an email:
83+
84+
```python
85+
from mailjet_rest import Client
86+
import os
87+
api_key = os.environ['MJ_APIKEY_PUBLIC']
88+
api_secret = os.environ['MJ_APIKEY_PRIVATE']
89+
mailjet = Client(auth=(api_key, api_secret), version='v3.1')
90+
data = {
91+
'Messages': [
92+
{
93+
"From": {
94+
"Email": "$SENDER_EMAIL",
95+
"Name": "Me"
96+
},
97+
"To": [
98+
{
99+
"Email": "$RECIPIENT_EMAIL",
100+
"Name": "You"
101+
}
102+
],
103+
"Subject": "My first Mailjet Email!",
104+
"TextPart": "Greetings from Mailjet!",
105+
"HTMLPart": "<h3>Dear passenger 1, welcome to <a href=\"https://www.mailjet.com/\">Mailjet</a>!</h3><br />May the delivery force be with you!"
106+
}
107+
]
108+
}
109+
result = mailjet.send.create(data=data)
110+
print result.status_code
111+
print result.json()
112+
```
113+
114+
## Client / Call Configuration Specifics
115+
116+
### API Versioning
35117

36118
The Mailjet API is spread among three distinct versions:
37119

38120
- `v3` - The Email API
39121
- `v3.1` - Email Send API v3.1, which is the latest version of our Send API
40-
- `v4` - SMS API
122+
- `v4` - SMS API (not supported in Python)
41123

42124
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`:
43125

@@ -51,7 +133,6 @@ API_KEY = os.environ['MJ_APIKEY_PUBLIC']
51133
API_SECRET = os.environ['MJ_APIKEY_PRIVATE']
52134

53135
mailjet = Client(auth=(API_KEY, API_SECRET), version='v3.1')
54-
55136
```
56137

57138
For additional information refer to our [API Reference](https://dev.preprod.mailjet.com/reference/overview/versioning/).
@@ -66,70 +147,178 @@ mailjet = Client(auth=(api_key, api_secret),api_url="https://api.us.mailjet.com/
66147

67148
If your account has been moved to Mailjet's **US architecture**, the URL value you need to set is `https://api.us.mailjet.com`.
68149

69-
## Make a `GET` request:
70-
``` python
71-
# get all contacts
72-
result = mailjet.contact.get()
150+
## Request examples
151+
152+
### POST request
153+
154+
#### Simple POST request
155+
156+
```python
157+
"""
158+
Create a new contact:
159+
"""
160+
from mailjet_rest import Client
161+
import os
162+
api_key = os.environ['MJ_APIKEY_PUBLIC']
163+
api_secret = os.environ['MJ_APIKEY_PRIVATE']
164+
mailjet = Client(auth=(api_key, api_secret))
165+
data = {
166+
'Email': '[email protected]'
167+
}
168+
result = mailjet.contact.create(data=data)
169+
print result.status_code
170+
print result.json()
73171
```
74172

75-
## `GET` request with filters:
76-
``` python
77-
# get the first 2 contacts
78-
result = mailjet.contact.get(filters={'limit': 2})
173+
#### Using actions
174+
175+
```python
176+
"""
177+
Manage the subscription status of a contact to multiple lists:
178+
"""
179+
from mailjet_rest import Client
180+
import os
181+
api_key = os.environ['MJ_APIKEY_PUBLIC']
182+
api_secret = os.environ['MJ_APIKEY_PRIVATE']
183+
mailjet = Client(auth=(api_key, api_secret))
184+
id = '$ID'
185+
data = {
186+
'ContactsLists': [
187+
{
188+
"ListID": "$ListID_1",
189+
"Action": "addnoforce"
190+
},
191+
{
192+
"ListID": "$ListID_2",
193+
"Action": "addforce"
194+
}
195+
]
196+
}
197+
result = mailjet.contact_managecontactslists.create(id=id, data=data)
198+
print result.status_code
199+
print result.json()
79200
```
80-
## `POST` request
81-
``` python
82-
# Register a new sender email address
83-
result = mailjet.sender.create(data={'email': '[email protected]'})
201+
202+
### GET Request
203+
204+
#### Retrieve all objects
205+
206+
```python
207+
"""
208+
Retrieve all contacts:
209+
"""
210+
from mailjet_rest import Client
211+
import os
212+
api_key = os.environ['MJ_APIKEY_PUBLIC']
213+
api_secret = os.environ['MJ_APIKEY_PRIVATE']
214+
mailjet = Client(auth=(api_key, api_secret))
215+
result = mailjet.contact.get()
216+
print result.status_code
217+
print result.json()
84218
```
85219

86-
## Combine a resource with an action
87-
``` python
88-
# Get the contacts lists of contact #2
89-
result = mailjet.contact_getcontactslists.get(id=2)
220+
#### Using filtering
221+
222+
```python
223+
"""
224+
Retrieve all contacts that are not in the campaign exclusion list:
225+
"""
226+
from mailjet_rest import Client
227+
import os
228+
api_key = os.environ['MJ_APIKEY_PUBLIC']
229+
api_secret = os.environ['MJ_APIKEY_PRIVATE']
230+
mailjet = Client(auth=(api_key, api_secret))
231+
filters = {
232+
'IsExcludedFromCampaigns': false,
233+
}
234+
result = mailjet.contact.get(filters=filters)
235+
print result.status_code
236+
print result.json()
90237
```
91238

92-
## Send an Email
93-
``` python
239+
#### Retrieve a single object
94240

241+
```python
242+
"""
243+
Retrieve a specific contact ID:
244+
"""
95245
from mailjet_rest import Client
96246
import os
97247
api_key = os.environ['MJ_APIKEY_PUBLIC']
98248
api_secret = os.environ['MJ_APIKEY_PRIVATE']
99-
mailjet = Client(auth=(api_key, api_secret), version='v3.1')
249+
mailjet = Client(auth=(api_key, api_secret))
250+
id = 'Contact_ID'
251+
result = mailjet.contact.get(id=id)
252+
print result.status_code
253+
print result.json()
254+
```
255+
256+
### PUT request
257+
258+
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.
259+
260+
Here's an example of a `PUT` request:
261+
262+
```python
263+
"""
264+
Update the contact properties for a contact:
265+
"""
266+
from mailjet_rest import Client
267+
import os
268+
api_key = os.environ['MJ_APIKEY_PUBLIC']
269+
api_secret = os.environ['MJ_APIKEY_PRIVATE']
270+
mailjet = Client(auth=(api_key, api_secret))
271+
id = '$CONTACT_ID'
100272
data = {
101-
'Messages': [
273+
'Data': [
274+
{
275+
"Name": "first_name",
276+
"value": "John"
277+
},
102278
{
103-
"From": {
104-
"Email": "[email protected]",
105-
"Name": "Mailjet Pilot"
106-
},
107-
"To": [
108-
{
109-
"Email": "[email protected]",
110-
"Name": "passenger 1"
111-
}
112-
],
113-
"Subject": "Your email flight plan!",
114-
"TextPart": "Dear passenger 1, welcome to Mailjet! May the delivery force be with you!",
115-
"HTMLPart": "<h3>Dear passenger 1, welcome to Mailjet!</h3><br />May the delivery force be with you!"
279+
"Name": "last_name",
280+
"value": "Smith"
116281
}
117282
]
118283
}
119-
result = mailjet.send.create(data=data)
284+
result = mailjet.contactdata.update(id=id, data=data)
120285
print result.status_code
121286
print result.json()
122-
123287
```
124288

125-
You can also use the previous version of Mailjet's Send API (v3). You can find the documentation explaining the overall differences and code samples [here](https://dev.mailjet.com/guides/?python#sending-a-basic-email-v3).
289+
### DELETE request
126290

127-
## Create a new Contact
128-
``` python
291+
Upon a successful `DELETE` request the response will not include a response body, but only a `204 No Content` response code.
129292

130-
# wrapping the call inside a function
131-
def new_contact(email):
132-
return mailjet.contact.create(data={'Email': email})
293+
Here's an example of a `DELETE` request:
133294

134-
new_contact('[email protected]')
295+
```python
296+
"""
297+
Delete an email template:
298+
"""
299+
from mailjet_rest import Client
300+
import os
301+
api_key = os.environ['MJ_APIKEY_PUBLIC']
302+
api_secret = os.environ['MJ_APIKEY_PRIVATE']
303+
mailjet = Client(auth=(api_key, api_secret))
304+
id = 'Template_ID'
305+
result = mailjet.template.delete(id=id)
306+
print result.status_code
307+
print result.json()
135308
```
309+
310+
## Contribute
311+
312+
Mailjet loves developers. You can be part of this project!
313+
314+
This wrapper is a great introduction to the open source world, check out the code!
315+
316+
Feel free to ask anything, and contribute:
317+
318+
- Fork the project.
319+
- Create a new branch.
320+
- Implement your feature or bug fix.
321+
- Add documentation to it.
322+
- Commit, push, open a pull request and voila.
323+
324+
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).

0 commit comments

Comments
 (0)