Skip to content

v4 API: Subscribers #79

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Mar 26, 2024
Merged

v4 API: Subscribers #79

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
bf6c5d4
Started work on subscriber methods
n7studios Mar 21, 2024
344b717
Completed first pass of subscriber methods
n7studios Mar 21, 2024
2d9db50
Added `callback_url` for bulk add subscribers
n7studios Mar 21, 2024
24faea8
Started stubbing tests
n7studios Mar 21, 2024
5ea28c7
Merge remote-tracking branch 'origin/v4-api-oauth' into v4-api-subscr…
n7studios Mar 22, 2024
58c96ea
Started writing tests for `get_subscribers`
n7studios Mar 22, 2024
134f661
Continued tests for `get_subscribers`
n7studios Mar 22, 2024
f9e515d
Completed `get_subscribers` tests
n7studios Mar 22, 2024
43a2375
Started tests for `create_subscriber`
n7studios Mar 22, 2024
c61d362
Completed `create_subscriber` tests
n7studios Mar 22, 2024
d657bfa
Completed tests
n7studios Mar 22, 2024
099a8b4
testCreateSubscriberWithSubscriberState: Use `cancelled` state for test
n7studios Mar 25, 2024
05ec7a7
Merge remote-tracking branch 'origin/v4-api-oauth' into v4-api-subscr…
n7studios Mar 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
218 changes: 183 additions & 35 deletions src/ConvertKit_API.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -933,6 +933,155 @@ public function get_resources(string $resource)
return $_resource;
}

/**
* Get subscribers.
*
* @param string $subscriber_state Subscriber State (active|bounced|cancelled|complained|inactive).
* @param string $email_address Search susbcribers by email address. This is an exact match search.
* @param \DateTime $created_after Filter subscribers who have been created after this date.
* @param \DateTime $created_before Filter subscribers who have been created before this date.
* @param \DateTime $updated_after Filter subscribers who have been updated after this date.
* @param \DateTime $updated_before Filter subscribers who have been updated before this date.
* @param string $sort_field Sort Field (id|updated_at|cancelled_at).
* @param string $sort_order Sort Order (asc|desc).
* @param string $after_cursor Return results after the given pagination cursor.
* @param string $before_cursor Return results before the given pagination cursor.
* @param integer $per_page Number of results to return.
*
* @since 2.0.0
*
* @see https://developers.convertkit.com/v4.html#list-subscribers
*
* @return false|mixed
*/
public function get_subscribers(
string $subscriber_state = 'active',
string $email_address = '',
\DateTime $created_after = null,
\DateTime $created_before = null,
\DateTime $updated_after = null,
\DateTime $updated_before = null,
string $sort_field = 'id',
string $sort_order = 'desc',
string $after_cursor = '',
string $before_cursor = '',
int $per_page = 100
) {
// Build parameters.
$options = [];

if (!empty($subscriber_state)) {
$options['status'] = $subscriber_state;
}
if (!empty($email_address)) {
$options['email_address'] = $email_address;
}
if (!is_null($created_after)) {
$options['created_after'] = $created_after->format('Y-m-d');
}
if (!is_null($created_before)) {
$options['created_before'] = $created_before->format('Y-m-d');
}
if (!is_null($updated_after)) {
$options['updated_after'] = $updated_after->format('Y-m-d');
}
if (!is_null($updated_before)) {
$options['updated_before'] = $updated_before->format('Y-m-d');
}
if (!empty($sort_field)) {
$options['sort_field'] = $sort_field;
}
if (!empty($sort_order)) {
$options['sort_order'] = $sort_order;
}

// Build pagination parameters.
$options = $this->build_pagination_params(
params: $options,
after_cursor: $after_cursor,
before_cursor: $before_cursor,
per_page: $per_page
);

// Send request.
return $this->get(
endpoint: 'subscribers',
args: $options
);
}

/**
* Create a subscriber.
*
* Behaves as an upsert. If a subscriber with the provided email address does not exist,
* it creates one with the specified first name and state. If a subscriber with the provided
* email address already exists, it updates the first name.
*
* @param string $email_address Email Address.
* @param string $first_name First Name.
* @param string $subscriber_state Subscriber State (active|bounced|cancelled|complained|inactive).
* @param array<string, string> $fields Custom Fields.
*
* @since 2.0.0
*
* @see https://developers.convertkit.com/v4.html#create-a-subscriber
*
* @return mixed
*/
public function create_subscriber(
string $email_address,
string $first_name = '',
string $subscriber_state = '',
array $fields = []
) {
// Build parameters.
$options = ['email_address' => $email_address];

if (!empty($first_name)) {
$options['first_name'] = $first_name;
}
if (!empty($subscriber_state)) {
$options['state'] = $subscriber_state;
}
if (count($fields)) {
$options['fields'] = $fields;
}

// Send request.
return $this->post(
endpoint: 'subscribers',
args: $options
);
}

/**
* Create multiple subscribers.
*
* @param array<int,array<string,string>> $subscribers Subscribers.
* @param string $callback_url URL to notify for large batch size when async processing complete.
*
* @since 2.0.0
*
* @see https://developers.convertkit.com/v4.html#bulk-create-subscribers
*
* @return mixed
*/
public function create_subscribers(array $subscribers, string $callback_url = '')
{
// Build parameters.
$options = ['subscribers' => $subscribers];

if (!empty($callback_url)) {
$options['callback_url'] = $callback_url;
}

// Send request.
return $this->post(
endpoint: 'bulk/subscribers',
args: $options
);
}

/**
* Get the ConvertKit subscriber ID associated with email address if it exists.
* Return false if subscriber not found.
Expand All @@ -941,27 +1090,18 @@ public function get_resources(string $resource)
*
* @throws \InvalidArgumentException If the email address is not a valid email format.
*
* @see https://developers.convertkit.com/#list-subscribers
* @see https://developers.convertkit.com/v4.html#get-a-subscriber
*
* @return false|integer
*/
public function get_subscriber_id(string $email_address)
{
if (!filter_var($email_address, FILTER_VALIDATE_EMAIL)) {
throw new \InvalidArgumentException('Email address is not a valid email format.');
}

$subscribers = $this->get(
'subscribers',
['email_address' => $email_address]
);

if (!$subscribers) {
$this->create_log('No subscribers');
return false;
}

if ($subscribers->total_subscribers === 0) {
if (!count($subscribers->subscribers)) {
$this->create_log('No subscribers');
return false;
}
Expand All @@ -975,7 +1115,7 @@ public function get_subscriber_id(string $email_address)
*
* @param integer $subscriber_id Subscriber ID.
*
* @see https://developers.convertkit.com/#view-a-single-subscriber
* @see https://developers.convertkit.com/v4.html#get-a-subscriber
*
* @return false|integer
*/
Expand All @@ -992,7 +1132,7 @@ public function get_subscriber(int $subscriber_id)
* @param string $email_address New Email Address.
* @param array<string, string> $fields Updated Custom Fields.
*
* @see https://developers.convertkit.com/#update-subscriber
* @see https://developers.convertkit.com/v4.html#update-a-subscriber
*
* @return false|mixed
*/
Expand Down Expand Up @@ -1023,56 +1163,64 @@ public function update_subscriber(
}

/**
* Unsubscribe an email address from all forms and sequences.
* Unsubscribe an email address.
*
* @param string $email Email Address.
*
* @see https://developers.convertkit.com/#unsubscribe-subscriber
* @see https://developers.convertkit.com/v4.html#unsubscribe-subscriber
*
* @return false|object
*/
public function unsubscribe(string $email)
{
return $this->put(
'unsubscribe',
['email' => $email]
return $this->post(
sprintf(
'subscribers/%s/unsubscribe',
$this->get_subscriber_id($email)
)
);
}

/**
* Remove subscription from a form
* Unsubscribe the given subscriber ID.
*
* @param array<string, string> $options Array of user data (email).
* @param integer $subscriber_id Subscriber ID.
*
* @see https://developers.convertkit.com/#unsubscribe-subscriber
* @see https://developers.convertkit.com/v4.html#unsubscribe-subscriber
*
* @return false|object
*/
public function form_unsubscribe(array $options)
public function unsubscribe_by_id(int $subscriber_id)
{
// This function is deprecated in 1.0, as we prefer functions with structured arguments.
// This function name is also misleading, as it doesn't just unsubscribe the email
// address from forms.
trigger_error(
'form_unsubscribe() is deprecated in 1.0. Use unsubscribe($email) instead.',
E_USER_NOTICE
);

return $this->put('unsubscribe', $options);
return $this->post(sprintf('subscribers/%s/unsubscribe', $subscriber_id));
}

/**
* Get a list of the tags for a subscriber.
*
* @param integer $subscriber_id Subscriber ID.
* @param string $after_cursor Return results after the given pagination cursor.
* @param string $before_cursor Return results before the given pagination cursor.
* @param integer $per_page Number of results to return.
*
* @see https://developers.convertkit.com/#list-tags-for-a-subscriber
* @see https://developers.convertkit.com/v4.html#list-tags-for-a-subscriber
*
* @return false|array<int,\stdClass>
*/
public function get_subscriber_tags(int $subscriber_id)
{
return $this->get(sprintf('subscribers/%s/tags', $subscriber_id));
public function get_subscriber_tags(
int $subscriber_id,
string $after_cursor = '',
string $before_cursor = '',
int $per_page = 100
) {
return $this->get(
endpoint: sprintf('subscribers/%s/tags', $subscriber_id),
args: $this->build_pagination_params(
after_cursor: $after_cursor,
before_cursor: $before_cursor,
per_page: $per_page
)
);
}

/**
Expand Down
Loading