From 82dd032f15bebd778829bd2e9d19b6795130a323 Mon Sep 17 00:00:00 2001 From: Alex Taranovsky Date: Wed, 17 Jun 2020 13:35:58 +0300 Subject: [PATCH 1/2] magento/devdocs#7366: GraphQl. subscribeEmailToNewsletter. Mutation for subscribe feature. https://devdocs.magento.com/guides/v2.4/graphql/mutations/subscribe-email-to-newsletter.html --- src/_data/toc/graphql.yml | 4 + .../subscribe-email-to-newsletter.md | 79 +++++++++++++++++++ 2 files changed, 83 insertions(+) create mode 100644 src/guides/v2.4/graphql/mutations/subscribe-email-to-newsletter.md diff --git a/src/_data/toc/graphql.yml b/src/_data/toc/graphql.yml index 30c5b4759e8..112b9ab5946 100644 --- a/src/_data/toc/graphql.yml +++ b/src/_data/toc/graphql.yml @@ -219,6 +219,10 @@ pages: - label: sendEmailToFriend mutation url: /graphql/mutations/send-email-to-friend.html + - label: subscribeEmailToNewsletter mutation + url: /graphql/mutations/subscribe-email-to-newsletter.html + exclude_versions: ["2.3"] + - label: setBillingAddressesOnCart mutation url: /graphql/mutations/set-billing-address.html diff --git a/src/guides/v2.4/graphql/mutations/subscribe-email-to-newsletter.md b/src/guides/v2.4/graphql/mutations/subscribe-email-to-newsletter.md new file mode 100644 index 00000000000..d642313fec0 --- /dev/null +++ b/src/guides/v2.4/graphql/mutations/subscribe-email-to-newsletter.md @@ -0,0 +1,79 @@ +--- +group: graphql +title: subscribeEmailToNewsletter mutation +contributor_name: Atwix +contributor_link: https://www.atwix.com/ +--- + +The `subscribeEmailToNewsletter` mutation allows subscription for guests and registered customers. + +## Syntax + +`mutation: {subscribeEmailToNewsletter(email: String!): SubscribeEmailToNewsletterOutput}` + +## Example usage + +The following call adds an email into a newsletter subscription. + +**Request:** + +```graphql +mutation { + subscribeEmailToNewsletter( + email: "email@example.com" + ) { + status + } +} +``` + +**Response:** + +```json +{ + "data": { + "subscribeEmailToNewsletter": { + "status": "SUBSCRIBED" + } + } +} +``` + +## Input arguments + +Mutation contains a required `email` parameter that specifies an email address that should be added into a newsletter subscription. + +## Output attributes + +The `SubscribeEmailToNewsletterOutput` object contains the following attributes: + +Attribute | Data Type | Description +--- | --- | --- +`status` | SubscriptionStatusesEnum | Contains a subscription status of specified `email` address. + +### SubscriptionStatusesEnum + +The `SubscriptionStatusesEnum` is a predefined set of possible subscription statuses: + +Value | Description +--- | --- +`NOT_ACTIVE` | Subscription requires a confirmation. Confirmation email has been sent to specified email address to confirm the subscription. +`SUBSCRIBED` | Email address is subscribed. +`UNSUBSCRIBED` | Email address is unsubscribed. +`UNCONFIRMED` | Specified email ties to customer which did not confirm a required customer registration. + +The `subscribeEmailToNewsletter` mutation for the `status` field may return only the following statuses: + +- `NOT_ACTIVE` +- `SUBSCRIBED` + +## Errors + +Error | Description +--- | --- +`Cannot create a newsletter subscription.` | A general error message that appears on some internal system errors. The original error is logged and can be found in the Magento logs. +`Enter a valid email address.` | The value provided in the `email` argument has an invalid format. +`Guests can not subscribe to the newsletter. You must create an account to subscribe.` | Guest subscription is disabled. Go to **Stores** > **Configuration** > **Customers** > **Newsletter** > **Subscription Options** > **Allow Guest Subscription** in the Admin to adjust the setting. +`The account sign-in was incorrect or your account is disabled temporarily.` | The email address provided in the `email` argument ties to customer account pending confirmation. +`This email address is already subscribed.` | The email address provided in the `email` argument is already subscribed. +`You must specify an email address to subscribe to a newsletter.`| The empty value is provided in the `email` argument. From d68e0b39679af720d79514ee8840d0b5987b3637 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Sat, 20 Jun 2020 15:54:16 -0500 Subject: [PATCH 2/2] Grammar/style updates --- .../mutations/subscribe-email-to-newsletter.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/guides/v2.4/graphql/mutations/subscribe-email-to-newsletter.md b/src/guides/v2.4/graphql/mutations/subscribe-email-to-newsletter.md index d642313fec0..d92fc5d8e24 100644 --- a/src/guides/v2.4/graphql/mutations/subscribe-email-to-newsletter.md +++ b/src/guides/v2.4/graphql/mutations/subscribe-email-to-newsletter.md @@ -5,7 +5,7 @@ contributor_name: Atwix contributor_link: https://www.atwix.com/ --- -The `subscribeEmailToNewsletter` mutation allows subscription for guests and registered customers. +The `subscribeEmailToNewsletter` mutation allows guests and registered customers to sign up to receive newsletters. ## Syntax @@ -13,7 +13,7 @@ The `subscribeEmailToNewsletter` mutation allows subscription for guests and reg ## Example usage -The following call adds an email into a newsletter subscription. +The following call subscribes an email to the store's newsletter. **Request:** @@ -41,7 +41,7 @@ mutation { ## Input arguments -Mutation contains a required `email` parameter that specifies an email address that should be added into a newsletter subscription. +The mutation contains a required `email` parameter that specifies the email address to be added into a newsletter subscription. ## Output attributes @@ -57,10 +57,10 @@ The `SubscriptionStatusesEnum` is a predefined set of possible subscription stat Value | Description --- | --- -`NOT_ACTIVE` | Subscription requires a confirmation. Confirmation email has been sent to specified email address to confirm the subscription. -`SUBSCRIBED` | Email address is subscribed. -`UNSUBSCRIBED` | Email address is unsubscribed. -`UNCONFIRMED` | Specified email ties to customer which did not confirm a required customer registration. +`NOT_ACTIVE` | The subscription requires a confirmation. A confirmation email has been sent to specified email address to confirm the subscription. +`SUBSCRIBED` | The email address is subscribed. +`UNSUBSCRIBED` | The email address is unsubscribed. +`UNCONFIRMED` | The specified email is that of a customer who did not previously confirm a required customer registration. The `subscribeEmailToNewsletter` mutation for the `status` field may return only the following statuses: @@ -74,6 +74,6 @@ Error | Description `Cannot create a newsletter subscription.` | A general error message that appears on some internal system errors. The original error is logged and can be found in the Magento logs. `Enter a valid email address.` | The value provided in the `email` argument has an invalid format. `Guests can not subscribe to the newsletter. You must create an account to subscribe.` | Guest subscription is disabled. Go to **Stores** > **Configuration** > **Customers** > **Newsletter** > **Subscription Options** > **Allow Guest Subscription** in the Admin to adjust the setting. -`The account sign-in was incorrect or your account is disabled temporarily.` | The email address provided in the `email` argument ties to customer account pending confirmation. +`The account sign-in was incorrect or your account is disabled temporarily.` | The email address provided in the `email` argument is that of a customer account pending confirmation. `This email address is already subscribed.` | The email address provided in the `email` argument is already subscribed. -`You must specify an email address to subscribe to a newsletter.`| The empty value is provided in the `email` argument. +`You must specify an email address to subscribe to a newsletter.`| The `email` argument is empty.