mailjet 1.5.4 → 1.8.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +5 -5
- data/README.md +298 -183
- data/Rakefile +23 -14
- data/lib/mailjet/configuration.rb +56 -4
- data/lib/mailjet/connection.rb +68 -33
- data/lib/mailjet/exception/errors.rb +94 -0
- data/lib/mailjet/mailer.rb +45 -16
- data/lib/mailjet/rack/endpoint.rb +2 -3
- data/lib/mailjet/resource.rb +105 -72
- data/lib/mailjet/resources/campaigndraft.rb +1 -1
- data/lib/mailjet/resources/campaigndraft_detailcontent.rb +17 -1
- data/lib/mailjet/resources/campaigndraft_schedule.rb +1 -1
- data/lib/mailjet/resources/campaigndraft_send.rb +1 -1
- data/lib/mailjet/resources/campaigndraft_status.rb +1 -1
- data/lib/mailjet/resources/campaigndraft_test.rb +1 -1
- data/lib/mailjet/resources/contact.rb +11 -2
- data/lib/mailjet/resources/contact_getcontactslists.rb +17 -0
- data/lib/mailjet/resources/contact_pii.rb +8 -0
- data/lib/mailjet/resources/contactslist_csv.rb +8 -0
- data/lib/mailjet/resources/csvimport.rb +0 -1
- data/lib/mailjet/resources/listrecipient.rb +2 -1
- data/lib/mailjet/resources/messagehistory.rb +16 -0
- data/lib/mailjet/resources/messageinformation.rb +17 -0
- data/lib/mailjet/resources/newsletter.rb +1 -2
- data/lib/mailjet/resources/openinformation.rb +17 -0
- data/lib/mailjet/resources/retrieve_errors_csv.rb +8 -0
- data/lib/mailjet/resources/send.rb +1 -1
- data/lib/mailjet/resources/statcounters.rb +33 -0
- data/lib/mailjet/resources/statistics_linkclick.rb +12 -0
- data/lib/mailjet/resources/template_detailcontent.rb +18 -2
- data/lib/mailjet/version.rb +1 -1
- data/lib/mailjet.rb +4 -6
- metadata +25 -120
- data/lib/mailjet/api_error.rb +0 -29
- data/lib/mailjet/core_extensions/ostruct.rb +0 -9
- data/lib/mailjet/gem_extensions/rest_client.rb +0 -19
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
|
-
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
2
|
+
SHA256:
|
3
|
+
metadata.gz: c9c74309f3d5e557d27fe01548e0998a987c90a9bd1e5e52c187c23d33fb5475
|
4
|
+
data.tar.gz: 3c44b00a89c535c6143d0011fa6e11ca1d6bcdbc82ed984eea4b5f23b0483b89
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: a35a75e7a661f72c28fda90a8403f363252f36cf9573786e512f1721b807b6f450d51dafdc6d8ae8c816b4bd0f32b4abe008f67b6189647a0caa70f0ebbc929d
|
7
|
+
data.tar.gz: 513f1178e1f7e625b177faa7220d60fbb4208a5d38f91642d173ee7a63d39fa3758d189f04e9a4a3e928d84e8d4921a17c22d281bb9fca2b8cf47c7f9f7348ca
|
data/README.md
CHANGED
@@ -1,6 +1,6 @@
|
|
1
|
-
|
1
|
+
![alt text](https://www.mailjet.com/images/email/transac/logo_header.png "Mailjet")
|
2
2
|
|
3
|
-
|
3
|
+
# Official Mailjet Ruby wrapper
|
4
4
|
|
5
5
|
[![Build Status](https://travis-ci.org/mailjet/mailjet-gem.svg?branch=master)](https://travis-ci.org/mailjet/mailjet-gem)
|
6
6
|
|
@@ -35,30 +35,55 @@
|
|
35
35
|
<!-- You can read this readme file in other languages:
|
36
36
|
english | [french](./README.fr.md) -->
|
37
37
|
|
38
|
-
|
38
|
+
## Overview
|
39
39
|
|
40
|
-
|
41
|
-
* Manage your lists, contacts and campaigns, and much more...
|
42
|
-
* Track email delivery through event API
|
40
|
+
This repository contains the official Ruby wrapper for the Mailjet API, bootstraped with [Mailjetter][mailjetter].
|
43
41
|
|
44
|
-
|
42
|
+
Check out all the resources and Ruby code examples in the [Offical Documentation](https://dev.mailjet.com/guides/?ruby#getting-started).
|
45
43
|
|
46
|
-
- Ruby 2.2.X
|
47
44
|
|
48
|
-
|
45
|
+
## Table of contents
|
49
46
|
|
50
|
-
|
47
|
+
- [Compatibility](#compatibility)
|
48
|
+
- [Installation](#installation)
|
49
|
+
- [Rubygems](#rubygems)
|
50
|
+
- [Bundler](#bundler)
|
51
|
+
- [Authentication](#authentication)
|
52
|
+
- [Make your first call](#make-your-first-call)
|
53
|
+
- [Call configuration specifics](#call-configuration-specifics)
|
54
|
+
- [API versioning](#api-versioning)
|
55
|
+
- [Base URL](#base-url)
|
56
|
+
- [List of resources](#list-of-resources)
|
57
|
+
- [Naming conventions](#naming-conventions)
|
58
|
+
- [Request examples](#request-examples)
|
59
|
+
- [POST request](#post-request)
|
60
|
+
- [Simple POST request](#simple-post-request)
|
61
|
+
- [Using actions](#using-actions)
|
62
|
+
- [GET request](#get-request)
|
63
|
+
- [Retrieve all objects](#retrieve-all-objects)
|
64
|
+
- [Use filtering](#use-filtering)
|
65
|
+
- [Retrieve a single object](#retrieve-a-single-object)
|
66
|
+
- [Retrieve the count of objects matching the query](retrieve-the-count-of-objects-matching-the-query)
|
67
|
+
- [Retrieve the first object matching the query](retrieve-the-first-object-matching-the-query)
|
68
|
+
- [PUT request](#put-request)
|
69
|
+
- [DELETE request](#delete-request)
|
70
|
+
- [Send emails with ActionMailer](#send-emails-with-actionmailer)
|
71
|
+
- [Track email delivery](#track-email-delivery)
|
72
|
+
- [Testing](#testing)
|
73
|
+
- [Contribute](#contribute)
|
51
74
|
|
52
|
-
|
75
|
+
## Compatibility
|
53
76
|
|
54
|
-
|
77
|
+
This library requires **Ruby v2.2.X**.
|
55
78
|
|
79
|
+
The Rails ActionMailer integration is designed for Rails >= 5.
|
56
80
|
|
57
|
-
|
58
|
-
## Install
|
81
|
+
## Installation
|
59
82
|
|
60
83
|
### Rubygems
|
61
84
|
|
85
|
+
Use the below command to install the wrapper.
|
86
|
+
|
62
87
|
```bash
|
63
88
|
$ gem install mailjet
|
64
89
|
```
|
@@ -72,25 +97,22 @@ Add the following in your Gemfile:
|
|
72
97
|
gem 'mailjet'
|
73
98
|
```
|
74
99
|
|
75
|
-
If you wish to use the most
|
100
|
+
If you wish to use the most recent release from Github, add the following in your Gemfile instead:
|
76
101
|
|
77
102
|
```ruby
|
78
103
|
#Gemfile
|
79
104
|
gem 'mailjet', :git => 'https://github.com/mailjet/mailjet-gem.git'
|
80
105
|
```
|
81
|
-
|
106
|
+
|
107
|
+
Then let the bundler magic happen:
|
82
108
|
|
83
109
|
```bash
|
84
110
|
$ bundle install
|
85
111
|
```
|
86
112
|
|
87
|
-
##
|
113
|
+
## Authentication
|
88
114
|
|
89
|
-
|
90
|
-
|
91
|
-
You need a proper account with [Mailjet][mailjet]. You can get the API key through the [Mailjet][mailjet] interface in _Account/Master API key_
|
92
|
-
|
93
|
-
Add the keys to an initializer:
|
115
|
+
The Mailjet Email API uses your API and Secret keys for authentication. [Grab](https://app.mailjet.com/account/api_keys) and save your Mailjet API credentials by adding them to an initializer:
|
94
116
|
|
95
117
|
```ruby
|
96
118
|
# initializers/mailjet.rb
|
@@ -101,7 +123,7 @@ Mailjet.configure do |config|
|
|
101
123
|
end
|
102
124
|
```
|
103
125
|
|
104
|
-
`default_from` is optional if you send emails with `:mailjet`'s SMTP
|
126
|
+
`default_from` is optional if you send emails with [`:mailjet`'s SMTP](https://github.com/mailjet/mailjet-gem#send-emails-with-actionmailer).
|
105
127
|
|
106
128
|
But if you are using Mailjet with Rails, you can simply generate it:
|
107
129
|
|
@@ -109,28 +131,219 @@ But if you are using Mailjet with Rails, you can simply generate it:
|
|
109
131
|
$ rails generate mailjet:initializer
|
110
132
|
```
|
111
133
|
|
134
|
+
## Make your first call
|
135
|
+
|
136
|
+
Here's an example on how to send an email:
|
137
|
+
|
138
|
+
```ruby
|
139
|
+
require 'mailjet'
|
140
|
+
Mailjet.configure do |config|
|
141
|
+
config.api_key = ENV['MJ_APIKEY_PUBLIC']
|
142
|
+
config.secret_key = ENV['MJ_APIKEY_PRIVATE']
|
143
|
+
config.api_version = "v3.1"
|
144
|
+
end
|
145
|
+
variable = Mailjet::Send.create(messages: [{
|
146
|
+
'From'=> {
|
147
|
+
'Email'=> '$SENDER_EMAIL',
|
148
|
+
'Name'=> 'Me'
|
149
|
+
},
|
150
|
+
'To'=> [
|
151
|
+
{
|
152
|
+
'Email'=> '$RECIPIENT_EMAIL',
|
153
|
+
'Name'=> 'You'
|
154
|
+
}
|
155
|
+
],
|
156
|
+
'Subject'=> 'My first Mailjet Email!',
|
157
|
+
'TextPart'=> 'Greetings from Mailjet!',
|
158
|
+
'HTMLPart'=> '<h3>Dear passenger 1, welcome to <a href=\'https://www.mailjet.com/\'>Mailjet</a>!</h3><br />May the delivery force be with you!'
|
159
|
+
}]
|
160
|
+
)
|
161
|
+
p variable.attributes[:messages]
|
162
|
+
```
|
163
|
+
|
164
|
+
## Call Configuration Specifics
|
165
|
+
|
166
|
+
### API Versioning
|
167
|
+
|
168
|
+
The Mailjet API is spread among three distinct versions:
|
169
|
+
|
170
|
+
- `v3` - The Email API
|
171
|
+
- `v3.1` - Email Send API v3.1, which is the latest version of our Send API
|
172
|
+
- `v4` - SMS API (not supported in this library yet)
|
173
|
+
|
174
|
+
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 `api_version`. For example, if using Send API `v3.1`:
|
175
|
+
|
176
|
+
```ruby
|
177
|
+
require 'mailjet'
|
178
|
+
Mailjet.configure do |config|
|
179
|
+
config.api_key = ENV['MJ_APIKEY_PUBLIC']
|
180
|
+
config.secret_key = ENV['MJ_APIKEY_PRIVATE']
|
181
|
+
config.api_version = "v3.1"
|
182
|
+
end
|
183
|
+
```
|
184
|
+
|
185
|
+
### Base URL
|
186
|
+
|
187
|
+
The default base domain name for the Mailjet API is `https://api.mailjet.com`. You can modify this base URL by setting a value for `end_point` in your call:
|
188
|
+
|
189
|
+
```ruby
|
190
|
+
Mailjet.configure do |config|
|
191
|
+
config.api_key = ENV['MJ_APIKEY_PUBLIC']
|
192
|
+
config.secret_key = ENV['MJ_APIKEY_PRIVATE']
|
193
|
+
config.api_version = "v3.1"
|
194
|
+
config.end_point = "https://api.us.mailjet.com"
|
195
|
+
end
|
196
|
+
```
|
197
|
+
|
198
|
+
If your account has been moved to Mailjet's **US architecture**, the URL value you need to set is `https://api.us.mailjet.com`.
|
199
|
+
|
200
|
+
## List of resources
|
201
|
+
|
202
|
+
You can find the list of all available resources for this library, as well as their configuration, in [/lib/mailjet/resources](https://github.com/mailjet/mailjet-gem/tree/master/lib/mailjet/resources).
|
203
|
+
|
204
|
+
### Naming conventions
|
205
|
+
|
206
|
+
- Class names' first letter is capitalized followed by the rest of the resource name in lowercase (e.g. `listrecipient` will be `Listrecipient` in ruby)
|
207
|
+
- Ruby attribute names are the underscored versions of API attributes names (e.g. `IsActive` will be `is_active` in ruby)
|
208
|
+
|
209
|
+
## Request examples
|
210
|
+
|
211
|
+
### POST Request
|
212
|
+
|
213
|
+
Use the `create` method of the Mailjet CLient (i.e. `variable = Mailjet::$resource.create($params)`).
|
214
|
+
|
215
|
+
`$params` will be a list of properties used in the request payload.
|
216
|
+
|
217
|
+
#### Simple POST request
|
218
|
+
|
219
|
+
```ruby
|
220
|
+
# Create a new contact:
|
221
|
+
require 'mailjet'
|
222
|
+
Mailjet.configure do |config|
|
223
|
+
config.api_key = ENV['MJ_APIKEY_PUBLIC']
|
224
|
+
config.secret_key = ENV['MJ_APIKEY_PRIVATE']
|
225
|
+
end
|
226
|
+
variable = Mailjet::Contact.create(email: "Mister@mailjet.com"
|
227
|
+
)
|
228
|
+
p variable.attributes['Data']
|
229
|
+
```
|
230
|
+
|
231
|
+
#### Using actions
|
232
|
+
|
233
|
+
Some APIs allow the use of action endpoints. To use them in this wrapper, the API endpoint is in the beginning, followed by an underscore, followed by the action you are performing - e.g. `Contact_managecontactslists`.
|
234
|
+
|
235
|
+
Use `id` to specify the ID you want to apply a POST request to (used in case of action on a resource).
|
236
|
+
|
237
|
+
```ruby
|
238
|
+
# Manage the subscription status of a contact to multiple lists
|
239
|
+
require 'mailjet'
|
240
|
+
Mailjet.configure do |config|
|
241
|
+
config.api_key = ENV['MJ_APIKEY_PUBLIC']
|
242
|
+
config.secret_key = ENV['MJ_APIKEY_PRIVATE']
|
243
|
+
end
|
244
|
+
variable = Mailjet::Contact_managecontactslists.create(id: $ID, contacts_lists: [{
|
245
|
+
'ListID'=> '$ListID_1',
|
246
|
+
'Action'=> 'addnoforce'
|
247
|
+
}, {
|
248
|
+
'ListID'=> '$ListID_2',
|
249
|
+
'Action'=> 'addforce'
|
250
|
+
}]
|
251
|
+
)
|
252
|
+
p variable.attributes['Data']
|
253
|
+
```
|
254
|
+
|
255
|
+
### GET request
|
256
|
+
|
257
|
+
#### Retrieve all objects
|
258
|
+
|
259
|
+
Use the `.all` method of the Mailjet CLient (i.e. `Mailjet::$resource.all()`) to retrieve all objects you are looking for. By default, `.all` will retrieve only 10 objects - you have to specify `limit: 0` if you want to GET them all (up to 1000 objects).
|
260
|
+
|
261
|
+
```ruby
|
262
|
+
> recipients = Mailjet::Listrecipient.all(limit: 0)
|
263
|
+
```
|
264
|
+
|
265
|
+
#### Use filtering
|
266
|
+
|
267
|
+
You can refine queries using API filters, as well as the following parameters:
|
268
|
+
|
269
|
+
- `format`: `:json`, `:xml`, `:rawxml`, `:html`, `:csv` or `:phpserialized` (default: `:json`)
|
270
|
+
- `limit`: integer (default: `10`)
|
271
|
+
- `offset`: integer (default: `0`)
|
272
|
+
- `sort`: `[[:property, :asc], [:property, :desc]]`
|
273
|
+
|
274
|
+
```ruby
|
275
|
+
# To retrieve all contacts from contact list ID 123:
|
276
|
+
> variable = Mailjet::Contact.all(limit: 0, contacts_list: 123)
|
277
|
+
```
|
278
|
+
|
279
|
+
#### Retrieve a single object
|
280
|
+
|
281
|
+
Use the `.find` method to retrieve a specific object. Specify the ID of the object inside the parentheses.
|
112
282
|
|
113
|
-
|
283
|
+
```ruby
|
284
|
+
# Retrieve a specific contact ID.
|
285
|
+
require 'mailjet'
|
286
|
+
Mailjet.configure do |config|
|
287
|
+
config.api_key = ENV['MJ_APIKEY_PUBLIC']
|
288
|
+
config.secret_key = ENV['MJ_APIKEY_PRIVATE']
|
289
|
+
end
|
290
|
+
variable = Mailjet::Contact.find($CONTACT_EMAIL)
|
291
|
+
p variable.attributes['Data']
|
292
|
+
```
|
114
293
|
|
115
|
-
|
294
|
+
#### Retrieve the count of objects matching the query
|
295
|
+
|
296
|
+
```ruby
|
297
|
+
> Mailjet::Contact.count
|
298
|
+
=> 83
|
299
|
+
```
|
300
|
+
|
301
|
+
#### Retrieve the first object matching the query
|
302
|
+
|
303
|
+
```ruby
|
304
|
+
> Mailjet::Contact.first
|
305
|
+
=> #<Mailjet::Contact>
|
306
|
+
````
|
307
|
+
|
308
|
+
### PUT request
|
309
|
+
|
310
|
+
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.
|
311
|
+
|
312
|
+
Here's an example of a PUT request:
|
313
|
+
|
314
|
+
```ruby
|
315
|
+
> recipient = Mailjet::Listrecipient.first
|
316
|
+
=> #<Mailjet::Listrecipient>
|
317
|
+
> recipient.is_active = false
|
318
|
+
=> false
|
319
|
+
> recipient.attributes
|
320
|
+
=> {...} # attributes hash
|
321
|
+
> recipient.save
|
322
|
+
=> true
|
323
|
+
> recipient.update_attributes(is_active: true)
|
324
|
+
=> true
|
325
|
+
```
|
116
326
|
|
117
|
-
|
118
|
-
email = { :from_email => "your email",
|
119
|
-
:from_name => "Your name",
|
120
|
-
:subject => "Hello",
|
121
|
-
:text_part => "Hi",
|
122
|
-
:recipients => [{:email => "recipient email"}] }
|
327
|
+
### DELETE request
|
123
328
|
|
124
|
-
|
329
|
+
Here's an example of a `DELETE` request:
|
125
330
|
|
126
|
-
|
127
|
-
|
331
|
+
```ruby
|
332
|
+
> recipient = Mailjet::Listrecipient.first
|
333
|
+
=> #<Mailjet::Listrecipient>
|
334
|
+
> recipient.delete
|
335
|
+
> Mailjet::Listrecipient.delete(123)
|
336
|
+
=> #<Mailjet::Listrecipient>
|
128
337
|
```
|
129
338
|
|
130
|
-
|
131
|
-
|
339
|
+
Upon a successful `DELETE` request the response will not include a response body, but only a `204 No Content` response code.
|
340
|
+
|
341
|
+
## Send emails with ActionMailer
|
342
|
+
|
343
|
+
A quick walkthrough to use Rails Action Mailer [here](http://guides.rubyonrails.org/action_mailer_basics.html).
|
132
344
|
|
133
345
|
First set your delivery method (here Mailjet SMTP relay servers):
|
346
|
+
|
134
347
|
```ruby
|
135
348
|
# application.rb or config/environments specific settings, which take precedence
|
136
349
|
config.action_mailer.delivery_method = :mailjet
|
@@ -138,12 +351,13 @@ config.action_mailer.delivery_method = :mailjet
|
|
138
351
|
```
|
139
352
|
|
140
353
|
Or if you prefer sending messages through [Mailjet Send API](http://dev.mailjet.com/guides/#send-transactional-email):
|
354
|
+
|
141
355
|
```ruby
|
142
356
|
# application.rb
|
143
357
|
config.action_mailer.delivery_method = :mailjet_api
|
144
358
|
```
|
145
359
|
|
146
|
-
You can use
|
360
|
+
You can use Mailjet specific options with `delivery_method_options` as detailed in the official [ActionMailer doc](http://guides.rubyonrails.org/action_mailer_basics.html#sending-emails-with-dynamic-delivery-options):
|
147
361
|
|
148
362
|
```ruby
|
149
363
|
class AwesomeMailer < ApplicationMailer
|
@@ -158,10 +372,36 @@ class AwesomeMailer < ApplicationMailer
|
|
158
372
|
end
|
159
373
|
```
|
160
374
|
|
161
|
-
|
375
|
+
Keep in mind that to use the latest version of the Send API, you need to specify the version via `delivery_method_options`:
|
376
|
+
|
377
|
+
```ruby
|
378
|
+
delivery_method_options: { version: 'v3.1' }
|
379
|
+
```
|
380
|
+
|
381
|
+
Other supported options are:
|
382
|
+
|
162
383
|
```ruby
|
384
|
+
# For v3_1 API
|
385
|
+
|
163
386
|
* :api_key
|
164
387
|
* :secret_key
|
388
|
+
* :'Priority'
|
389
|
+
* :'CustomCampaign'
|
390
|
+
* :'DeduplicateCampaign'
|
391
|
+
* :'TemplateLanguage'
|
392
|
+
* :'TemplateErrorReporting'
|
393
|
+
* :'TemplateErrorDeliver'
|
394
|
+
* :'TemplateID'
|
395
|
+
* :'TrackOpens'
|
396
|
+
* :'TrackClicks'
|
397
|
+
* :'CustomID'
|
398
|
+
* :'EventPayload'
|
399
|
+
* :'Variables'
|
400
|
+
* :'Headers'
|
401
|
+
|
402
|
+
# For v3_0 API
|
403
|
+
|
404
|
+
* :recipients
|
165
405
|
* :'mj-prio'
|
166
406
|
* :'mj-campaign'
|
167
407
|
* :'mj-deduplicatecampaign'
|
@@ -170,12 +410,11 @@ Supported options are:
|
|
170
410
|
* :'mj-templateerrordeliver'
|
171
411
|
* :'mj-templateid'
|
172
412
|
* :'mj-trackopen'
|
173
|
-
* :'mj-trackclick'
|
413
|
+
* :'mj-trackclick',
|
174
414
|
* :'mj-customid'
|
175
415
|
* :'mj-eventpayload'
|
176
|
-
* :
|
177
|
-
* :
|
178
|
-
* :'recipients'
|
416
|
+
* :vars
|
417
|
+
* :headers
|
179
418
|
```
|
180
419
|
|
181
420
|
Otherwise, you can pass the custom Mailjet SMTP headers directly:
|
@@ -244,150 +483,17 @@ UserMailer.welcome_email.deliver_now!
|
|
244
483
|
|
245
484
|
For more information on `ActionMailer::MessageDelivery`, see the documentation [HERE](http://edgeapi.rubyonrails.org/classes/ActionMailer/MessageDelivery.html)
|
246
485
|
|
247
|
-
|
248
|
-
|
249
|
-
This gem provide a convenient wrapper for consuming the mailjet API. The wrapper is highly inspired by [ActiveResource][activeresource] even though it does not depend on it.
|
250
|
-
|
251
|
-
You can find out all the resources you can access to in the [Official API docs][apidocs].
|
252
|
-
|
253
|
-
Let's have a look at the power of this thin wrapper
|
254
|
-
|
255
|
-
### Naming conventions
|
256
|
-
|
257
|
-
* Class names' first letter is capitalized followed by the rest of the resource name in lowercase (e.g. `listrecipient` will be `Listrecipient` in ruby)
|
258
|
-
* Ruby attribute names are the [underscored][underscore-api] versions of API attributes names (e.g. `IsActive` will be `is_active` in ruby)
|
259
|
-
|
260
|
-
### Wrapper REST API
|
261
|
-
|
262
|
-
Let's say we want to manage list recipients.
|
263
|
-
|
264
|
-
#### GET all the recipients in one query:
|
265
|
-
|
266
|
-
```ruby
|
267
|
-
> recipients = Mailjet::Listrecipient.all(limit: 0)
|
268
|
-
=> [#<Mailjet::Listrecipient>, #<Mailjet::Listrecipient>]
|
269
|
-
```
|
270
|
-
|
271
|
-
By default, `.all` will retrieve only 10 resources, so, you have to specify `limit: 0` if you want to GET them all.
|
272
|
-
|
273
|
-
You can refine queries using [API Filters][apidoc-recipient]`*` as well as the following parameters:
|
274
|
-
|
275
|
-
* format: `:json, :xml, :rawxml, :html, :csv` or `:phpserialized` (default: `:json`)
|
276
|
-
* limit: int (default: 10)
|
277
|
-
* offset: int (default: 0)
|
278
|
-
* sort: `[[:property, :asc], [:property, :desc]]`
|
279
|
-
|
280
|
-
#### GET the resources count
|
281
|
-
|
282
|
-
```ruby
|
283
|
-
> Mailjet::Listrecipient.count
|
284
|
-
=> 83
|
285
|
-
```
|
286
|
-
|
287
|
-
#### GET the first resource matching a query
|
288
|
-
|
289
|
-
```ruby
|
290
|
-
> Mailjet::Listrecipient.first
|
291
|
-
=> #<Mailjet::Listrecipient>
|
292
|
-
```
|
293
|
-
|
294
|
-
#### GET a resource from its id
|
295
|
-
|
296
|
-
```ruby
|
297
|
-
> recipient = Mailjet::Listrecipient.find(id)
|
298
|
-
=> #<Mailjet::Listrecipient>
|
299
|
-
```
|
300
|
-
|
301
|
-
#### Updating a resource
|
302
|
-
|
486
|
+
#### Manage contacts via CSV Upload
|
487
|
+
Create the CSV content in a format compatible with the Mailjet API, see the documentation [HERE](https://dev.mailjet.com/email/guides/contact-management/#manage-contacts-via-csv-upload)
|
303
488
|
```ruby
|
304
|
-
|
305
|
-
=> #<Mailjet::Listrecipient>
|
306
|
-
> recipient.is_active = false
|
307
|
-
=> false
|
308
|
-
> recipient.attributes
|
309
|
-
=> {...} # attributes hash
|
310
|
-
> recipient.save
|
311
|
-
=> true
|
312
|
-
> recipient.update_attributes(is_active: true)
|
313
|
-
=> true
|
489
|
+
Mailjet::ContactslistCsv.send_data(ID_CONTACTLIST, File.open('some_csvdata.csv', 'r'))
|
314
490
|
```
|
315
491
|
|
316
|
-
####
|
317
|
-
```ruby
|
318
|
-
> recipient = Mailjet::Listrecipient.first
|
319
|
-
=> #<Mailjet::Listrecipient>
|
320
|
-
> recipient.delete
|
321
|
-
> Mailjet::Listrecipient.delete(123)
|
322
|
-
=> #<Mailjet::Listrecipient>
|
323
|
-
```
|
324
|
-
|
325
|
-
### Action Endpoints
|
326
|
-
|
327
|
-
Some APIs allow the use of action endpoints:
|
328
|
-
* [/newsletter](http://dev.mailjet.com/email-api/v3/newsletter/)
|
329
|
-
* [/contact](http://dev.mailjet.com/email-api/v3/contact/)
|
330
|
-
* [/contactslist](http://dev.mailjet.com/email-api/v3/contactslist/)
|
331
|
-
|
332
|
-
To use them in this wrapper, the API endpoint is in the beginning, followed by an underscore, followed by the action you are performing.
|
333
|
-
|
334
|
-
For example, the following performs `managemanycontacts` on the `contactslist` endpoint:
|
335
|
-
where 4 is the `listid` and 3025 is the `jobid`
|
336
|
-
``` ruby
|
337
|
-
Mailjet::Contactslist_managemanycontacts.find(4, 3025)
|
338
|
-
```
|
339
|
-
|
340
|
-
Each action endpoint requires the ID of the object you are changing. To 'create' (POST), pass the ID as a variable like such:
|
341
|
-
``` ruby
|
342
|
-
Mailjet::Contactslist_managecontact.create(id: 1, action: "unsub", email: "example@me.com", name: "tyler")
|
343
|
-
```
|
344
|
-
|
345
|
-
To 'find' (GET), pass the ID as a variable like such:
|
346
|
-
``` ruby
|
347
|
-
Mailjet::Contact_getcontactslists.find(1)
|
348
|
-
# will return all the lists containing the contact with id 1
|
349
|
-
```
|
350
|
-
|
351
|
-
Managing large amount of contacts asyncronously, uploading many contacts and returns a `job_id`
|
352
|
-
``` ruby
|
353
|
-
managecontactslists = Mailjet::Contact_managemanycontacts.create(contacts_lists: [{:ListID => 39, :action => "addnoforce"}], contacts: [{Email: 'mr-smith@mailjet.com'}])
|
354
|
-
|
355
|
-
```
|
356
|
-
|
357
|
-
To 'find' (GET) with also a job ID, pass two parameters - first, the ID of the object; second, the job ID:
|
358
|
-
``` ruby
|
359
|
-
Mailjet::Contactslist_managemanycontacts.find(1, 34062)
|
360
|
-
# where 1 is the contactlist id and 34062 is the job id
|
361
|
-
```
|
362
|
-
|
363
|
-
Some actions are not attached to a specific resource, like /contact/managemanycontacts. In these cases when there is a job ID but no ID for the object when 'find'ing, pass `nil` as the first parameter:
|
364
|
-
``` ruby
|
365
|
-
Mailjet::Contact_managemanycontacts.find(nil, 34062)
|
366
|
-
```
|
367
|
-
|
368
|
-
## Send emails through API
|
369
|
-
|
370
|
-
In order to send emails through the API, you just have to `create` a new `Send` resource.
|
371
|
-
|
372
|
-
``` ruby
|
373
|
-
Mailjet::Send.create(from_email: "me@example.com", to: "you@example.com", subject: "Mailjet is awesome", text_part: "Yes, it is!")
|
374
|
-
```
|
375
|
-
|
376
|
-
If you want to send it to multiple recipients, just use an array:
|
377
|
-
``` ruby
|
378
|
-
Mailjet::Send.create(from_email: "me@example.com", to: "you@example.com, someone-else@example.com", subject: "Mailjet is awesome", text_part: "Yes, it is!")
|
379
|
-
```
|
380
|
-
|
381
|
-
In order to Mailjet modifiers, you cannot use the regular form of Ruby 2 hashes. Instead, use a String `e.g.: 'mj-prio' => 2` or a quoted symbol `e.g.: 'mj-prio' => 2`.
|
382
|
-
|
383
|
-
In these modifiers, there is now the ability to add a Mailjet custom-id or Mailjet Custom payload using the following:
|
492
|
+
#### [Delete the Contact](https://dev.mailjet.com/email/guides/contact-management/#gdpr-delete-contacts)
|
384
493
|
```ruby
|
385
|
-
|
386
|
-
'mj-eventpayload' => '{"message": "hello world"}'
|
494
|
+
Mailjet::ContactPii.delete(contact_ID)
|
387
495
|
```
|
388
496
|
|
389
|
-
For more information on custom properties and available params, see the [official doc][send-api-doc].
|
390
|
-
|
391
497
|
## Track email delivery
|
392
498
|
|
393
499
|
You can setup your Rack application in order to receive feedback on emails you sent (clicks, etc.)
|
@@ -458,12 +564,21 @@ Then at the root of the gem, simply run:
|
|
458
564
|
bundle
|
459
565
|
bundle exec rake
|
460
566
|
```
|
461
|
-
|
567
|
+
|
568
|
+
## Contribute
|
569
|
+
|
570
|
+
Mailjet loves developers. You can be part of this project!
|
571
|
+
|
572
|
+
This wrapper is a great introduction to the open source world, check out the code!
|
573
|
+
|
574
|
+
Feel free to ask anything, and contribute:
|
462
575
|
|
463
576
|
- Fork the project.
|
464
|
-
- Create a
|
577
|
+
- Create a new branch.
|
465
578
|
- Implement your feature or bug fix.
|
466
|
-
- Add documentation for
|
579
|
+
- Add documentation for it.
|
467
580
|
- Add specs for your feature or bug fix.
|
468
581
|
- Commit and push your changes.
|
469
582
|
- Submit a pull request. Please do not include changes to the gemspec, or version file.
|
583
|
+
|
584
|
+
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).
|
data/Rakefile
CHANGED
@@ -1,17 +1,26 @@
|
|
1
|
-
|
2
|
-
require '
|
3
|
-
require 'bundler'
|
4
|
-
Bundler::GemHelper.install_tasks
|
1
|
+
require "rspec/core/rake_task"
|
2
|
+
require 'bundler/gem_tasks'
|
5
3
|
|
6
|
-
|
7
|
-
|
8
|
-
|
9
|
-
|
10
|
-
|
11
|
-
|
12
|
-
|
13
|
-
|
4
|
+
RSpec::Core::RakeTask.new(:spec) do |t|
|
5
|
+
t.pattern = [
|
6
|
+
"spec/mailjet/rack/endpoint_spec.rb",
|
7
|
+
"spec/mailjet/api_error_spec.rb",
|
8
|
+
"spec/mailjet/apikey_spec.rb",
|
9
|
+
"spec/mailjet/mailer_spec.rb",
|
10
|
+
"spec/mailjet/resource_spec.rb",
|
11
|
+
"spec/configuration_spec.rb",
|
12
|
+
"spec/mailjet_spec.rb",
|
13
|
+
"spec/resources/contact_spec.rb",
|
14
|
+
"spec/resources/contactmetadata_spec.rb",
|
15
|
+
"spec/resources/messagehistory_spec.rb",
|
16
|
+
"spec/resources/getcontactslists_spec.rb",
|
17
|
+
"spec/resources/template_detailcontent_spec.rb",
|
18
|
+
"spec/resources/integration_spec.rb",
|
19
|
+
"spec/resources/newsletter_spec.rb",
|
20
|
+
"spec/resources/statcounters_spec.rb",
|
21
|
+
"spec/resources/send_spec.rb",
|
22
|
+
"spec/resources/resource_spec.rb",
|
23
|
+
]
|
14
24
|
end
|
15
25
|
|
16
|
-
|
17
|
-
task :default => :spec
|
26
|
+
task default: [:spec]
|