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:

In our examples, we'll use email.

1. (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' \  'https://your-engage-domain.com/api/rest/contact/get' \
{
  "type": "EMAIL",
  "value": "j.mcexample@example.com"
}'

<soapenv:Envelope
    xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ecm="https://your-engage-domain.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>

2. 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' \
  'https://your-engage-domain.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"}
]
}

{
  "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"}
  ],
  
}

<soapenv:Envelope
    xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ecm="https://your-engage-domain.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>

3. 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:

1. 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. 

   RESTSOAP

   'POST' \  'https://your-engage-domain.com/api/rest/membership/subscribe?userID=12345&groupId=334&subscriptionMode=DOUBLE_OPT_IN' \

   <soapenv:Envelope
       xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/"
       xmlns:ecm="https://your-engage-domain.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>

2. 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.

   RESTSOAP

   'POST' \
     'https://your-engage-domain.com/api/rest/membership/subscribeByEmail?email=name%255Dsurname%40test.com&groupId=334&subscriptionMode=DOUBLE_OPT_IN' \

   <soapenv:Envelope
       xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/"
       xmlns:ecm="https://your-engage-domain.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>

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. 

Related Topics

Engage web service implementation and error handling