Emarsys supports the use of HTTPS Feeds to perform background data registration tasks, which can range from adding new contact data, updating existing data or even triggering transaction-specific emails.
HTTPS Feeds use register.php registration links that run in the background to transfer content, and trigger bespoke email campaigns. As a method for data transfer it provides an easy-to-configure powerful solution that is fast to set up with no programming skill requirements. However, it should be pointed out that this is less secure than using the Emarsys API (since it uses visible URLs) and is also both slower and can handle lower volumes of data traffic.
Typical use cases for this feature are when embedded forms are used for contact registration or updates, triggering transactional mails from a web page, and as a smart way to create double opt-in solutions.
- About register.php
- Example registration
- The restrictions of using HTTPS requests
- Error handling
- Setting up HTTPS feeds
This feed type makes use of an Emarsys form to add or update contacts, and can be used directly from Emarsys or integrated within a web page. All the fields used in the transaction and feed must exist in the form in order for this feed to work.
Incoming transactions from this feed type are queued and processed at a fixed rate of 10,000 requests per hour. This results in very stable and predictable performance, and high volumes of incoming transactions will not affect (or be affected by) any other aspects of system performance.
The downside to using this feed type is that because the transactions are queued, contact updates are not immediate – and the user_ID of the contact is not returned. This means that you cannot track the contact updates, emails or responses without logging into your Emarsys account. Below is an overview of this method:
- HTTPS Feed type – register.php
- Immediacy – Request is queued
- Volume limit – 10,000 requests per hour, fixed rate
- Track user_ID – Triggered by link
- Form use – Form must contain all required fields
- Data Import method – form
- Duplication handling – yes (standard fields only)
Register.php uses standard duplication handling (first name, last name, email address), except if a specific external key has been defined for this account. Emarsys Support will tell you if a specific external key has been set.
The following parameters are used by register.php. Those in red are mandatory and must be included for the HTTPS feed to work.
|CID||This is your account ID and will be supplied by Emarsys Support|
|inp_xx||These are the fields used in the transaction, with xx being the field ID.|
|f||This is the ID of the form used by the transaction, and is needed to trigger the email.|
|optin||This is the opt-in status of the contact. Text values are used, e.g. y =TRUE, n =FALSE.|
|nl_optin||This is the opt-in used for newsletters. It must contain the form ID of the newsletter form to which the contact is subscribed.|
Below is an example of the kind of information that you might want to collect in your web page and then send to Emarsys using register.php:
|Emarsys registration form ID||f||1234|
|Contact’s opt-in status||optin||TRUE|
Creating the HTTPS Feed using the above would result in the following URL:
Note: If you are using a multiple-choice field to capture information and want to include more than one value, then each value must be entered separately and the parameter must be followed by square brackets [ ], otherwise only the last value will be taken,
- Correct use:
- Incorrect use:
The restrictions of using HTTPS requests
Although quick and easy to set up, the implementations described do have some limitations which you should consider:
- If exactly the same request is resent within 15 seconds, it is treated as a mistake and ignored. The error returned is:
HTTP/1.0 409 Conflict.
- If a contact makes repeated submissions, repeated requests are sent.
- It is cumbersome to edit active on-event campaigns.
- Standard on-event campaigns have no response analysis over time.
- Custom fields and their associated variables must be created for each request in advance. This can create large amounts of data in the database which is rarely used. For example, an email for order confirmation would need fields like
- If you want to display repeated content in its own sections (e.g. show multiple products with their images and descriptions), you have to create all the sections in advance and use section targeting to display them. A large number of sections in the email campaign will also have an adverse impact on the launch speed of the email.
The registrations will be submitted as a regular HTTPS message, with the corresponding error codes.
Examples of successful responses might be:
HTTP/1.0 200 OK(for a new user registration)
HTTP/1.0 200 OK(for a contact profile update)
Examples of unsuccessful responses might be:
HTTP/1.0 400 Bad Request
HTTP/1.0 405 Method Not Allowed
HTTP/1.0 503 Service Unavailable
For a full list of HTTPS error codes, see: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.
Setting up HTTPS feeds
HTTPS feeds can be set up via a simple, five-step process:
- Prepare the database fields
- Create the form
- Create the custom HTTPS feed
- Create the transactional email (if required)
- Implement the HTTPS feed in your web shop or 3rd-party application
These steps are described in detail below.
Step 1: Preparing the Database Fields
The database fields are used to capture content in the transaction and display it in the email, for example name, booking reference, etc. This content is sent to the database via the HTTPS feed and from there is added to the email via personalization variables.
In order to include a field in the HTTPS feed, the field ID is required. For system fields, the IDs are listed here. For custom fields, you must open the field in the Field Generator dialog in Emarsys.
To do this, go to the Administration Menu, Field Editor, select the field and click Edit. The field ID can be found in the browser address bar of the Field Generator and is listed as field_id=xxxx where x is a numeric value (e.g. field_id=1234).
For single- and multiple-choice fields, you will also need to know the IDs of the hard-coded values (for all other fields you can simply enter the values manually). You can find the IDs as follows:
- System fields – on the Single-choice Fields and their Values page of this site.
- Custom fields – In the Field Generator, hover your mouse over the delete (X) icon for each value and you will see the ID in the bottom left of the dialog, displayed as
3is the ID of the value.
Once you have selected and prepared the fields you will be using, make a note of their names and IDs for use in steps 3 and 4.
Step 2: Creating the Form
Each HTTPS feed needs its own registration form. To create a form, open the Forms Manager, choose General Registration in the Create New drop-down and click Create.
Depending on the type of HTTPS feed used, you must now complete the form and add your selected fields to it.
To find the form ID, hover the cursor over the icons to the right of the Forms list (View, Edit, Delete). The form ID is displayed in the bottom left of your browser window as:
2955 is the form ID. Alternatively, open the preview of the form and the ID is displayed in the browser address bar as:
Step 3: Creating the Custom HTTPS Feed
The next step is to define the HTTPS feed that submits the data which triggers the database update and/or the transactional email. This feed is a URL and is constructed as follows:
- URL – this is the URL containing the environment domain of your Emarsys account.
- HTTPS feed type – this refers to the file used for the feed and will always be register.php?.
Parameters – these contain all the necessary data required to identify the email, add content and launch it. Multiple parameters can be separated by ‘&’. An example URL would therefore look something like this:
href="https://www.emarsys.net/u/register.php?parameter=value¶meter=value¶meter=value(%E2%80%A6)" rel="nofollow" target="_blank">https://www.emarsys.net/u/register.php?parameter=value¶meter=value¶meter=value(…)
Step 4: Creating the Transactional Email in Emarsys
If you want to trigger a transactional email with the HTTPS feed, once you have completed the above steps you must now create an email campaign. This campaign must be an on-event campaign, based on a registration form, with the transactional feed registration form selected. For example:
On the Content Creation page you add the fields which should be displayed by using the personalisation variables. The example below is how a booking confirmation email might look in Emarsys:
And here is how it might look in the email itself:
Once you have finished creating your campaign, go to the Scheduling page and select whether the email will be sent immediately after the submission has been received, or with a delay (in hours or days). After checking the personalisation you can activate the email campaign, and the transactional email is now ready to launch.
Step 5: Implementing the HTTPS feed
Once all the above steps have been completed, you simply pass on your URL to the administrator of your web shop (or other software application), and instruct them to send this request according to your requirements. This is the only part of the process which requires any degree of technical knowledge.
Once this step is complete, the HTTPS feed will be up and running.