From 2b4354238e178403c2cb5427e004423fe273a48b Mon Sep 17 00:00:00 2001 From: Oleksandr Mazepa Date: Mon, 23 Dec 2024 13:08:27 +0200 Subject: [PATCH] other: Finish readme for ibp --- .DS_Store | Bin 8196 -> 0 bytes .gitignore | 2 +- README.md | 578 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 576 insertions(+), 4 deletions(-) delete mode 100644 .DS_Store diff --git a/.DS_Store b/.DS_Store deleted file mode 100644 index d9e89792c01aaeb6548a0c7d400e3019b6a4d151..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 8196 zcmeHM-A)rh6g~qLwgm(ejKsubZ@j|>5K%8oN}QLQUz?wN$pdq(4-wCB63v z^uky0IeY@&!h5guJ2OkOGcDd~WG0z8v$NkfbLN{f9cCdSk?&MjiI#}SL1w!!gJMkL z_nb%4MBH)}R)A0BQv>a8uU0#<=@ zsQ~{zxX5gCu^lKYe>zaeD*$W?%`%~mdw}G)vCYMHpsb{#Pj!0`F;&D@458?F?=l=V z7u$idicUh&NyH=LM06x4fY? zk+Z*KLXBt+44QGV}3Q5JeE%_3V;p423Kc@YX&0)MvX@@a32j^ z<`l$3Y>lFz@Gy;*0B>c13Lq3NXM9K8GU!)`yrP)ODgpxq0}sG z(F3$Tru$T&hx7zCOAV^(JUQzmZ&7O60FpI6RZFc?tTg(0OD&@xRwda_O0H7N^iwKf z;v$S`^e0sqi}Sjz!#F~|d51y0)m~ZoE+!^Z7pA5iC*x%1GOtVfQMc5tv^%YQrTLPd zb}H?CFRnj}qF`9Bc+cy8x4f{p6@~3eJ@lKBT(A0oyn0a&t5G)}b;4>(_ESGOVi@y$nAhc-k4~i$D-)yi4%8g2g>hALr->SUkrA6+)m(xS`V{E z4>I&dc^obpFHKJ|w@uonN3df8U+Q*}&~1jdEjA?2tPPum>J18X|A=)=vgVcHDe8{zU8W*1|6LtX!*Xwrvi(s;Tq zGGcxt)EtJktyl$21twL)65sy|XMg`UY4+JFU={d}6cDNH(smvbI{mxIoEzV@UF2P4 zPK+BUD=8@CbsSb+$6<&6Fht!2lsUQB4wOX;(qH%xAWzBUnQG5}xfHfIM+*D~t2f|( diff --git a/.gitignore b/.gitignore index 2c2f785c..d56b0c71 100644 --- a/.gitignore +++ b/.gitignore @@ -6,4 +6,4 @@ build ./test.js .coverage/ .nvmrc -.DS_Store +**/.DS_Store diff --git a/README.md b/README.md index ed4b8cb3..9334390e 100644 --- a/README.md +++ b/README.md @@ -202,11 +202,27 @@ The following service methods are available to instantiated clients. The example - [create](#create-8) - [update](#update-4) - [destroy](#destroy-6) - - [Attributes](#attributes) + - [SeedsLists Attributes](#attributes) - [list](#list-8) - [get](#get-10) - - [Filters](#filters) + - [SeedsLists Filters](#filters) - [list](#list-9) + - [Providers](#providers) + - [list](#list-10) + - [Results](#results) + - [list](#list-11) + - [get](#get-11) + - [destroy](#destroy-7) + - [getResultByShareId](#getresultbyshareid) + - [Results Attributes](#attributes-1) + - [list](#list-12) + - [get](#get-12) + - [Results Filters](#filters-1) + - [list](#list-13) + - [Sharing](#sharing) + - [get](#get-13) + - [update](#update-5) + - [Run Test](#run-test) - [Navigation thru lists](#navigation-thru-lists) - [Browser Demo](#browser-demo) - [Development](#development) @@ -216,7 +232,7 @@ The following service methods are available to instantiated clients. The example - [Release Process](#release-process) - [TODO](#todo) -Method naming conventions: +### Method naming conventions: - `get` or `get{{Item}}` - expected response for client is a single object - `list` or `list{{Items}}` - expected response for client is a list of objects - `create` or `create{{Item}}` - expected response for client is a single object @@ -2213,6 +2229,7 @@ A client to manage members within a specific mailing list. ### Inbox Placements A client to allows you to see the likely deliverability of your email campaigns. - #### SeedsLists + - #### list `mg.inbox_placements.seedsLists.list()` @@ -2387,6 +2404,7 @@ A client to manage members within a specific mailing list. is_auto_generated: true, } ``` + - #### create ```js mg.inbox_placements.seedsLists.create({ @@ -2531,6 +2549,7 @@ A client to manage members within a specific mailing list. ``` - #### Attributes + - #### list `mg.inbox_placements.seedsLists.attributes.list()` @@ -2551,6 +2570,7 @@ A client to manage members within a specific mailing list. }, ...] } ``` + - #### get `mg.inbox_placements.attributes.get('attribute_name');` @@ -2570,7 +2590,9 @@ A client to manage members within a specific mailing list. } } ``` + - #### Filters + - #### list `mg.inbox_placements.seedsLists.filters.list()` @@ -2595,6 +2617,556 @@ A client to manage members within a specific mailing list. } } ``` + +- #### Providers + + - #### list + List all available email providers. + + `mg.inbox_placements.providers.list()` + + Example: + + ```JS + mg.inbox_placements.providers.list() + .then(data => console.log(data)) // logs response data + .catch(err => console.error(err)); //logs any error + ``` + Promise returns: providers list + ```JS + { + items: [ + { + domain: 'something.com', + region: 'provider region', + display_name: 'provider name', + created_at: new Date('2024-08-09T14:32:57.183Z'), + updated_at: new Date('2024-08-09T14:32:59.183Z') + }, + ... + ] + } + ``` + +- #### Results + + - #### list + Get the details for all placement test results. + + ```js + mg.inbox_placements.results.list({ + 'sender': 'sender value', // optional + 'subject': 'subject value', // optional + 'provider': 'provider value', // optional + 'target_email': 'target_email value', // optional + 'time_after': new Date('2024-08-09T14:32:57.183Z'), // optional + 'time_before': new Date('2024-08-11T14:32:57.183Z'), // optional + 'cursor': '', // optional + 'sort': '', // optional + 'offset': 1, // optional + 'ascending': true, // optional + 'limit': 5, // optional + }) + ``` + + Example: + + ```JS + mg.inbox_placements.results.list({ + 'sender': 'sender value', // optional + 'subject': 'subject value', // optional + }) + .then(data => console.log(data)) // logs response data + .catch(err => console.error(err)); //logs any error + ``` + Promise returns: results list + ```JS + { + status: 200, + items: [ + { + rid: 'rid_value', + result_id: 'result_id_value', + AccountID: 'AccountID_value', + KeyBoxID: 'KeyBoxID_value', + keybox_email: 'keybox_email_value', + subject: 'subject_value', + sender: 'sender_value', + seedlist_name: 'seedlist_name_value', + created_at: new Date('2024-08-09T14:32:57.183Z'), + updated_at: new Date('2024-08-11T14:32:57.183Z'), + status: 'status_value', + CreatedTS: 1723214101728, + attributes: { + attribute_value: 'attribute_value_value' + }, + campaign_id: 'campaign_id_value', + sharing_enabled: true, + sharing_id: 'sharing_id_value', + sharing_expires_at: new Date('2024-08-14T14:32:57.183Z'), + Box: { + Id: 'box_Id_value', + kid: 'box_kid_value', + AccountID: 'box_AccountID_value', + created_at: new Date('2024-08-11T14:32:57.183Z'), + updated_at: new Date('2024-08-12T14:32:57.183Z'), + last_result_at: new Date('2024-08-13T14:32:57.183Z'), + Seeds: null, + target_email: 'box_target_email_value', + sending_domains: null, + has_results: true, + name: 'box_name_value', + seed_filter: 'box_seed_filter_value', + mailing_list: 'box_mailing_list_value', + CreatedTS: 1723214101728, + tags: ['tag_value'], + SeedQuality: 100, + is_auto_generated: true, + }, + seed_results: [{ + email: 'seed_result_email_value', + provider: 'seed_result_provider_value', + destination: 'seed_result_destination_value', + state: 'seed_result_state_value', + originating_ip: 'seed_result_originating_ip_value', + tags: ['seed_result_tag_value'], + dkim: 'seed_result_dkim_value', + spf: 'seed_result_spf_value', + dmarc: 'seed_result_dmarc_value', + headers: [{ + key: 'seed_result_header_key_value', + value: 'seed_result_header_value_value', + }], + extensions: { + category: 'seed_result_extensions_category_value', + } + }], + spamassassin: { + is_spam: false, + score: 1, + required: 1, + rules: [{ + name: 'rule_name_value', + points: 100, + short_description: 'short_description_value', + long_description: 'long_description_value', + }], + }, + delivery_stats: { + test_delivery_stat: { + delivered: 1, + missing: 0, + pending: 0, + spam: 0, + inbox: 0, + total: 1, + provider: 'provider_value', + categories: { + primary: 1, + updates: 0, + } + } + } + } + ], + pages: { + first: '?page=first', + last: '?page=last', + next: '?page=next', + previous: '?page=previous', + }, + } + ``` + + - #### get + + Get the details for a single result. + + `mg.inbox_placements.results.get(IBPResultId)` + + Example: + + ```JS + mg.inbox_placements.results.get(IBPResultId); + .then(data => console.log(data)) // logs response data + .catch(err => console.error(err)); //logs any error + ``` + + Promise returns: Inbox Placement result item + ```JS + { + status: 200, + inboxPlacementResult: { + rid: 'rid_value', + result_id: 'result_id_value', + AccountID: 'AccountID_value', + KeyBoxID: 'KeyBoxID_value', + keybox_email: 'keybox_email_value', + subject: 'subject_value', + sender: 'sender_value', + seedlist_name: 'seedlist_name_value', + created_at: new Date('2024-08-09T14:32:57.183Z'), + updated_at: new Date('2024-08-11T14:32:57.183Z'), + status: 'status_value', + CreatedTS: 1723214101728, + attributes: { + attribute_value: 'attribute_value_value' + }, + campaign_id: 'campaign_id_value', + sharing_enabled: true, + sharing_id: 'sharing_id_value', + sharing_expires_at: new Date('2024-08-14T14:32:57.183Z'), + Box: { + Id: 'box_Id_value', + kid: 'box_kid_value', + AccountID: 'box_AccountID_value', + created_at: new Date('2024-08-11T14:32:57.183Z'), + updated_at: new Date('2024-08-12T14:32:57.183Z'), + last_result_at: new Date('2024-08-13T14:32:57.183Z'), + Seeds: null, + target_email: 'box_target_email_value', + sending_domains: null, + has_results: true, + name: 'box_name_value', + seed_filter: 'box_seed_filter_value', + mailing_list: 'box_mailing_list_value', + CreatedTS: 1723214101728, + tags: ['tag_value'], + SeedQuality: 100, + is_auto_generated: true, + }, + seed_results: [{ + email: 'seed_result_email_value', + provider: 'seed_result_provider_value', + destination: 'seed_result_destination_value', + state: 'seed_result_state_value', + originating_ip: 'seed_result_originating_ip_value', + tags: ['seed_result_tag_value'], + dkim: 'seed_result_dkim_value', + spf: 'seed_result_spf_value', + dmarc: 'seed_result_dmarc_value', + headers: [{ + key: 'seed_result_header_key_value', + value: 'seed_result_header_value_value', + }], + extensions: { + category: 'seed_result_extensions_category_value', + } + }], + spamassassin: { + is_spam: false, + score: 1, + required: 1, + rules: [{ + name: 'rule_name_value', + points: 100, + short_description: 'short_description_value', + long_description: 'long_description_value', + }], + }, + delivery_stats: { + test_delivery_stat: { + delivered: 1, + missing: 0, + pending: 0, + spam: 0, + inbox: 0, + total: 1, + provider: 'provider_value', + categories: { + primary: 1, + updates: 0, + } + } + } + } + } + ``` + + - #### destroy + Delete the result and all associated information. + + `mg.inbox_placements.results.destroy(IBPResultId)` + + Example: + + ```JS + mg.inbox_placements.results.destroy(IBPResultId) + .then(data => console.log(data)) // logs response data + .catch(err => console.error(err)); //logs any error + ``` + + Promise returns: status object + ```JS + { + status: 200, + message: 'deleted' + } + ``` + + - #### getResultByShareId + Get a result by the share ID. + ```js + mg.inbox_placements.results.getResultByShareId('result_sharing_id') + ``` + + Example: + + ```JS + mg.inbox_placements.results.getResultByShareId('result_sharing_id') + .then(data => console.log(data)) // logs response data + .catch(err => console.error(err)); //logs any error + ``` + + Promise returns: Inbox Placement result item + ```JS + { + status: 200, + inboxPlacementResult: { + rid: 'rid_value', + result_id: 'result_id_value', + AccountID: 'AccountID_value', + KeyBoxID: 'KeyBoxID_value', + keybox_email: 'keybox_email_value', + subject: 'subject_value', + sender: 'sender_value', + seedlist_name: 'seedlist_name_value', + created_at: new Date('2024-08-09T14:32:57.183Z'), + updated_at: new Date('2024-08-11T14:32:57.183Z'), + status: 'status_value', + CreatedTS: 1723214101728, + attributes: { + attribute_value: 'attribute_value_value' + }, + campaign_id: 'campaign_id_value', + sharing_enabled: true, + sharing_id: 'sharing_id_value', + sharing_expires_at: new Date('2024-08-14T14:32:57.183Z'), + Box: { + Id: 'box_Id_value', + kid: 'box_kid_value', + AccountID: 'box_AccountID_value', + created_at: new Date('2024-08-11T14:32:57.183Z'), + updated_at: new Date('2024-08-12T14:32:57.183Z'), + last_result_at: new Date('2024-08-13T14:32:57.183Z'), + Seeds: null, + target_email: 'box_target_email_value', + sending_domains: null, + has_results: true, + name: 'box_name_value', + seed_filter: 'box_seed_filter_value', + mailing_list: 'box_mailing_list_value', + CreatedTS: 1723214101728, + tags: ['tag_value'], + SeedQuality: 100, + is_auto_generated: true, + }, + seed_results: [{ + email: 'seed_result_email_value', + provider: 'seed_result_provider_value', + destination: 'seed_result_destination_value', + state: 'seed_result_state_value', + originating_ip: 'seed_result_originating_ip_value', + tags: ['seed_result_tag_value'], + dkim: 'seed_result_dkim_value', + spf: 'seed_result_spf_value', + dmarc: 'seed_result_dmarc_value', + headers: [{ + key: 'seed_result_header_key_value', + value: 'seed_result_header_value_value', + }], + extensions: { + category: 'seed_result_extensions_category_value', + } + }], + spamassassin: { + is_spam: false, + score: 1, + required: 1, + rules: [{ + name: 'rule_name_value', + points: 100, + short_description: 'short_description_value', + long_description: 'long_description_value', + }], + }, + delivery_stats: { + test_delivery_stat: { + delivered: 1, + missing: 0, + pending: 0, + spam: 0, + inbox: 0, + total: 1, + provider: 'provider_value', + categories: { + primary: 1, + updates: 0, + } + } + } + } + } + ``` + + - #### Attributes + + - #### list + `mg.inbox_placements.results.attributes.list()` + + Example: + + ```JS + mg.inbox_placements.results.attributes.list() + .then(data => console.log(data)) // logs response data + .catch(err => console.error(err)); //logs any error + ``` + Promise returns: results attributes + ```JS + { + status: 200, + items:[{ + attribute: 'available attribute', + values: ['attribute_value', ...] + }, ...] + } + ``` + + - #### get + `mg.inbox_placements.attributes.get('attribute_name');` + + Example: + ```JS + mg.inbox_placements.results.attributes.get('attribute_name') + .then(data => console.log(data)) // logs response data + .catch(err => console.error(err)); //logs any error + ``` + Promise returns: results attribute + ```JS + { + status: 200, + items: { + attribute: 'attribute_name', + values: ['attribute_value', ...] + } + } + ``` + + - #### Filters + + - #### list + `mg.inbox_placements.results.filters.list()` + + Example: + + ```JS + mg.inbox_placements.results.filters.list() + .then(data => console.log(data)) // logs response data + .catch(err => console.error(err)); //logs any error + ``` + Promise returns: SeedsLists filters + ```JS + { + status: 200, + supported_filters:{ + filters: [ + { + parameter: 'parameter_name', + description: 'parameter_description' + }, .... + ] + } + } + ``` + + - #### Sharing + - #### get + The sharing status of a result. + + `mg.inbox_placements.results.sharing.get('result_id');` + Example: + ```JS + mg.inbox_placements.results.sharing.get('result_id'); + .then(data => console.log(data)) // logs response data + .catch(err => console.error(err)); //logs any error + ``` + Promise returns: IPRSharingResult + ```JS + { + status: 200, + result_id: 'result_id', + expires_at: new Date('2024-08-12T14:32:57.183Z'), + enabled: true, + url_id: 'result_sharing_id', + url: 'url-to-shared-result-page', + api_url: 'url-shared-result-page-in-json' + } + ``` + - #### update + Change the sharing status of a result or create a new share URL + + `mg.inbox_placements.results.sharing.update('result_id', IPRSharingUpdateData);` + + Example: + ```JS + mg.inbox_placements.results.sharing.update('result_id', { enabled: false }); + .then(data => console.log(data)) // logs response data + .catch(err => console.error(err)); //logs any error + ``` + Promise returns: IPRSharingResult + ```JS + { + status: 200, + result_id: 'result_id', + expires_at: new Date('2024-08-12T14:32:57.183Z'), + enabled: false, + url_id: 'result_sharing_id', + url: '', + api_url: '' + } + ``` + +- #### Run test + Create and run a new inbox placement test. + + Either 'html' or 'template_name' field should be provided. + + 'variables' are Template variables, which could be used in html or template. You can use next recipient variables inside Template variables, which will be filled for every seed automatically: %recipient.first_name%, %recipient.last_name%. + + `mg.inbox_placements.runTest(InboxPlacementsData);` + + Example: + ```JS + mg.inbox_placements.runTest({ + from: 'Excited User ', + subject: 'Subject of test email', + provider_filter: ['o365.mailgun.email'], + html: ` +

Waiting for inbox placements support in mailgun.js SDK?

+

We are working on this

+ `, + template_name: 'name-of-the-template-you-made-in-mailgun-web-portal'; + variables: JSON.stringify({ + 'template_variable_name': 'template_variable_value' + }, + seed_list: 'previously-generated-seed-list', + }) + .then(data => console.log(data)) // logs response data + .catch(err => console.error(err)); //logs any error + ``` + + Promise returns: InboxPlacementsTestResult + + ```JS + { + status: 200, + result_id: 'result_id', + links: { + results: 'link to result page', + } + } + ``` + ## Navigation thru lists Most of the methods that return items in a list support pagination. There are two ways to receive part of the list: