How To: Send marketing emails Send transactional emails Send automated emails
Building Email Content
Emails are created and sent using the endpoints emails/save + emails/send or emails/sendTransactional. You can code your own (provide the full HTML document) or use a pre-built template.
Using Templates
Templates are currently managed solely through the emfluence Marketing Platform. To find out what templates are available for your account, use templates/search. For full details on a given template, use templates/lookup. The lookup call will return everything about the template, including the HTML and Text versions.
Editable Areas <emflcontent>
Editable areas define what parts of the template can be edited when composing an email.
Editable areas are created with <emflcontent> tags.
<emflcontent> Tag Attributes
| Attribute | Description |
|---|---|
| body_slot | ID of editable area. Corresponds to body_slot property on an email. |
| name | Friendly name. Useful for identifying editable area's purpose/usage (e.g. header, footer...) |
Sample Template
Here is an example of a template with a single editable area with a body_slot (ID) of "1".
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>ACME Updates</title>
</head>
<body>
<h1>ACME Updates</h1>
<p>Here are this month's updates:</p>
<!-- main-content will be editable by users -->
<emflcontent body_slot="1" name="main-content"></emflcontent>
<p>You are currently subscribed as $$email. <a href="$$url[unsubscribe]">Unsubscribe</a></p>
<p>
$$account[name]<br />
$$account[address]<br />
$$account[city], $$account[state] $$account[zip]
</p>
</body>
</html>
Populating Content
To populate content for an email, you must provide both a templateID and the HTML for each body_slot[x] parameter that corresponds with your template's editable areas.
Code Your Own (no template)
HTML Version
When coding your own email, you provide the full HTML version along with a flag indicating you are not using a template. You do not need to pass individual body_slot[x] parameters, those are only used in conjunction with a template.
The HTML version must be a complete HTML document containing opening and closing <html> and <body> tags as well meet CAN-SPAM requirements.
Text Version
All HTML emails are multi-part meaning there is a plain-text version as well as an HTML version. You can specify the plain-text version or let the system automatically generate it from the HTML version.
Permissions
If creating an email without a template, the user must have "Client Administrator" or "Email Coder" permissions. You can check a user's permissions with the users/self endpoint.
CAN-SPAM Law
By sending marketing emails through the emfluence Marketing Platform you are agreeing that your emails are CAN-SPAM compliant. Read more about CAN-SPAM law.
CAN-SPAM law requires all marketing emails to contain an unsubscribe link and a physical address*.
Your email must contain the unsubscribe variable: $$url[unsubscribe]. e.g. <a href="$$url[unsubscribe]">Unsubscribe</a>
Your email must also contain your physical address. You can manually enter the address in the HTML or use the address registered with your account with these variables:
- $$account[address]
- $$account[city]
- $$account[state]
- $$account[zip]
*Transactional emails are not required to include an unsubscribe link or a physical address. See emails/sendTransactional if you are sending a transactional email.
Variables
Variables can be used within the email body as well as the subject line.
Contact Variables
Contact data is referenced in emails using variables. Contact data can be set using contacts/save and contacts/import as well as when sending transactional emails using emails/sendTransactional.
See contacts/lookup for more information about each field.
| Field | Variable |
|---|---|
| Contact ID | $$contactID |
| First Name | $$firstName |
| Last Name | $$lastName |
| Email Address | |
| Street Address 1 | $$address1 |
| Street Address 2 | $$address2 |
| City | $$city |
| State | $$state |
| Zip/Postal Code | $$zip |
| Country | $$country |
| Phone | $$phone |
| Fax | $$fax |
| Job Title | $$title |
| Company | $$company |
| Your system's customer ID | $$customerID |
| Date of Birth | $$dateofbirth |
| Memo | $$memo |
| Custom Fields 1-X. Custom fields are defined per account. Make a call to customFields/search for available custom fields. | $$custom01-$$customX |
| Content Variables 1-10 | $$content01-$$content10 |
Account Variables
Account variables represent the client account the email belongs to.
| Field | Variable |
|---|---|
| Name | $$account[name] |
| City | $$account[city] |
| State | $$account[state] |
| Zip Code | $$account[zip] |
| Street Address | $$account[address] |
| Street Address Line 2 | $$account[address2] |
User Variables
User variables represent the system user who owns the email. Emails are owned by the user who created/sent the email.
| Field | Variable |
|---|---|
| userID | $$user[userID] |
| Username | $$user[username] |
| First Name | $$user[firstName] |
| Last Name | $$user[lastName] |
| $$user[email] | |
| Company | $$user[company] |
| Title | $$user[title] |
| Phone | $$user[phone] |
| Alt Phone | $$user[phone2] |
| Fax | $$user[fax] |
| Street Address | $$user[address] |
| Street Address Line 2 | $$user[address2] |
| City | $$user[city] |
| State | $$user[state] |
| Zip Code | $$user[zip] |
| Business Unit | $$user[businessUnit] |
| Business Hours | $$user[businessHours] |
| URL | $$user[url] |
Link Variables
Link variables represent URLs to system pages. These variables contain recipient-specific data and therefore the full URL cannot be known until send time.
| Link | Variable |
|---|---|
| Unsubscribe | $$url[unsubscribe] |
| Forward to a Friend | $$url[forwardtofriend] |
| View as Webpage | $$url[viewaswebpage] |
Examples
Create email using template with one editable area
Create email without using a template
When not using a template, set htmlVersionEditable=1 and set htmlVersion to the full HTML document
Update existing email using template with multiple editable areas
Send transactional email with a template
Create a contact record and send an email in a single call. It should be noted that with this particular example, the same result could be achieved by simply putting the contact's information directly into the content of the email (rather than using variables). Using variables works best when working with email templates that contain reusable content.
Send transactional email without a template
Create a contact record and send an email in a single call. It should be noted that with this particular example, the same result could be achieved by simply putting the contact's information directly into the content of the email (rather than using variables). Using variables works best when working with email templates that contain reusable content.