POST emails/save

Save content and header information for an email. Can pass an email object (i.e. response from /emails/lookup) or just key/value pairs.

* required

Parameters

Name

Type

Description

emailID

integer

Unique ID of email

templateID

integer

ID of template used by email. Set htmlVersionEditable property to true to provide full HTML Version without using a template

userID

integer

ID of system user email belongs to

title

string

Title of email (for internal use)

subject

string

Subject of email

preheader

string

Summary text that follows subject line in the inbox

fromName

string

Name used in From header

fromAddress

email-address

Email address used in From header

replyToName

string

Name used in Reply-to header

replyToAddress

email-address

Email address used in Reply-to header

bccAddress

email-address

Email address that will receive a BCC (blind carbon copy) for every recipient.

recipients

object

contactIDs	array[integer]	Individual contacts assigned to receive the email. For larger sends, add the contacts to a group and send to the group. Max: 1000
excludeGroupIDs	array[integer]	Exclude contacts in these groups from receiving the email
groupIDs	array[integer]	Groups assigned to receive the email

content

object

body_slot1...body_slot10	string	Content for email template slots (1 to 10)
htmlHead	string	Markup that will be placed in the <head> of the HTML version. Only applies to emails using a template that has the htmlHeadEditable property set to true.
htmlVersion	string	HTML version of email. Auto-generated by default using template in conjunction with body_slot* and htmlHead properties. If htmlVersionEditable==true, user can manually set (no template is used)
textVersion	string	Text version of email. Auto-generated by default, but can be manually set

htmlVersionEditable

boolean

If true, no template is used and user provides the full HTML version of email (see htmlVersion property). The HTML Version must contain the unsubscribe link variable: $$url[unsubscribe]. The value of htmlVersionEditable cannot be changed on an existing email.

Default: 0

throttling

object

minimumDeliveryDuration

integer

Number of hours delivery is throttled. 0 means no custom throttling. Only applies to emails with manual delivery type.

tracking

object

clicksEnabled	boolean	Track which links were clicked and who did the clicking
viewsEnabled	boolean	Embed an invisible image in email that tracks who viewed

Response Data

Returns a full representation of an email (same as when doing a lookup)

Name

Type

Description

abSplit

object

A/B split details

abSplitID	integer	ID of A/B split
parentEmailID	integer	ID of parent email
testEmailIDs	array[integer]	IDs of test emails
winnerEmailID	integer	ID of winner email

approval

object

approvalsCurrent	integer	Number of users who have approved email
approvalsNeeded	integer	Number of users who must approve email
approved	boolean	Overall approved status
requiresApproval	boolean	Indicates if email requires approval (can vary based on user and template settings)
users	array	Array of objects containing approval data per user

automation

object

Automation settings. Automated emails cannot be managed via the API.

active	boolean	Is automation active?
recipientDelay	integer	Delay (in minutes) before contacts will receive email
schedule	array	Array of objects with daily schedule details. e.g. [{"dayOfWeek":1,"scheduledSendTime": "07:00:00"},{"dayOfWeek":2,"scheduledSendTime": "07:00:00"},etc...]

bccAddress

string

Email address that will receive a BCC (blind carbon copy) for every recipient.

content

object

body_slot1...body_slot10	string	Content for email template slots (1 to 10)
htmlHead	string	Markup that will be placed in the <head> of the HTML version. Only applies to emails using a template that has the htmlHeadEditable property set to true.
htmlVersion	string	HTML version of email. Auto-generated by default using template in conjunction with body_slot* and htmlHead properties. If htmlVersionEditable==true, user can manually set (no template is used)
textVersion	string	Text version of email. Auto-generated by default, but can be manually set

dateAdded

datetime

Date record was added

dateModified

datetime

Date record was modified

dateSent

datetime

Date email was sent

deliveryType

string

How email gets delivered. One of: Manual, Automated, Transactional

emailID

integer

Unique ID of email

fromAddress

string

Email address used in From header

fromName

string

Name used in From header

htmlVersionEditable

boolean

ignoreContactSuppression

boolean

Indicates whether or not suppressed contacts can receive the email. Applies to transactional emails only.

metrics

object

Summary deliverability metrics

bounces	integer	Total number of bounces
clickToViewRate	decimal	Percentage of unique contacts who viewed the email and also clicked (unique views / unique clicks)
clicks	integer	Total number of clicks
complaints	integer	Total number of spam complaints
forwards	integer	Total number of forwards (forward-to-friend)
recipients	integer	Total email recipients
sendingIssues	integer	Total number of sending issues
shares	integer	Total number of shares
uniqueClicks	integer	Unique contacts that clicked a link
uniqueForwards	integer	Unique contacts that forwarded email
uniqueShares	integer	Unique contacts that shared email
uniqueViews	integer	Unique contacts that viewed email
uniqueWebViews	integer	Unique contacts that viewed as a web page
unsubscribes	integer	Total number of unsubscribes
views	integer	Total number of views
webViews	integer	Total number of web views

parentEmailID

integer

ID of parent email record

preheader

string

Summary text that follows subject line in the inbox

recipients

object

contactIDs	array[integer]	Individual contacts assigned to receive the email. For larger sends, add the contacts to a group and send to the group.
excludeGroupIDs	array[integer]	Exclude contacts in these groups from receiving the email
groupIDs	array[integer]	Groups assigned to receive the email

replyToAddress

string

Email address used in Reply-to header

replyToName

string

Name used in Reply-to header

schedule

object

confirmed	boolean	Is schedule delivery confirmed?
dateScheduled	datetime	Date/time of scheduled delivery

status

string

Current status of email delivery. One of: Draft, Sent, Scheduled

subject

string

Subject of email

templateID

integer

ID of template used by email. Set htmlVersionEditable property to true to provide full HTML Version without using a template

throttling

object

Throttling settings

minimumDeliveryDuration

integer

Number of hours delivery is throttled. 0 means no custom throttling. Only applies to emails with manual delivery type.

title

string

Title of email (for internal use)

tracking

object

Tracking options

clicksEnabled	boolean	Track which links were clicked and who did the clicking
viewsEnabled	boolean	Embed an invisible image in email that tracks who viewed

userID

integer

ID of system user email belongs to

Permissions

Method requires the Compose Mail permission

Example Calls

Create email using template

New emails must have at least the following defined: templateID,subject,fromName,fromAddress

POST

/emails/save

cURL

Copy

curl https://api.emailer.emfluence.com/v1/emails/save \
	-H "Authorization: Bearer {{accessToken}}" \
	-H "Content-Type: application/json" \
	-X POST \
	-d '{
		"title": "Monthly Newsletter",
		"fromName": "ACME",
		"fromAddress": "sample@example.com",
		"subject": "Check out the latest news!",
		"templateID": 123,
		"recipients": {
			"groupIDs": [123]
		},
		"content": {
			"body_slot1": "Banner content goes here...",
			"body_slot2": "Main content goes here..."
		}
	}'

Response Data

{"success":1,"data":{"subject":"Check out the latest news!","dateAdded":"2014-03-26 21:49:28","fromName":"ACME","automation":{},"recipients":{"groupIDs":[123],"contactIDs":[]},"schedule":{"dateScheduled":"","confirmed":0},"dateModified":"2014-03-26 21:49:28","dateSent":"","status":"Draft","emailID":123,"approval":{"users":[{"name":"super admin","comments":"","date":"","approved":"","userID":123}],"approvalsCurrent":0,"approved":1,"requiresApproval":0,"approvalsNeeded":0},"content":{"body_slot3":"","body_slot10":"","body_slot4":"","body_slot5":"","body_slot6":"","body_slot7":"","body_slot8":"","body_slot9":"","textVersion":"emfluence, llc\r\nBanner content goes here...\r\nMain content goes here...","body_slot1":"Banner content goes here...","htmlVersion":"<html><head><title>emfluence, llc</title></head><body><h1>Banner content goes here...</h1><p>Main content goes here...</p></body></html>","body_slot2":"Main content goes here..."},"templateID":123,"deliveryType":"Manual","parentEmailID":"","metrics":{"views":0,"forwards":0,"uniqueViews":0,"webViews":0,"recipients":0,"bounces":0,"uniqueClicks":0,"uniqueForwards":0,"shares":0,"clicks":0,"complaints":0,"unsubscribes":0,"uniqueWebViews":0,"uniqueShares":0},"fromAddress":"sample@example.com","replyToName":"","replyToAddress":"","bccAddress":"","title":"Monthly Newsletter","userID":123},"code":0,"requestID":"2E0401A3-51A5-4292-B56A6D8A993347B7"}

Create email without a template

When not using a template, set htmlVersionEditable=1 and set htmlVersion to the full HTML document

POST

/emails/save

cURL

Copy

curl https://api.emailer.emfluence.com/v1/emails/save \
	-H "Authorization: Bearer {{accessToken}}" \
	-H "Content-Type: application/json" \
	-X POST \
	-d '{
			"title": "Monthly Newsletter",
			"fromName": "ACME",
			"fromAddress": "sample@example.com",
			"subject": "Check out the latest news!",
			"recipients": {
				"groupIDs": [123]
			},
			"htmlVersionEditable": 1,
			"content": {
					"htmlVersion": "<html><body><p>This is the html version of the email</p><p><a href="$$url[unsubscribe]">Unsubscribe</a></p></body></html>"
			}
		}'

Response Data

{"success":1,"data":{"emailID":123,"...":"Full email object returned"},"code":0,"requestID":"9FB8D451-7BD2-4EEA-B43F555FAA7164ED"}

Update single email property

Updates can pass in just the changes

POST

/emails/save

cURL

Copy

curl https://api.emailer.emfluence.com/v1/emails/save \
	-H "Authorization: Bearer {{accessToken}}" \
	-H "Content-Type: application/json" \
	-X POST \
	-d '{
		"emailID": 123,
		"subject": "New subject line"
	}'

Response Data

{"success":1,"data":{"emailID":123,"...":"Full email object returned"},"code":0,"requestID":"C8788A56-B768-4A2F-AFD13C2488017162"}

Update email using object

Updates can pass in a fully populated email object. An email object can be obtained by calling emails/lookup. They are also returned after a save operation.

POST

/emails/save

cURL

Copy

curl https://api.emailer.emfluence.com/v1/emails/save \
	-H "Authorization: Bearer {{accessToken}}" \
	-H "Content-Type: application/json" \
	-X POST \
	-d '{
     "subject": "Check out the latest news!",
     "dateAdded": "2014-03-26 21:49:28",
     "fromName": "ACME",
     "automation": {},
     "recipients": {
         "groupIDs": [
             123
         ],
         "contactIDs": []
     },
     "schedule": {
         "dateScheduled": "",
         "confirmed": 0
     },
     "dateModified": "2014-03-26 21:49:28",
     "dateSent": "",
     "status": "Draft",
     "emailID": 123,
     "approval": {
         "users": [
             {
                 "name": "super admin",
                 "comments": "",
                 "date": "",
                 "approved": "",
                 "userID": 123
             }
         ],
         "approvalsCurrent": 0,
         "approved": 1,
         "requiresApproval": 0,
         "approvalsNeeded": 0
     },
     "content": {
         "body_slot3": "",
         "body_slot10": "",
         "body_slot4": "",
         "body_slot5": "",
         "body_slot6": "",
         "body_slot7": "",
         "body_slot8": "",
         "body_slot9": "",
         "textVersion": "emfluence, llc\r\nBanner content goes here...\r\nMain content goes here...",
         "body_slot1": "Banner content goes here...",
         "htmlVersion": "<html><head><title>emfluence, llc</title></head><body><h1>Banner content goes here...</h1><p>Main content goes here...</p></body></html>",
         "body_slot2": "Main content goes here..."
     },
		 "htmlVersionEditable": 0,
     "templateID": 123,
     "deliveryType": "Manual",
     "parentEmailID": "",
     "metrics": {
         "views": 0,
         "forwards": 0,
         "uniqueViews": 0,
         "webViews": 0,
         "recipients": 0,
         "bounces": 0,
         "uniqueClicks": 0,
         "uniqueForwards": 0,
         "shares": 0,
         "clicks": 0,
         "complaints": 0,
         "unsubscribes": 0,
         "uniqueWebViews": 0,
         "uniqueShares": 0
     },
     "fromAddress": "sample@example.com",
     "replyToName": "",
     "replyToAddress": "",
     "bccAddress": "",
     "title": "Monthly Newsletter",
     "userID": 123
 }'

Response Data

{"success":1,"data":{"emailID":123,"...":"Full email object returned"},"code":0,"requestID":"BA9A9CD8-106F-4D64-9CA1479CF6F4969D"}

API Console

The console uses production data, so BE CAREFUL!

POST

emails/save

Request Body

{"content":{},"templateID":0,"replyToAddress":"","userID":0,"fromAddress":"","recipients":{},"preheader":"","subject":"","throttling":{},"tracking":{},"fromName":"","htmlVersionEditable":"0","emailID":0,"replyToName":"","title":"","bccAddress":""}

Access token: *

Emails

POST emails/save

Parameters

Response Data

Permissions

Example Calls

Create email using template

Create email without a template

Update single email property

Update email using object

API Console