EmailOptIn v1.2

Opt-in emails are the cornerstone of permission marketing. They ensure that subscriptions are confirmed and genuine.

What can I do with emailOptIn?

Send a confirmed opt-in email with a unique link that's automatically generated:

  • See our subscription endpoint for more information on confirmed opt-in, subscriptions and best practice.
  • POST with subscriber_id and list_id to create a new subscription and send an opt-in email in the same request.
  • POST with subscription_id to issue (or re-issue) an opt-in email.
  • Each subscriber can receive 4 opt-in emails per list_id, up to a maximum of 10 emails within a 24 hour period. An error will occur if these limits are exceeded.
  • Only opt-in emails created with the opt-in endpoint can be fetched. Opt-in emails generated by other means will not be available.

We may request proof of every confirmed opt-in which is manually confirmed through the Permission Marketing API.

GET /emailOptIn or /emailOptIn/:id

AttributeTypeFilterSortDescription
id
intYesYesUnique ID of the resource.
completed
boolYesNoWhether the opt-in email has been sent.
confirmed
boolYesNoWhether the subscriber has confirmed the opt-in.
error
boolYesNoWhether the opt-in encountered an error.
errortype
enum/nullNoNoAn enum of an error, if one occurred. Possible values: 'Failed', 'Blacklisted', 'Hard bounce', 'Soft bounce'.
list_id
intYesNoUnique ID of the list.
message_id*
int/nullYesNoID of a message containing the required email link code. If no message_id is specified then the default opt-in email is sent instead.
redirectionurl*
string/nullNoNoDirect the user to this URL once they have accepted the opt-in. If no redirectionurl is specified the user will see the default confirmation page.
subscriber_id
intYesNoUnique ID of the subscriber.
subscription_id
intYesNoUnique ID of the subscription.
cdate
decimalNoYesCreation timestamp.

* Currently supports "null" value only. Non-null funtionality may be made available through subsequent releases of PMAPI.

HEAD /emailOptIn or /emailOptIn/:id

AttributeTypePresenceDescription
id
intOptionalUnique ID of the resource.
completed
boolOptionalWhether the opt-in email has been sent.
confirmed
boolOptionalWhether the subscriber has confirmed the opt-in.
error
boolOptionalWhether the opt-in encountered an error.
list_id
intOptionalUnique ID of the list.
message_id*
int/nullOptionalID of a message containing the required email link code. If no message_id is specified then the default opt-in email is sent instead.
subscriber_id
intOptionalUnique ID of the subscriber.
subscription_id
intOptionalUnique ID of the subscription.

* Currently supports "null" value only. Non-null funtionality may be made available through subsequent releases of PMAPI.

POST /emailOptIn

AttributeTypePresenceDescription
list_id
intOptional**Unique ID of the list.
message_id*
int/nullOptionalID of a message containing the required email link code. If no message_id is specified then the default opt-in email is sent instead.
redirectionurl*
string/nullOptionalDirect the user to this URL once they have accepted the opt-in. If no redirectionurl is specified the user will see the default confirmation page.
subscriber_id
intOptional**Unique ID of the subscriber.
subscription_id
intOptional**Unique ID of the subscription.

* Currently supports "null" value only. Non-null funtionality may be made available through subsequent releases of PMAPI.

** You must either provide a subscription_id OR (subscriber_id AND list_id). A new subscription is created if you specify subscriber_id and list_id - this subscription will be confirmed once the subscriber clicks the opt-in link in the sent message.

Each subscriber can receive 4 opt-in emails per list_id, up to a maximum of 10 emails within a 24 hour period. An error will occur if these limits are exceeded.

PUT /emailOptIn or /emailOptIn/:id

This method is not supported.

DELETE /emailOptIn or /emailOptIn/:id

This method is not supported.

Error codes

There are no error codes for this endpoint.

Examples

JSON response

{
    "id"               : 123456,
    "completed"        : true,
    "confirmed"        : true, 
    "error"            : false,
    "errortype"        : null,
    "list_id"          : 123456,
    "message_id"       : null,
    "redirectionurl"   : null,
    "subscriber_id"    : 123456,
    "subscription_id"  : null,
    "cdate"            : 123456,
}