Subscribe a new Contact to your Newsletter

The goal is to add a new subscriber to your mailing list for a newsletter. This can be achieved by adding them to the group of newsletter subscribers. First, you should double-check that there isn't an existing user. If it does not exist, you could create a new one. Finally, in either case, subscribe the contact to the correct subscription group.

If you'd like, you can test with our Postman Collection here: Postman Collection

Prerequisites

Before you begin, make sure you have valid authorization credentials. Please see this page for more information.

You will need to have the groupID (Audience > Groups) on hand that you will use to subscribe the user to the newsletter, and an opt-in type (with notification or without, and double opt-in. Please see step 3 for more information.).

Procedure

In order to search for a contact or update their information, you will need to decide which identifier you'd like to use:

Contact Identifier Type	Definition
EMAIL	The identifier is an email address.
MOBILE	The identifier is a mobile number.
APP_ALIAS	The identifier is a mobile app alias.
EXTERNAL	The identifier is a value generated by an external system.
ID	Contact (User) identifier

In our examples, we'll use email.

(Optional) Use a POST request to check if the contact already exists

In order to avoid errors, you may wish to double-check that the contact exists. To use contact/get, you must provide t he desired identifier type & subsequent identifier. In this case, we will use the contact's email address.

'POST' \  'http://yourdomain.com/api/rest/contact/get' \
{
  "type": "EMAIL",
  "value": "j.mcexample@example.com"
}'

JS

<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ecm="http://yourdomain.com/developer/ecmapi">
    <soapenv:Header/>
    <soapenv:Body>
        <ecm:contactGet>
            <identifier>
                <type>EMAIL</type>
                <value>j.mcexample@example.com</value>
            </identifier>
        </ecm:contactGet>
    </soapenv:Body>
</soapenv:Envelope>

JS

Response	Description
200	From this request, you should receive a 200 response, with information about the contact. This includes information like their contactID.
400	If the profile does not exist you will receive a 400 response. You can also double-check the email used in the call if you believe there is an existing user profile.

Use a POST request to create the Contact Profile

For this, you need to specify at least one of the following identifiers: email address, mobile number, or mobile app alias. In this case, we will use the contact's email address.

 'POST' \
  'http://yourdomain.com/api/rest/contact/create'\ 
{
"emailAddress": "j.mcexample@example.com",
"attributes":
[
{"name": "FirstName", "value": "John"},
{"name": "LastName", "value": "mcexample"},
{"name": "mobileNumber", "value": "33505606709"},
{"name": "user.ISOCountryCode", "value": "FR"}
]
}

JS

You should receive a 200 response, alongside your contact's information like this:

{
  "id": 0,
  "email": "j.mcexample@example.com",
  "mobileNumber": "string",
  "identifier": "string",
  "attributes": [
    {"name": "FirstName", "value": "John"},
    {"name": "LastName", "value": "mcexample"},
    {"name": "mobileNumber", "value": "33505606709"},
    {"name": "user.ISOCountryCode", "value": "FR"}
  ],
  
}

JS

If there was a problem, like missing required information, you might receive a 400 response.

<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ecm="http://yourdomain.com/developer/ecmapi">
    <soapenv:Header/>
    <soapenv:Body>
        <ecm:contactCreate>
            <contact>
                <contactId>1</contactId>
                <emailAddress>j.mcexample@example.com</emailAddress>
                <mobileNumber>48505606707</mobileNumber>
                <applicationAlias>?</applicationAlias>
                <identifier>?</identifier>
                <!--Zero or more repetitions:-->
                <attributes>
                    <name>test</name>
                    <value>test</value>
                </attributes>
            </contact>
        </ecm:contactCreate>
    </soapenv:Body>
</soapenv:Envelope>

JS

Use a POST request to subscribe them to a Group

While you can use email or userID, you need to also include one of the following opt-in types:

Type	Definition
CONFIRMED_OPT_IN	New contacts receive a welcome message via email when they are added to the group. The contact does not need to confirm the subscription. A single opt-in subscription.
DOUBLE_OPT_IN	New contacts receive an invitation to join the group via email. The contact must accept the invitation before they are added to the group.
OPT_IN	New contacts are added to the group without notification. OPT_IN is creating self-subscribers

By userID

For this method, you will need the contact's userID (this is the same as their ContactID from above), the groupID, and the type of opt-in you would like to use.

'POST' \  'http://yourdomain.com/api/rest/membership/subscribe?userID=12345&groupId=334&subscriptionMode=DOUBLE_OPT_IN' \

JS

<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ecm="http://yourdomain.com/developer/ecmapi">
    <soapenv:Header/>
    <soapenv:Body>
        <ecm:membershipSubscribe>
            <userID>3769713</userID>
            <groupId>385</groupId>
            <subscriptionMode>DOUBLE_OPT_IN</subscriptionMode>
        </ecm:membershipSubscribe>
    </soapenv:Body>
</soapenv:Envelope>

JS

By Email
For this method, you can replace the userID above with their email. You will still need to provide the groupID and opt-in method. According to URL encoding, some characters like "+", "[", "]" need to be encoded otherwise the request will fail.

'POST' \
  'http://yourdomain.com/api/rest/membership/subscribeByEmail?email=name%255Dsurname%40test.com&groupId=334&subscriptionMode=DOUBLE_OPT_IN' \

JS

<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ecm="http://yourdomain.com/developer/ecmapi">
    <soapenv:Header/>
    <soapenv:Body>
        <ecm:membershipSubscribeByEmail>
            <email>one@test.com</email>
            <groupId>385</groupId>
            <subscriptionMode>CONFIRMED_OPT_IN</subscriptionMode>
        </ecm:membershipSubscribeByEmail>
    </soapenv:Body>
</soapenv:Envelope>

JS

Conclusion

If the request is successful, you will receive a 204 response and no further information. This indicates that the contact has successfully been added to the group.

If you receive a 400 response, several things could have gone wrong. The parameter 'email' is not a valid email address, a user with this email does not exist, or a group with this id is archived. Please double-check. A 404 response indicates the user or group was not found. Please check the request again.