Skip to content

Commit 37046c4

Browse files
n7studiosn7studios
authored
Merge pull request #79 from ConvertKit/v4-api-subscribers
v4 API: Subscribers
2 parents b07a92f + 05ec7a7 commit 37046c4

File tree

2 files changed

+912
-132
lines changed

2 files changed

+912
-132
lines changed

‎src/ConvertKit_API.php

Lines changed: 183 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -933,6 +933,155 @@ public function get_resources(string $resource)
933933
return $_resource;
934934
}
935935

936+
/**
937+
* Get subscribers.
938+
*
939+
* @param string $subscriber_state Subscriber State (active|bounced|cancelled|complained|inactive).
940+
* @param string $email_address Search susbcribers by email address. This is an exact match search.
941+
* @param \DateTime $created_after Filter subscribers who have been created after this date.
942+
* @param \DateTime $created_before Filter subscribers who have been created before this date.
943+
* @param \DateTime $updated_after Filter subscribers who have been updated after this date.
944+
* @param \DateTime $updated_before Filter subscribers who have been updated before this date.
945+
* @param string $sort_field Sort Field (id|updated_at|cancelled_at).
946+
* @param string $sort_order Sort Order (asc|desc).
947+
* @param string $after_cursor Return results after the given pagination cursor.
948+
* @param string $before_cursor Return results before the given pagination cursor.
949+
* @param integer $per_page Number of results to return.
950+
*
951+
* @since 2.0.0
952+
*
953+
* @see https://developers.convertkit.com/v4.html#list-subscribers
954+
*
955+
* @return false|mixed
956+
*/
957+
public function get_subscribers(
958+
string $subscriber_state = 'active',
959+
string $email_address = '',
960+
\DateTime $created_after = null,
961+
\DateTime $created_before = null,
962+
\DateTime $updated_after = null,
963+
\DateTime $updated_before = null,
964+
string $sort_field = 'id',
965+
string $sort_order = 'desc',
966+
string $after_cursor = '',
967+
string $before_cursor = '',
968+
int $per_page = 100
969+
) {
970+
// Build parameters.
971+
$options = [];
972+
973+
if (!empty($subscriber_state)) {
974+
$options['status'] = $subscriber_state;
975+
}
976+
if (!empty($email_address)) {
977+
$options['email_address'] = $email_address;
978+
}
979+
if (!is_null($created_after)) {
980+
$options['created_after'] = $created_after->format('Y-m-d');
981+
}
982+
if (!is_null($created_before)) {
983+
$options['created_before'] = $created_before->format('Y-m-d');
984+
}
985+
if (!is_null($updated_after)) {
986+
$options['updated_after'] = $updated_after->format('Y-m-d');
987+
}
988+
if (!is_null($updated_before)) {
989+
$options['updated_before'] = $updated_before->format('Y-m-d');
990+
}
991+
if (!empty($sort_field)) {
992+
$options['sort_field'] = $sort_field;
993+
}
994+
if (!empty($sort_order)) {
995+
$options['sort_order'] = $sort_order;
996+
}
997+
998+
// Build pagination parameters.
999+
$options = $this->build_pagination_params(
1000+
params: $options,
1001+
after_cursor: $after_cursor,
1002+
before_cursor: $before_cursor,
1003+
per_page: $per_page
1004+
);
1005+
1006+
// Send request.
1007+
return $this->get(
1008+
endpoint: 'subscribers',
1009+
args: $options
1010+
);
1011+
}
1012+
1013+
/**
1014+
* Create a subscriber.
1015+
*
1016+
* Behaves as an upsert. If a subscriber with the provided email address does not exist,
1017+
* it creates one with the specified first name and state. If a subscriber with the provided
1018+
* email address already exists, it updates the first name.
1019+
*
1020+
* @param string $email_address Email Address.
1021+
* @param string $first_name First Name.
1022+
* @param string $subscriber_state Subscriber State (active|bounced|cancelled|complained|inactive).
1023+
* @param array<string, string> $fields Custom Fields.
1024+
*
1025+
* @since 2.0.0
1026+
*
1027+
* @see https://developers.convertkit.com/v4.html#create-a-subscriber
1028+
*
1029+
* @return mixed
1030+
*/
1031+
public function create_subscriber(
1032+
string $email_address,
1033+
string $first_name = '',
1034+
string $subscriber_state = '',
1035+
array $fields = []
1036+
) {
1037+
// Build parameters.
1038+
$options = ['email_address' => $email_address];
1039+
1040+
if (!empty($first_name)) {
1041+
$options['first_name'] = $first_name;
1042+
}
1043+
if (!empty($subscriber_state)) {
1044+
$options['state'] = $subscriber_state;
1045+
}
1046+
if (count($fields)) {
1047+
$options['fields'] = $fields;
1048+
}
1049+
1050+
// Send request.
1051+
return $this->post(
1052+
endpoint: 'subscribers',
1053+
args: $options
1054+
);
1055+
}
1056+
1057+
/**
1058+
* Create multiple subscribers.
1059+
*
1060+
* @param array<int,array<string,string>> $subscribers Subscribers.
1061+
* @param string $callback_url URL to notify for large batch size when async processing complete.
1062+
*
1063+
* @since 2.0.0
1064+
*
1065+
* @see https://developers.convertkit.com/v4.html#bulk-create-subscribers
1066+
*
1067+
* @return mixed
1068+
*/
1069+
public function create_subscribers(array $subscribers, string $callback_url = '')
1070+
{
1071+
// Build parameters.
1072+
$options = ['subscribers' => $subscribers];
1073+
1074+
if (!empty($callback_url)) {
1075+
$options['callback_url'] = $callback_url;
1076+
}
1077+
1078+
// Send request.
1079+
return $this->post(
1080+
endpoint: 'bulk/subscribers',
1081+
args: $options
1082+
);
1083+
}
1084+
9361085
/**
9371086
* Get the ConvertKit subscriber ID associated with email address if it exists.
9381087
* Return false if subscriber not found.
@@ -941,27 +1090,18 @@ public function get_resources(string $resource)
9411090
*
9421091
* @throws \InvalidArgumentException If the email address is not a valid email format.
9431092
*
944-
* @see https://developers.convertkit.com/#list-subscribers
1093+
* @see https://developers.convertkit.com/v4.html#get-a-subscriber
9451094
*
9461095
* @return false|integer
9471096
*/
9481097
public function get_subscriber_id(string $email_address)
9491098
{
950-
if (!filter_var($email_address, FILTER_VALIDATE_EMAIL)) {
951-
throw new \InvalidArgumentException('Email address is not a valid email format.');
952-
}
953-
9541099
$subscribers = $this->get(
9551100
'subscribers',
9561101
['email_address' => $email_address]
9571102
);
9581103

959-
if (!$subscribers) {
960-
$this->create_log('No subscribers');
961-
return false;
962-
}
963-
964-
if ($subscribers->total_subscribers === 0) {
1104+
if (!count($subscribers->subscribers)) {
9651105
$this->create_log('No subscribers');
9661106
return false;
9671107
}
@@ -975,7 +1115,7 @@ public function get_subscriber_id(string $email_address)
9751115
*
9761116
* @param integer $subscriber_id Subscriber ID.
9771117
*
978-
* @see https://developers.convertkit.com/#view-a-single-subscriber
1118+
* @see https://developers.convertkit.com/v4.html#get-a-subscriber
9791119
*
9801120
* @return false|integer
9811121
*/
@@ -992,7 +1132,7 @@ public function get_subscriber(int $subscriber_id)
9921132
* @param string $email_address New Email Address.
9931133
* @param array<string, string> $fields Updated Custom Fields.
9941134
*
995-
* @see https://developers.convertkit.com/#update-subscriber
1135+
* @see https://developers.convertkit.com/v4.html#update-a-subscriber
9961136
*
9971137
* @return false|mixed
9981138
*/
@@ -1023,56 +1163,64 @@ public function update_subscriber(
10231163
}
10241164

10251165
/**
1026-
* Unsubscribe an email address from all forms and sequences.
1166+
* Unsubscribe an email address.
10271167
*
10281168
* @param string $email Email Address.
10291169
*
1030-
* @see https://developers.convertkit.com/#unsubscribe-subscriber
1170+
* @see https://developers.convertkit.com/v4.html#unsubscribe-subscriber
10311171
*
10321172
* @return false|object
10331173
*/
10341174
public function unsubscribe(string $email)
10351175
{
1036-
return $this->put(
1037-
'unsubscribe',
1038-
['email' => $email]
1176+
return $this->post(
1177+
sprintf(
1178+
'subscribers/%s/unsubscribe',
1179+
$this->get_subscriber_id($email)
1180+
)
10391181
);
10401182
}
10411183

10421184
/**
1043-
* Remove subscription from a form
1185+
* Unsubscribe the given subscriber ID.
10441186
*
1045-
* @param array<string, string> $options Array of user data (email).
1187+
* @param integer $subscriber_id Subscriber ID.
10461188
*
1047-
* @see https://developers.convertkit.com/#unsubscribe-subscriber
1189+
* @see https://developers.convertkit.com/v4.html#unsubscribe-subscriber
10481190
*
10491191
* @return false|object
10501192
*/
1051-
public function form_unsubscribe(array $options)
1193+
public function unsubscribe_by_id(int $subscriber_id)
10521194
{
1053-
// This function is deprecated in 1.0, as we prefer functions with structured arguments.
1054-
// This function name is also misleading, as it doesn't just unsubscribe the email
1055-
// address from forms.
1056-
trigger_error(
1057-
'form_unsubscribe() is deprecated in 1.0. Use unsubscribe($email) instead.',
1058-
E_USER_NOTICE
1059-
);
1060-
1061-
return $this->put('unsubscribe', $options);
1195+
return $this->post(sprintf('subscribers/%s/unsubscribe', $subscriber_id));
10621196
}
10631197

10641198
/**
10651199
* Get a list of the tags for a subscriber.
10661200
*
10671201
* @param integer $subscriber_id Subscriber ID.
1202+
* @param string $after_cursor Return results after the given pagination cursor.
1203+
* @param string $before_cursor Return results before the given pagination cursor.
1204+
* @param integer $per_page Number of results to return.
10681205
*
1069-
* @see https://developers.convertkit.com/#list-tags-for-a-subscriber
1206+
* @see https://developers.convertkit.com/v4.html#list-tags-for-a-subscriber
10701207
*
10711208
* @return false|array<int,\stdClass>
10721209
*/
1073-
public function get_subscriber_tags(int $subscriber_id)
1074-
{
1075-
return $this->get(sprintf('subscribers/%s/tags', $subscriber_id));
1210+
public function get_subscriber_tags(
1211+
int $subscriber_id,
1212+
string $after_cursor = '',
1213+
string $before_cursor = '',
1214+
int $per_page = 100
1215+
) {
1216+
return $this->get(
1217+
endpoint: sprintf('subscribers/%s/tags', $subscriber_id),
1218+
args: $this->build_pagination_params(
1219+
after_cursor: $after_cursor,
1220+
before_cursor: $before_cursor,
1221+
per_page: $per_page
1222+
)
1223+
);
10761224
}
10771225

10781226
/**

0 commit comments

Comments
 (0)