Ongage 3rd Party Content Integration

Table of Contents:

General Important Notice About 3rd Party Content Integrations

Important Info

(warning) In general, these integrations only work with Ongage's SMTP relay vendors (unless indicated otherwise below).

A full list of which vendors are of type SMTP you can find in our ESP/SMTP/SMS Vendors Knowledge Base page.

How to Setup and use Indeed in Ongage

Indeed Intro

  • Indeed claims to be the world's #1 job site, with over 180 million unique visitors every month from over 50 different countries,
  • The Ongage - Indeed integration, enables you to simply put an Indeed invocation tag in your HTML email and it will pull a tailored job offering from the Indeed Job database, for each of your recipients based on their zip code/location and job title
  • The Ongage Indeed Invocation tag in its most basic form looks like this: {{indeed}} - i.e., this is what you put inside your HTML email.
  • For each tag, in each email, we issue an API call to Indeed, which looks something like this:
http://www.indeed.com/ads/imgad?adsformat=json&adslimit=10&publisher=1234567890123456&userid=emailname%40somedomain.com&q=Marketing&l=10024
http://api.indeed.com/ads/apisearch?format=json&v=2&userip=127.0.0.1&chnl=CALL&publisher=123456789012345&limit=10

There are 2 types of Indeed job invocation methods

  1. {{indeed}} for retrieving Image ads: will load an image with a set of job offerings, directly into your HTML email newsletter. That set of jobs is refreshed and reloaded each time the recipient opens their email.
  2. {{indeedxml}} for retrieving XML ads: when using this method, Ongage makes a call to the Indeed DB for each email that goes, with that recipient's zip code and job title. The email gets rendered into HTML based on HTML code that is set within Ongage. In this method the email get's populated once when it is sent. If the recipient opens the emails several times, they will get the same set of jobs, unlike in the case of the image tag.

(info) Note: There is now a New Indeed XML Invocation Tag – see the following chapter

How to Connect your Indeed Account to your Ongage Account

  1. Send us your Indeed publisher key
  2. Tell us which 2 fields in your list that will contain the location and job title as those 2 fields we'll use when calling Indeed, so that each one of your recipients will get a tailored offering/content based on those parameters. The Job title will be used in the Indeed query parameter (&q=) and the zip or city or state field will be used in location parameter (&l=)
  3. Wait for a confirmation email from us that we have connected your account!
  4. Optional: additional list fields can be mapped to parameters sent in the Indeed API call and those are: 
    1. radius (Distance, in miles, from search location, the default port is 25).
    2. jt (job type: Internship, Full-time, Part-time, Contract, Temporary).
    3. limit (Maximum number of results returned per query, the default value is 10).
    4. co (Search within country specified. Default is US).

Using Indeed in Ongage

  1. As noted above, Indeed requires at least 2 fields as input in order to bring back relevant jobs:

    1. Location where location is a postal code (i.e., zip code) – or –  a "city, state/province/region" combination.

    2. Job Title(s)

    3. In your List in Ongage tell us which 2 fields we should map to those two. Typically you’ll want to call them something similar e.g., zip_code, job_title.

  2. When importing your recipients into Ongage, you 'll want to make sure that those 2 fields have values for each one of your List members.
    1. Then in your email all you need to do, is enter either one of the invocation tags, either {{indeed}} or {{indeedxml}}

    2. {{indeed}}        retrieves job image banner ads.

    3. {{indeedxml}}  retrieves job text ads in XML format.

  3. In addition you can send in the invocation tag, 2 additional parameters: (1) Indeed Channel ID and (2)  number of ads to display, in the following manner {{indeed:1234567:10}}
    1. Channel ID is an optional logical tagging, that Indeed offers, so you can track the performance of different websites / or sources.
    2. If you don't indicate the number of ads to display, by default it is typically set to 4

Every recipient will get a tailored job ad

  • Each one of your recipients will get jobs advertisements that match the values that are in your list for them, in their list zip_code and job_title fields.
  • So based on the following example Jenny will get Marketing related Indeed ads in NYC,  John will get Sales related ads in California, and Sarah will get QA and Support ads in Washington DC.
emailfirst_namelast_namezip_codejob_title
jenny_jackson@somewhere.com  Jenny Jackson10024Marketing
john_smith@somewhere.com JohnSmith90005Sales
sarah_taylor@somewhere.comSarahTaylor20001QA, Support

For example your email might look like this

 How to format IndeedXML and render it into HTML

In the case of Indeed XML, you will need to use the {{indeedxml}} tag and provide Ongage Support with an accompanying HTML template, that will be used to render the XML data that comes back from the API call to Indeed XML, into HTML and would look something like this example:

Indeed HTML Template Example
<table align="center" border="0" cellpadding="0" cellspacing="0" style="border-collapse:collapse; mso-table-lspace:0pt; mso-table-rspace:0pt;margin-bottom:20px" width="100%">
	<tbody>
		<tr>
			<td>
				<a style="font-size:12px;color:#0000cc;font-family:Arial, Helvetica, sans-serif;" href="[url]&mid={{myid}}">[title]</a>
			</td>
		</tr>
		<tr>
			<td style="padding:5px 0;font-size:12px;color:#000;font-family:Arial, Helvetica, sans-serif;">[company] - <span style="color:#999;">[location], [state]</span></td>
		</tr>
		<tr>
			<td style="padding:0;font-size:12px;color:#cd29c0;font-family:Arial, Helvetica, sans-serif;">Sponsored by <span style="font-weight:bold;">[company]</span></td>
		</tr>
	</tbody>
</table>


Important

  • (warning) The above is an example, when providing a different HTML template based on the above make sure to keep the parameters within the square brackets [ ]. Note: those key words are case sensitive. 
  • The HTML tags must be valid and structured as in the above example.



And here's an example of what your recipients might receive in their inbox if their location was NYC and Job Title is Marketing Manager:

About Clicks Tracking when using Indeed in Ongage 

  • Generally speaking Ongage does not track Indeed clicks.
  • This is specifically true In the case of Indeed image, since the links are loaded directly from the Indeed server, into the recipient's mail client / mobile device, and never goes through Ongage. So, Ongage has no way to track these image links.
  • In the case of Indeed XML ONLY, Ongage can turn on campaign level click statsONLY. Meaning Ongage can't track which recipients clicked on which link, but you will get campaign aggregated click stats.

Indeed Advanced Replacement Macros

If you have more than one Indeed publisher ID: you can set the publisher ID dynamically by adding the following replacement macro to the HTML email of the campaign:

[[0:publisher:12345]]

Additionally you can control the destination URL that comes back from Indeed XML with the following replacement Macro. If you wish to do this, please contact Ongage support, as this macro requires an additional setup in the Ongage back-end

[[0:indeedxml.param.destination_domain:www.yoururl.com]]

(info) Note: These macros should be placed within the <body> </body> tags of your HTML email.

The New Indeed XML Invocation Tag 

Ongage has upgraded the Indeed XML invocation tag to the new and more dynamic format (like that below of Jobs2Career) which provides you full control as to which dynamic fields from your Ongage list you want to use on the API call to Indeed XML. So above in the section "How to Connect your Indeed Account to your Ongage Account" you no longer need to tell us which 2 fields in your Ongage list you want to map to the Indeed XML API call.  Now you can determine that on your own, and change whenever you want without needing to contact us.

{{ocx_dynamic_xml_indeed_new{url=http://api.indeed.com/ads/apisearch?userip={{ip}}&q={{query}}&l={{location}}}}}

How to send multiple values on a single Indeed parameter

You can send multiple values on a single Indeed parameter, where supported by the Indeed API. The location parameter is one such example. You can for example, place three Ongage dynamic list fields, even if you don't have values for all three. You need to have at least one value populated, as the location is a required parameter. All you need to do is use the HTML encoding for the comma character (%2C) separator, in the following manner:

&l={{state}}%2C{{city}}%2C{{zip}}

New invocation tag supports using 2 different publication keys in same email message 

Use 1st publisher key
{{ocx_dynamic_xml_indeed_new{url=http://api.indeed.com/ads/apisearch?userip={{ip}}&q={{query}}&l={{location}},external_account=default}}}
 
Use 2nd publisher key
{{ocx_dynamic_xml_indeed_new{url=http://api.indeed.com/ads/apisearch?userip={{ip}}&q={{query}}&l={{location}},external_account=con_1}}}
 
When not indicated then it will use the default one
{{ocx_dynamic_xml_indeed_new{url=http://api.indeed.com/ads/apisearch?userip={{ip}}&q={{query}}&l={{location}}}}}

How to Setup and Use Talroo (Formerly Jobs2Careers) in Ongage

Talroo (Formerly Jobs2Careers) Intro

  • Jobs2Careers is a US nationwide job search aggregator. Parent company was re-branded to Talroo with Jobs2Career a subsidiary. 
  • The Ongage - Jobs2Careers integration, enables you to simply put a special URL tag, in the body of your HTML email, and it will pull a tailored job offering from Jobs2Careers, for each of your recipients, based on the personalized search values, for each given recipient in your campaign.

The Ongage Jobs2Careers Invocation Tag

{{ocx_dynamic_xml_jobs2careers{url=http://api.jobs2careers.com/api/search.php?q={{query}}&l={{location}}&industry={{industry}}&format=xml}}}
  1. The above URL will invoke an API call to the Jobs2Careers database for each recipient in the targeted campaign where it is used, with URL parameter values unique to that recipient.
  2. This is what you should put in the <body> tag of your HTML email. 

Connect your Jobs2Careers Account to your Ongage Account

  1. Send us your J2C credentials id=1234 and password=ABCDe1fGhI3KLM and we'll setup the connection for you. 

  2. Send us an HTML template file of how you'd like the the formatting of the jobs to appear in your HTML email as J2C returns an XML, that needs to be formatted into HTML. Here's an example:
Sample HTML Snippet
<a href="[url]"><h3>[title]</h3></a>
<h4>Company: [company]</h4>
<b>City: [city]</b><br>
Date: [date]<br>
<b>Description: [description]<br><b>


The parameters above in square brackets, are populated dynamically by the XML that returns from Jobs2Career. E.g., [url], [title], etc. The above is just an example, you can use any valid HTML and CSS formatting you like to match your brand, so long as it complies with HTML for email messages.

How to Use Jobs2Careers in Ongage

  1. Let say that in your List in Ongage you have the fields: job_title and city for each of your recipients.

  2. Make sure that the members in your list, have values for those fields.

  3. Then setup a campaign using the following J2C invocation tag in your email message:

    {{ocx_dynamic_xml_jobs2careers{url=http://api.jobs2careers.com/api/search.php?q={{job_title}}&l={{city}}&format=xml}}}
  4. (warning)We recommended entering the above directly into the HTML code, and not via the WYSIWYG editor, which could add unexpected CSS code in the middle of the tag.
  5. URL encoding: In case job_title or city have values with spaces, Ongage will automatically URL encode it for you, so you don't need to worry about that.. For example the value "Sales Manager" will be sent on the URL as following: &q=Sales+Manager.
  6. The location &l= parameter is required. You can pass more than one parameter here, if you do then use the "+" to concatonate, e.g., &l={{param-1}}+{{param-2}}
  7. If you want pass multiple job titles then use the &industry= parameter along with the pipe "|" character as a delimiter, e.g., &industry=sales|marketing

To test that your Jobs2Careers account is setup and properly working, you can pop the following URL into your browser, and substitute id= and pass= with the values of your account at Jobs2Careers:

http://api.jobs2careers.com/api/search.php?id=1234&pass=a1b2c3d4e5&ip=50.18.254.253&q=sales&l=78759&industry=sales&format=xml


Additional Notes

  • Email message will not be sent in case of failed J2C API calls: if for a given contact, in your campaign, a mandatory field is missing, or is incorrect, and the API call for that contact to J2C fails, then Ongage will simply not send the email message to that contact, and will move on to the next contact targeted in that campaign (and will continue to attempt to send to all remaining contacts).

Jobs2Careers API Document and Parameters

  • Here is a link to the Jobs2Careers API documentation which Ongage implemented. Included here just as a general reference, there's no need for you to implement it as Ongage has already done that for you!
  • What might be of interest are the API parameters that can be used on the URL call. Not all of the below are applicable.

How to setup and use ZipRecruiter in Ongage

ZipRecruiter Intro

  • ZipRecruiter is an online employment marketplace, connecting millions of employers and job seekers through mobile and email services.
  • The Ongage - ZipRecruiter integration, enables you to simply put a ZipRecruiter invocation tag in your HTML email and it will pull a tailored job offering from ZipRecruiter, for each of your recipients, based on the location and search (job title) values.

Connect your ZipRecruiter Account to your Ongage Account

  1. Send us your ZipRecruiter API Key.
  2. Send us an HTML code snippet, to format the XML, that ZipRecruiter returns, into HTML, to be displayed in your HTML Email (See similar examples above).
  3. Wait for a confirmation from us that we have connected your account and have set the HTML template for styling the job offering in your email message.

The ZipRecruiter Invocation Tag

  • Simply place the following invocation tag inside the body of your HTML email.
  • We recommend entering it directly into the HTML code and not via the wysiwyg editor to ensure that no CSS code is accidentally inserted into the middle of the command below.
  • Only the search parameter is mandatory all the rest are optional. The search parameter will typically have the job title you're searching for e.g., "Sales":

{{ocx_dynamic_content_ziprecruiter{url=https://api.ziprecruiter.com/jobs/v1?search={{search}}&location={{location}}&radius_miles=25}}}

Request Parameters

Here's a list of some of the parameters that can be used:

Field

Type

Description

search

string

search terms, e.g. “Inside Sales”

location

string

location, e.g., “Santa Monica, CA” or zipcode e.g., “10001”

radius_miles

integer

distance of the job relative to the location

days_ago

integer

only show jobs posted within this number of days

A list of all parameters can be found here: https://docs.google.com/document/d/1PM6pgV06vGbQJoZ1mxeSTZPr1aYemSGoEyTtNTDyt3s/pub 


To test that your ZipRecruiter account is setup and properly working, you can pop the following URL into your web browser, using your ZipRecruiter API Key: 

https://api.ziprecruiter.com/jobs/v1?search=Sales&api_key=YOUR_API_KEY

(warning) Note: The above should not be used within the invocation tag indicated in the previous section. The above is just for testing that the API to your ZipRecuriter account is working!

Appendix 

How to manage multiple HTML templates with the new job board feeds

This feature is only supported for invocation tags that start with the new job board feeds that start with ocx_dynamic_xml_

  1. Contact Ongage – and supply the additional HTML snippet templates. Indicate to support the name you'd like to give to it – in example below template_2
  2. Once support gets back to you, that the additional template was set, you can invoke it in the following manner:
{{ocx_dynamic_xml_jobs2careers{url=http://api.jobs2careers.com/api/search.php?limit=4&q={{keyword}}&l={{zip}}&ip={{ip}}&format=xml,template=template_2}}}

(info) For examples of what the HTML snippet should look like – see examples in the sections above.