From 3b635788529e8aeb5fbed362d0261f50f89d43bf Mon Sep 17 00:00:00 2001
From: Rostislav Wolny <rosta@mailpoet.com>
Date: Wed, 22 May 2019 17:07:46 +0200
Subject: [PATCH] Add doc page for getSubscriber method

[MAILPOET-2035]
---
 doc/api_methods/GetSubscriber.md | 89 ++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)
 create mode 100644 doc/api_methods/GetSubscriber.md

diff --git a/doc/api_methods/GetSubscriber.md b/doc/api_methods/GetSubscriber.md
new file mode 100644
index 0000000000..a4e49ce574
--- /dev/null
+++ b/doc/api_methods/GetSubscriber.md
@@ -0,0 +1,89 @@
+[back to list](../Readme.md)
+
+# Get Subscriber
+
+## `array getSubscriber(string $subscriber_email)`
+
+This method throws an `\Exception` in case a subscriber with a given email address doesn’t exist.
+
+## Arguments
+| Argument | Type | Description |
+| --- | --- | --- |
+| $subscriber_email | string | a valid email address |
+
+## A subscriber data structure
+
+### Subscriber
+| Property | Type | Limits | Description |
+| --- | --- | --- | --- |
+| id | string | 11 chars | Id of the subscriber |
+| wp_user_id | string\|null | 20 chars | Id of a WordPress user associated with the subscriber |
+| is_woocommerce_user | string | - | A flag telling whether the user is also a WooCommerce customer. Possible values are: `1`, `0` |
+| first_name | string | 255 chars | Fist name of the subscriber. |
+| last_name | string | 255 chars | Last name of the subscriber. |
+| email | string | 150 chars | Email address of the subscriber. |
+| status | string | - | Status of the subscriber. Possible values are: `unconfirmed`, `subscribed`, `unsubscribed`, `bounced`, `inactive` |
+| subscribed_ip | string\|null | 45 chars | An IP address used for subscription. |
+| confirmed_ip | string\|null | 45 chars | An IP address used for confirmation. |
+| confirmed_at | string\|null | - | UTC time of subscription confirmation in 'Y-m-d H:i:s' format |
+| created_at | string\|null | - | UTC time of creation in 'Y-m-d H:i:s' format |
+| updated_at | string | - | UTC time of last update in 'Y-m-d H:i:s' format |
+| deleted_at | string\|null | - | This property in not null in case that list is in trash and contains UTC time in 'Y-m-d H:i:s' format. |
+| unconfirmed_data | string\|null | 65K chars | May contain serialized subscriber data in case when there are pending changes waiting for a confirmation from a subscriber |
+| source | string\|null | - | Possible values: `form`,`imported`,`administrator`,`api`,`wordpress_user`,`woocommerce_user`,`woocommerce_checkout`,`unknown`)
+| count_confirmations | string | 11 chars | Counter for confirmation emails |
+| subscriptions | array | - | List of subcriber subscriptions |
+| cf_{custom_field['id']}| string | 65K chars | A custom subscriber field value (see [Get Subscriber Fields](GetSubscriberFields.md)|
+
+### Subscriber's subscription
+| Property | Type | Limits | Description |
+| --- | --- | --- | --- |
+| id | string | 11 chars | Id of relation |
+| subscriber_id | string | 11 chars | Id of subscriber |
+| segment_id | string | 11 chars | Id of a list |
+| status | string | - | Status of a subscription for the list. Possible values: `subscribed`, `unsubscribed` |
+| created_at | string | - | UTC time of creation in 'Y-m-d H:i:s' format |
+| updated_at | string | - | UTC time of last update in 'Y-m-d H:i:s' format |
+
+### Response Example
+```php
+<?php
+[
+  'id' => '10',
+  'wp_user_id' => '72',
+  'is_woocommerce_user' => '1',
+  'first_name' => 'John',
+  'last_name' => 'Doe',
+  'email' => 'email@example.com',
+  'status' => 'subscribed',
+  'subscribed_ip' => '127.0.0.1',
+  'confirmed_ip' => NULL,
+  'confirmed_at' => NULL,
+  'created_at' => '2019-05-07 07:24:37',
+  'updated_at' => '2019-05-14 08:43:08',
+  'deleted_at' => NULL,
+  'unconfirmed_data' => NULL,
+  'source' => 'woocommerce_user',
+  'count_confirmations' => '0',
+  'subscriptions' => [
+    0 => [
+      'id' => '3',
+      'subscriber_id' => '10',
+      'segment_id' => '1',
+      'status' => 'subscribed',
+      'created_at' => '2019-05-07 07:24:37',
+      'updated_at' => '2019-05-07 07:24:37',
+    ],
+    1 => [
+      'id' => '13',
+      'subscriber_id' => '10',
+      'segment_id' => '2',
+      'status' => 'unsubscribed',
+      'created_at' => '2019-05-14 08:43:08',
+      'updated_at' => '2019-05-14 08:43:08',
+    ],
+  ],
+  'cf_1' => 'US',
+  'cf_2' => 'New York',
+];
+```