Skip to content

Commit 5687edc

Browse files
author
adamyanliev
committed
readme revamp draft
1 parent 54b8bd4 commit 5687edc

File tree

1 file changed

+240
-52
lines changed

1 file changed

+240
-52
lines changed

‎README.md‎

Lines changed: 240 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,124 @@
1+
[mailjet](http://www.mailjet.com/)
12
[api_credential]: https://app.mailjet.com/account/api_keys
23
[doc]: http://dev.mailjet.com/guides/?python#
34
[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
65

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

98
# Official Mailjet Python Wrapper
109

1110
[![Build Status](https://travis-ci.org/mailjet/mailjet-apiv3-python.svg?branch=master)](https://travis-ci.org/mailjet/mailjet-apiv3-python)
11+
![Current Version](https://img.shields.io/badge/version-1.3.2-green.svg)
1212

13-
### API documentation
13+
## Overview
1414

15-
All code examples can be found on the [Mailjet Documentation][doc].
15+
Welcome to the [Mailjet][mailjet] official Python API wrapper!
1616

17-
(Please refer to the [Mailjet Documentation Repository][api_doc] to contribute to the documentation examples)
17+
Check out all the resources and Python code examples in the official [Mailjet Documentation][doc].
18+
19+
## Table of contents
20+
21+
- [Compatibility](#compatibility)
22+
- [Installation](#installation)
23+
- [Authentication](#authentication)
24+
- [Make your first call](#make-your-first-call)
25+
- [Client / Call configuration specifics](#client--call-configuration-specifics)
26+
- [API versioning](#api-versioning)
27+
- [Base URL](#base-url)
28+
- [Request examples](#request-examples)
29+
- [POST request](#post-request)
30+
- [Simple POST request](#simple-post-request)
31+
- [Using actions](#using-actions)
32+
- [GET request](#get-request)
33+
- [Retrieve all objects](#retrieve-all-objects)
34+
- [Use filtering](#use-filtering)
35+
- [Retrieve a single object](#retrieve-a-single-object)
36+
- [PUT request](#put-request)
37+
- [DELETE request](#delete-request)
38+
- [Contribute](#contribute)
39+
40+
## Compatibility
41+
42+
This library officially supports the following Node.js versions:
43+
44+
- v2.7
45+
- v3.5
46+
- v3.6
1847

1948
## Installation
2049

50+
Use the below code to install the wrapper:
51+
2152
``` bash
2253
(sudo) pip install mailjet_rest
2354
```
2455

25-
## Getting Started
56+
## Authentication
2657

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

2960
```bash
3061
export MJ_APIKEY_PUBLIC='your api key'
3162
export MJ_APIKEY_PRIVATE='your api secret'
3263
```
3364

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

36117
The Mailjet API is spread among three distinct versions:
37118

38119
- `v3` - The Email API
39120
- `v3.1` - Email Send API v3.1, which is the latest version of our Send API
40-
- `v4` - SMS API
121+
- `v4` - SMS API (not supported in Python)
41122

42123
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`:
43124

@@ -51,7 +132,6 @@ API_KEY = os.environ['MJ_APIKEY_PUBLIC']
51132
API_SECRET = os.environ['MJ_APIKEY_PRIVATE']
52133

53134
mailjet = Client(auth=(API_KEY, API_SECRET), version='v3.1')
54-
55135
```
56136

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

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

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

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

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)
219+
#### Using filtering
220+
221+
```python
222+
"""
223+
Retrieve all contacts that are not in the campaign exclusion list:
224+
"""
225+
from mailjet_rest import Client
226+
import os
227+
api_key = os.environ['MJ_APIKEY_PUBLIC']
228+
api_secret = os.environ['MJ_APIKEY_PRIVATE']
229+
mailjet = Client(auth=(api_key, api_secret))
230+
filters = {
231+
'IsExcludedFromCampaigns': false,
232+
}
233+
result = mailjet.contact.get(filters=filters)
234+
print result.status_code
235+
print result.json()
90236
```
91237

92-
## Send an Email
93-
``` python
238+
#### Retrieve a single object
94239

240+
```python
241+
"""
242+
Retrieve a specific contact ID:
243+
"""
95244
from mailjet_rest import Client
96245
import os
97246
api_key = os.environ['MJ_APIKEY_PUBLIC']
98247
api_secret = os.environ['MJ_APIKEY_PRIVATE']
99-
mailjet = Client(auth=(api_key, api_secret), version='v3.1')
248+
mailjet = Client(auth=(api_key, api_secret))
249+
id = 'Contact_ID'
250+
result = mailjet.contact.get(id=id)
251+
print result.status_code
252+
print result.json()
253+
```
254+
255+
### PUT request
256+
257+
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.
258+
259+
Here's an example of a `PUT` request:
260+
261+
```python
262+
"""
263+
Update the contact properties for a contact:
264+
"""
265+
from mailjet_rest import Client
266+
import os
267+
api_key = os.environ['MJ_APIKEY_PUBLIC']
268+
api_secret = os.environ['MJ_APIKEY_PRIVATE']
269+
mailjet = Client(auth=(api_key, api_secret))
270+
id = '$CONTACT_ID'
100271
data = {
101-
'Messages': [
272+
'Data': [
273+
{
274+
"Name": "first_name",
275+
"value": "John"
276+
},
102277
{
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!"
278+
"Name": "last_name",
279+
"value": "Smith"
116280
}
117281
]
118282
}
119-
result = mailjet.send.create(data=data)
283+
result = mailjet.contactdata.update(id=id, data=data)
120284
print result.status_code
121285
print result.json()
122-
123286
```
124287

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).
288+
### DELETE request
126289

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

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

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