POST emails/sendTransactional

Send a transactional email to a limited number of contacts in a single call. Transactional emails contain information that completes a transaction or process the recipient has started with you. This endpoint should never be used to send marketing emails. To include suppressed contacts, be sure to use the ignoreContactSuppression flag. NOTE: This endpoint must be enabled for your account before use. Please contact support for access.

* required

Parameters

Name

Type

Description

email *

object

Email object. See emails/save for object structure.

contacts

array

Array of contact objects. See contacts/save for object structure. Duplicates (either by contactID or email address) will be ignored (first occurrence will be used). Existing contacts will be updated with data provided.

Max: 5

contactIDs

array[integer]

Array of contactIDs.

Max: 1000

transactionalCategory

string

Name of a Transactional Category (i.e. "Order Confirmation" or "Password Reset"). Used for grouping transactional emails for reporting purposes. If the value provided does not match any existing category names, a new category will be created.

ignoreContactSuppression

boolean

Allows suppressed contacts to receive the email. Transactional emails are intended to complete a transaction or process the recipient has started.

Default: 0

Response Data

Name	Type	Description
emailID	integer	ID of email record
contacts	array	Array of objects containing keys for "success" (1 or 0) and "contact". Contact is simply the contact data that was originally passed in with the contactID appended. If success = 0, a reason is provided. e.g. [{"success": 1, "contact": {"contactID": 1772977, "email": "test@emfluence.com"}}, {"success": 0, "reason": "Duplicate", "contact": {"contactID": 1772977, "email": "test@emfluence.com"}}

Permissions

Method requires the Send Mail permission

Example Calls

Successful send

Custom field on contact is set and variable is used in body of email.

POST

/emails/sendTransactional

cURL

Copy

curl https://api.emailer.emfluence.com/v1/emails/sendTransactional \
	-H "Authorization: Bearer {{accessToken}}" \
	-H "Content-Type: application/json" \
	-X POST \
	-d '{
	"email": {
		"fromName": "ACME",
		"fromAddress": "sample@example.com",
		"subject": "Thanks for your order!",
		"templateID": 1000,
		"body_slot1": "Your order number is $$custom01!",
		"transactionalCategory": "Order confirmations",
		"ignoreContactSuppression": 1
	},
	"contacts": [
		{"email":"test@example.com","customFields": {"custom1": {"value":"123"}}}
	]
}'

Response Data

{"success":1,"data":{"emailID":1000,"contacts":[{"status":"Success","contact":{"contactID":10000,"firstName":"John","lastName":"Doe","email":"test@example.com"}},{"status":"Failed","reason":"Duplicate email","contact":{"email":"test@example.com"}}]},"code":0,"requestID":"113B7A91-9506-4F54-AB5E9EECC12C54EF"}

Successful send without a template

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

POST

/emails/sendTransactional

cURL

Copy

curl https://api.emailer.emfluence.com/v1/emails/sendTransactional \
	-H "Authorization: Bearer {{accessToken}}" \
	-H "Content-Type: application/json" \
	-X POST \
	-d '{
		"email": {
			"fromName": "ACME",
			"fromAddress": "sample@example.com",
			"subject": "Thanks for your order!",
			"htmlVersionEditable": 1,
			"content": {
				"htmlVersion": "<html><body><h1>Order receipt</h1><p>Your order number is 123</p></body></html>"
			},
			"transactionalCategory": "Order confirmations",
			"ignoreContactSuppression": 1
		},
		"contacts": [
			{"email":"test@example.com"}
		]
	}'

Response Data

{"success":1,"data":{"emailID":1000,"contacts":[{"status":"Success","contact":{"contactID":10000,"firstName":"John","lastName":"Doe","email":"test@example.com"}},{"status":"Failed","reason":"Duplicate email","contact":{"email":"test@example.com"}}]},"code":0,"requestID":"61D5B12B-3EE3-48DC-9877494C17A5292B"}

Duplicate recipients

Call succeeds, even though one of the recipients failed as a duplicate.

POST

/emails/sendTransactional

cURL

Copy

curl https://api.emailer.emfluence.com/v1/emails/sendTransactional \
	-H "Authorization: Bearer {{accessToken}}" \
	-H "Content-Type: application/json" \
	-X POST \
	-d '{
	  "email": {

	    "fromName": "ACME",
		"fromAddress": "sample@example.com",
		"subject": "Thanks for your order!",
		"templateID": 1000,
	    "body_slot1": "Your order number is 123!"
	  },
	  "contacts": [
	    	{"email":"test@example.com","firstName": "John", "lastName": "Doe"},
	    	{"email":"test@example.com"}
	 	]
	}'

Response Data

{"success":1,"data":{"emailID":1000,"contacts":[{"status":"Success","contact":{"contactID":10000,"firstName":"John","lastName":"Doe","email":"test@example.com"}},{"status":"Failed","reason":"Duplicate email","contact":{"email":"test@example.com"}}]},"code":0,"requestID":"7D3C0FAE-CE77-48EF-A15025DAF3FF3F82"}

Invalid recipient

Call fails because the recipient email is invalid.

POST

/emails/sendTransactional

cURL

Copy

curl https://api.emailer.emfluence.com/v1/emails/sendTransactional \
	-H "Authorization: Bearer {{accessToken}}" \
	-H "Content-Type: application/json" \
	-X POST \
	-d '{
	  "email": {
	    "fromName": "ACME",
		"fromAddress": "sample@example.com",
		"subject": "Thanks for your order!",
		"templateID": 1000,
	    "body_slot1": "Your order number is 123!"
	  },
	  "contacts": [
	    	{"email":"test@example-com"}
	 	]
	}'

Response Data

{"success":0,"errors":["Contact object at position 1 had an error.  Parameter \"email\" has an invalid value (test@example-com) for the data type \"email-address\""],"data":{},"code":500,"requestID":"63D9683C-DA17-4C09-A5052DACD73B1A91"}

API Console

The console uses production data, so BE CAREFUL!

POST

emails/sendTransactional

Request Body

{"ignoreContactSuppression":"0","transactionalCategory":"","contactIDs":"","contacts":[],"email":{}}

Access token: *

Emails

POST emails/sendTransactional

Parameters

Response Data

Permissions

Example Calls

Successful send

Successful send without a template

Duplicate recipients

Invalid recipient

API Console