Recipients

This page provides you information about how to manage recipients (subscribe, unsubscribe, update personal data).

On this page:

Manage a single email recipient / subscriber

Add a single recipient / subscriber - synchronous import

A single recipient can be added to a console account by calling the following methods:

• POST /Console/List/{id_List}/Recipient

• POST /Console/Group/{id_Group}/Recipient

You can choose to perform a double optin procedure for the given recipient by adding the querystring parameter "ConfirmEmail=true": in this case the recipient will be added to the given list/group in "Pending" status, and a confirmation email will be sent to that address, waiting for his/her confirmation. You can also update the information and status of an existing recipient by specifying his/her email address or mobile number as unique identifier of the existing recipient. 

Update personal data fields of a subscriber

This section refers to changes to a specific subscriber's personal data field (the subscriber must already exist)

The update operation requires:

• Recipient ID, which can be retrieved with the operation listed above (Check if a subscriber exists)

• The IDs of the fields to be updated

Update subscription status of a recipient

You can change the subscription status of an existing recipient in a specified List. To update multiple recipients at the same time, see Manage multiple recipients below.

Update operation requires

• Recipient ID (refer to section "Check if a subscriber exists")

• List ID

Update group assignment

A group in MailUp is a subset of a list. Subscribe/unsubscribe is at the list level, not at the group level. Groups are typically used for segmentation purposes within a list.

You can use the API to assign or remove an existing recipient to/from a specified group. Removing a recipient from a group does not affect its list subscription status.

Update operation requires

• Recipient ID (see section "Check if a subscriber exists")

• Group ID

Check if a subscriber exists

This method allows you to:

• verify whether a certain recipient is already a subscriber in a certain list within a specified MailUp account

• retrieve the recipientID and personal data fields for that recipient, if it is found

Manage multiple recipients 

If you need to subscribe or unsubscribe multiple recipients it is strongly recommended to use an asynchronous method instead of calling many times the single import method. The Confimed Opt-in subscription method is availble in this mode by performing a few different API calls, as described below (see Send confirmation email).

Subscribe/unsubscribe recipients - asynchronous import 

Asynchronous import is used to perform a bulk import of several recipients into the specified list. Since the process is not synchronous, it is fast and it immediately returns an import ID (without waiting for the end of the import process), but it's not real time and there cannot be two or more imports at the same time with a single MailUp account. A HTTP 500 error with description="Resource internal error. Another import is running" is returned when you try to do more import at the same time. Please check the import status in order to know whether the import task has been completed.  

The import process is able to recognize existing recipients (using the email address or the mobile number as unique identifiers), and update them according to the given input details. It is possible to add somequerystringparameters to specify some advanced behavior for the import process:

• ConfirmEmail=true: if specified, sets the new recipients status to "Pending", and a confirmation email is generated (but not yet sent). Please check below in the section "Send Confirmation Email" the procedure to actually send the emails generated so far.

• importType=asOptout: if specified, the given recipients' status is set to "Optout", except for the ones already in “Pending” Status. A complete explanation of the available scenarios is provided below.

• clearMissingOrEmptyFields: when set to "true", the import process clears on MailUp field that is not specified or set as empty in the request body.

• removeFromPrevGroups: when set to "true", first the import process removes the given recipients from any group they have been part of, then it adds them only to the group specified along with this request. This querystring parameter applies only to "Import recipients into a group" cases.

• ignoreMobile: (RECOMMENDED if you are not going to send SMS) when set to "true", the import process ignores the MobileNumber and MobilePrefix fields. As multi-channel import is much slower than single-channel import (up to 60 times), you should avoid importing on both channels when it is not mandatory for your business goals.

• fileName: accepts a recipients' list in a file format instead of passing it through the request body. This option is recommended when uploading a large amount of data with a single call (e.g. more than 10K recipients). Please refer to the second of the links below for more details
  
  
  

Send Confirmation Email

The confirmation emails (generated in the bulk import process as the result of "ConfirmEmail=true"querystring parameter) can be sentwith the following process;

1.  Retrieve the SendingID of that confirmation email, with the following call, where {id_import} is the result of the current import call.  The result of this GET call is a structure with the SendingID (idImport) and the number of generated emails (EnqueuedEmails).

1. Send the email immediately or planning a schedule by calling one of these methods where {id_sending} is the SendingID retrieved at previousstep, with no body. Moreover a body like  {Date:'yyyy-MM-dd HH:mm'} is required: for the "Deferred" case. NOTE: the specified date must be in UTC and at least 5 minutes in the future, with the format described in the section 'Type and cast definition' of "Paging and filtering" page

Read import information

As stated above, bulk import tasks are asynchronous. Since you can run only one import task a time, it is important to check if there is a running process before starting a new one.

This section contains a method to query the status of a process by specifying its ID, a method to get a list of import tasks and a method to get all the details of a completed import.

Read Import Status

Get import status codes

Get list of import tasks