mailjet 1.5.4 → 1.8.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (36) hide show
  1. checksums.yaml +5 -5
  2. data/README.md +298 -183
  3. data/Rakefile +23 -14
  4. data/lib/mailjet/configuration.rb +56 -4
  5. data/lib/mailjet/connection.rb +68 -33
  6. data/lib/mailjet/exception/errors.rb +94 -0
  7. data/lib/mailjet/mailer.rb +45 -16
  8. data/lib/mailjet/rack/endpoint.rb +2 -3
  9. data/lib/mailjet/resource.rb +105 -72
  10. data/lib/mailjet/resources/campaigndraft.rb +1 -1
  11. data/lib/mailjet/resources/campaigndraft_detailcontent.rb +17 -1
  12. data/lib/mailjet/resources/campaigndraft_schedule.rb +1 -1
  13. data/lib/mailjet/resources/campaigndraft_send.rb +1 -1
  14. data/lib/mailjet/resources/campaigndraft_status.rb +1 -1
  15. data/lib/mailjet/resources/campaigndraft_test.rb +1 -1
  16. data/lib/mailjet/resources/contact.rb +11 -2
  17. data/lib/mailjet/resources/contact_getcontactslists.rb +17 -0
  18. data/lib/mailjet/resources/contact_pii.rb +8 -0
  19. data/lib/mailjet/resources/contactslist_csv.rb +8 -0
  20. data/lib/mailjet/resources/csvimport.rb +0 -1
  21. data/lib/mailjet/resources/listrecipient.rb +2 -1
  22. data/lib/mailjet/resources/messagehistory.rb +16 -0
  23. data/lib/mailjet/resources/messageinformation.rb +17 -0
  24. data/lib/mailjet/resources/newsletter.rb +1 -2
  25. data/lib/mailjet/resources/openinformation.rb +17 -0
  26. data/lib/mailjet/resources/retrieve_errors_csv.rb +8 -0
  27. data/lib/mailjet/resources/send.rb +1 -1
  28. data/lib/mailjet/resources/statcounters.rb +33 -0
  29. data/lib/mailjet/resources/statistics_linkclick.rb +12 -0
  30. data/lib/mailjet/resources/template_detailcontent.rb +18 -2
  31. data/lib/mailjet/version.rb +1 -1
  32. data/lib/mailjet.rb +4 -6
  33. metadata +25 -120
  34. data/lib/mailjet/api_error.rb +0 -29
  35. data/lib/mailjet/core_extensions/ostruct.rb +0 -9
  36. data/lib/mailjet/gem_extensions/rest_client.rb +0 -19
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
- SHA1:
3
- metadata.gz: 7240913ecc6542f14a4c9cc7078347f4c55032a3
4
- data.tar.gz: 70d23c920e3b4d1e45d843eab8034fff9e2086bf
2
+ SHA256:
3
+ metadata.gz: c9c74309f3d5e557d27fe01548e0998a987c90a9bd1e5e52c187c23d33fb5475
4
+ data.tar.gz: 3c44b00a89c535c6143d0011fa6e11ca1d6bcdbc82ed984eea4b5f23b0483b89
5
5
  SHA512:
6
- metadata.gz: 2bf10f5fd0dd62f207b1d84ee7bb178c31a2501a291b2983cfa391707e10e95b73d4e087fdf66713cf99cfd05f5863f51748eb1f11b8964339ad38073132f031
7
- data.tar.gz: 1db8b006b9c5393fa185ba0dd36964e4bbb2395e9294a35d8ca76a2a170a2a8f397e623c1a9838c02e219a30b43f1214929058ea1ca9a0706d52d4150be809b1
6
+ metadata.gz: a35a75e7a661f72c28fda90a8403f363252f36cf9573786e512f1721b807b6f450d51dafdc6d8ae8c816b4bd0f32b4abe008f67b6189647a0caa70f0ebbc929d
7
+ data.tar.gz: 513f1178e1f7e625b177faa7220d60fbb4208a5d38f91642d173ee7a63d39fa3758d189f04e9a4a3e928d84e8d4921a17c22d281bb9fca2b8cf47c7f9f7348ca
data/README.md CHANGED
@@ -1,6 +1,6 @@
1
- # Mailjet
1
+ ![alt text](https://www.mailjet.com/images/email/transac/logo_header.png "Mailjet")
2
2
 
3
- [Mailjet][mailjet]'s official Ruby wrapper, bootstraped with [Mailjetter][mailjetter].
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
- This gem helps you to:
38
+ ## Overview
39
39
 
40
- * Send transactional emails through Mailjet API in Rails 3/4
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
- Compatibility:
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
- Rails ActionMailer integration designed for Rails 3.X and 4.X
45
+ ## Table of contents
49
46
 
50
- IMPORTANT: Mailjet gem switched to API v3, the new API provided by Mailjet. For the wrapper for API v1, check the [v1 branch][v1-branch].
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
- Every code example can be found in the [Mailjet Documentation][mailjet_doc]
75
+ ## Compatibility
53
76
 
54
- (Please refer to the [Mailjet Documentation Repository][api_doc] to contribute to the documentation examples)
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 up to date version from Github, add the following in your Gemfile instead:
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
- and let the bundler magic happen
106
+
107
+ Then let the bundler magic happen:
82
108
 
83
109
  ```bash
84
110
  $ bundle install
85
111
  ```
86
112
 
87
- ## Setup
113
+ ## Authentication
88
114
 
89
- ### Api key
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 (below)
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
- ### Send emails via the Send API
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
- Find more about the Mailjet Send API in the [official guides](http://dev.mailjet.com/guides/?ruby#choose-sending-method)
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
- ``` ruby
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
- test = Mailjet::Send.create(email)
329
+ Here's an example of a `DELETE` request:
125
330
 
126
- # retrieve the API response
127
- p test.attributes['Sent']
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
- ### Send emails with ActionMailer
131
- A quick walkthrough to use Rails Action Mailer [here](http://guides.rubyonrails.org/action_mailer_basics.html)
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 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):
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
- Supported options are:
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
- * :'vars'
177
- * :'headers'
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
- ## Manage your campaigns
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
- > recipient = Mailjet::Listrecipient.first
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
- #### Deleting a resource
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
- 'mj-customid' => "A useful custom ID"
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
- ## Send a pull request
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 topic branch.
577
+ - Create a new branch.
465
578
  - Implement your feature or bug fix.
466
- - Add documentation for your feature or bug fix.
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
- #!/usr/bin/env rake
2
- require 'rake/testtask'
3
- require 'bundler'
4
- Bundler::GemHelper.install_tasks
1
+ require "rspec/core/rake_task"
2
+ require 'bundler/gem_tasks'
5
3
 
6
- $:.push File.expand_path("../lib", __FILE__)
7
-
8
- Rake::TestTask.new(:spec) do |t|
9
- t.libs << 'lib'
10
- t.libs << 'spec'
11
- # t.pattern = 'spec/**/*_spec.rb'
12
- t.verbose = true
13
- t.test_files = Dir['spec/**/*_spec.rb']
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]