Oracle Eloqua integration

Better Email syncs each finished Campaign to Oracle Eloqua as an HTML email. The email arrives with its subject, preview text, sender, email group, header and footer set, filed in the folder you chose. Your team sends it from Eloqua. Better Email can also read Eloqua's Field Merges as recipient fields, export block variants as Dynamic Content, and bring send, open and click numbers back after the email goes out.

How the integration works

What a sync creates. One HTML email per Campaign and Destination, named after the Campaign. Every later sync updates that same email.

What it doesn't do. Better Email never sends or schedules anything in Eloqua, and it doesn't create Eloqua campaigns, segments or contacts. To send, add the email to an Eloqua campaign and activate it there.

What it reads. The instance's email folders, email groups, headers and footers, for the Destination settings. The Field Merges and contact field definitions, for recipient fields and conditions. With performance data on, Eloqua's totals for the emails Better Email created. It never reads contact records.

Before you start

You will need:

• an Eloqua user for Better Email alone, set up as in step 1
• the company name your team types on the Eloqua login page
• an admin user in Better Email who can create and edit integrations
• for performance data only, an Eloqua Analyzer licence for that user

1. Create an Eloqua user for Better Email

Better Email signs in to Eloqua as a user, so give it one of its own. A person changing their password or leaving the company then can't break syncing, and Eloqua's history shows which changes came from Better Email.

1. In Eloqua, add a user under Settings > Users.
2. Add it to the Advanced Users - Marketing security group. That is Oracle's minimum for API access.
3. Give it an Eloqua password. Better Email signs in with the username and password, so the user can't be limited to single sign-on. If your instance only allows single sign-on, contact us.
4. Optional: assign it an Eloqua Analyzer licence, if you want performance data.

2. Create the integration in Better Email

1. Go to Integrations and click Add integration.
2. Choose Oracle Eloqua.
3. Give the integration a clear name, such as Eloqua (Production).
4. Fill in the connection:
   • Company name, the Company field on the Eloqua login page
   • Username and Password of the user from step 1
5. Optional: turn on Sync recipient fields and Sync performance data. See Personalization with recipient fields and Performance data.
6. Leave Enabled on and click Create integration.

Better Email encrypts the password and never shows it again. There's no URL to enter. Better Email finds the data center your instance runs in when it signs in.

One integration connects to one Eloqua instance. If you have a sandbox as well as production, create one integration for each.

3. Set up Destinations

Saving the integration creates its default Destination. A Destination decides where new emails are filed, how they're framed and who they're from.

1. Open the Destinations tab and open the Destination.
2. Under Eloqua folder, email group, header and footer, click Fetch from Eloqua. Better Email reads the lists from your instance.
3. Pick the settings:

Setting	What it does
Folder	Where new emails are filed. Left blank, Eloqua uses its default folder. A later sync leaves the email in whatever folder it's in, so you can move it in Eloqua.
Email group	The email group the email belongs to. Left blank, Eloqua uses its default email group.
Header and Footer	The email header and footer Eloqua adds to the email. Left blank, the email uses its email group's.

4. Under Delivery defaults, fill in From name, From email, Reply-to name and Reply-to email. Left blank, a new email gets Eloqua's defaults and an existing email keeps its own.
5. Save the Destination.

If you send for several brands, or from several senders or folders, add one Destination per combination. Campaigns pick their Destination when they are created.

4. Sync a Campaign to Eloqua

On the Campaign's Review tab, click Sync to <integration name>.

The first sync creates an HTML email in the Destination's folder, named after the Campaign. It carries:

• the Campaign's subject line, and its preheader as the email's preview text
• the rendered HTML
• the Destination's sender, reply-to, email group, header and footer
• Eloqua's link tracking, switched on so clicks are counted

Eloqua writes the plain-text version from the HTML. After a sync, the Review tab shows an Open in Eloqua link to the email.

Eloqua saves an email without a subject line but won't send it, so Better Email doesn't sync a Campaign without one. Add a subject and sync again.

Syncing again

Each later sync through the same Destination updates the same email: its name, subject, preview text and HTML. The sender, reply-to, email group, header and footer only change when they're set on the Destination. Eloqua campaigns that already use the email keep pointing at it.

The next sync replaces the HTML, so make content changes in Better Email, not in Eloqua's editor.

Better Email creates a new email instead of updating when the earlier one:

• was deleted in Eloqua
• was archived in Eloqua
• is in another Eloqua instance, because the integration's Company name now points somewhere else

Better Email cuts the email's name at 100 characters.

5. Personalization with recipient fields

Eloqua personalizes emails with Field Merges. A Field Merge is an Eloqua asset that says which field to show and what to show when a contact has no value. Recipient fields export as Field Merges, written with the merge's syntax name:

Hi <span class=eloquaemail>FirstName</span>,

Inside a link, Better Email writes the form Eloqua uses in email links, ~~eloqua..type--emailfield..syntax--FirstName~~, so the merge doesn't break the link's HTML.

Eloqua fills in the Field Merge's own default value when a contact has none. Set defaults on the Field Merge in Eloqua. Recipient fields on an Eloqua integration have no default value in Better Email.

Syncing fields from Eloqua

1. On the integration, turn on Sync recipient fields and save.
2. Click Sync now in the page header.

Better Email reads the instance's Field Merges and creates a recipient field for each one, named after the merge. The merge's syntax name becomes the field's ESP field name. Number and date fields keep their type from the contact field the merge reads. Everything else arrives as text. Field Merges belong to the whole instance, so every Destination shares the same fields.

New fields arrive inactive. Switch on the ones you want on the integration's Recipient fields tab.

Adding a field by hand

Create the Field Merge in Eloqua first. Then add a recipient field on the Recipient fields tab and set its ESP field name to the merge's syntax name, such as FirstName.

See Recipient Fields / Merge Tags for the general setup.

6. Segmentation and block variants

An Eloqua email has no conditional code. Content that changes per contact lives in a Dynamic Content asset, so each segmented block exports as one:

• a rule for each variant, in the order the editor shows them
• the Everybody else fallback as the default content

Eloqua uses the first rule that matches, as Better Email's preview does. The Dynamic Content is named after the Campaign, and later syncs update the same assets.

A condition can test a recipient field when Better Email can match it to an Eloqua contact field. Fields synced from Field Merges that read a contact field already match. What each field type supports:

• Text fields: is, is not, is set and is not set.
• Number fields: the same, plus greater than and less than.
• Date fields: fixed dates, compared by day.

And, or and not groups work, nested as deep as you need.

Two things don't work with Eloqua:

• Code segments. Eloqua has no code to run them in, so a variant that uses one stops the sync. Build the condition from recipient fields instead.
• Dates relative to today, such as Within the next 14 days. The builder doesn't offer them on an Eloqua integration. See Dates relative to today.

Use preview profiles to check the variants before you sync. To see them with real contact data, send a test from Eloqua to a contact.

7. Performance data

Better Email can bring back sends, deliveries, opens, clicks, bounces, unsubscribes and clicks per link for the emails it synced. It needs an Eloqua Analyzer licence on the user and doesn't work in Eloqua sandboxes. See Performance data from Oracle Eloqua.

Troubleshooting

• "Eloqua rejected the login." Check the Company name, Username and Password. The user has to sign in with an Eloqua password, not single sign-on. If syncing worked before, the password may have expired or been changed in Eloqua. Enter the new one on the integration.
• "The Eloqua user is not allowed to do this." Add the user to the Advanced Users - Marketing security group.
• "Eloqua needs a subject line." Add a subject to the Campaign and sync again.
• Eloqua refuses a field, such as "senderEmail is not a valid email address". Fix the matching setting under Delivery defaults on the Destination, then sync again.
• "Eloqua has no contact field for …" A condition tests a recipient field that Better Email can't match to a contact field. Sync recipient fields from Eloqua, or set the field's ESP field name to a Field Merge that reads a contact field.
• "Eloqua Dynamic Content needs conditions built from Recipient Fields." A variant uses a code segment. Rebuild its condition from recipient fields.
• A second email appeared in Eloqua. The first one was archived or deleted, or the integration now points at another instance. See Syncing again.
• A new field doesn't show up in the Campaign Editor. Synced fields arrive inactive. Switch it on in the Recipient fields tab.

Related docs

• Performance data from Oracle Eloqua
• Integrations
• Recipient Fields / Merge Tags
• Dynamic Content / Segmentation