Files
piratepoet/doc/api_methods/AddSubscriber.md
Pavel Dohnal 8ee1ead0a6 Add new exception to API documentation
[MAILPOET-2107]
2019-06-06 11:22:48 -04:00

4.0 KiB
Raw Blame History

back to list

Add Subscriber

array addSubscriber(array $subscriber [, array $list_ids = [], array $options = []])

This method allows a subscriber to be created, adds them into lists, and handles confirmation email and admin notification email sending and welcome email scheduling.

If sign-up confirmation (double opt-in) is enabled in the MailPoet settings a subscriber is created with status unconfirmed otherwise the status is set to subscribed.

  • A confirmation email is an email which is sent to a subscriber so that they can confirm his subscription. It is sent only if sign-up confirmation is enabled in the MailPoet settings.
  • A welcome email is an automatic email which is sent to a new subscriber. This email is scheduled only if sign-up confirmation is disabled and a welcome email is configured for some of given lists. In case of required sign-up confirmation, it is scheduled later after a subscriber confirms the subscription.
  • An admin notification email is sent to the site admin to inform them about a new subscription. It is sent only if the notification feature is enabled in the MailPoet setting.

All these emails can be disabled using $options.

A subscriber can be added only once. This method throws an \Exception in case of adding an existing subscriber. This method also throws an \Exception in case that some of $list_ids is invalid. In such a case a subscriber is created, but is not subscribed to any list. There might be other \Exceptions because of some invalid input data such a invalid email address etc.

It returns a new subscriber. See Get Subscriber for a subscriber data structure.

Arguments

$subscriber (required)

An associative array containing subscriber data which contains default properties (email, first_name, last_name) and custom subscriber fields which were defined in MailPoet. It has to contain an email and all required custom fields. To get defined custom fields see Get Subscriber Fields

Property Type Limits Description
email (required) string 150 chars a valid email address
first_name (optional) string/null 255 chars Fist name of the subscriber.
last_name (optional) string/null 255 chars Last name of the subscriber.
cf_* (optional/required) string/null 65K chars A custom field (see Get Subscriber Fields).

$list_ids (optional)

An array containing list ids into which subscriber will be added. In case that the list is empty a subscriber will be created; but sending a confirmation email, notification email and scheduling welcome email will be skipped.

$options (optional)

All options are optional. If omitted a default value is used.

Option Type Default Description
send_confirmation_email boolean true Can be used to disable a confirmation email. Otherwise, a confirmation email is sent as described above. It is strongly recommended to keep this option set to true so that MailPoet settings for sign-up confirmation are respected. Turning it to false might lead that subscriber to be added as unconfirmed.
schedule_welcome_email boolean true Can be used to disable a welcome email. Otherwise, a welcome email is scheduled as described above.
skip_subscriber_notification boolean false Can be used to disable an admin notification email. Otherwise, an admin notification email is sent as described above.

Error handling

All expected errors from the API are exceptions of class \MailPoet\API\MP\v1\APIException. Code of the exception is populated to distinguish between different errors.

An exception of base class \Exception can be thrown when something unexpected happens.

Codes description:

Code Description
11 Missing email address
12 Trying to create a subscriber that already exists
13 The subscriber couldnt be created in the database
17 Welcome email failed to send