Send an Email

To simplify job creation, Docoon REST API provides to you a specific resource per media. For Email jobs only the resource is called “EmailJobs”.

We will review how to send quickly an Email with one recipient or many recipients. We will also review the Email advanced parameters and the text personnalisation of the email body.

When the Email job request is accepted, you will get a jobNumber, it means a job was accepted and was put in the appropriate queue (depending on your priority defined in your contract), we will send the message to each recipient as soon as possible depending of the current traffic.

When the job is finished, you will be able to check the transmission status of each recipient, check “Get transmission reports” easy worflow for more information.

Send Email request informations

Name: /EmailJobs
Type: POST

Headers:

Parameters list:

Structure details of AdhocRecipients

This Object is used to list your recipient in the “AdhocRecipients”

Structure details of FileReference

The object File Reference is used for both list and documents, The structure is the same but you have to select the right “Type” depending of your document.

{
	"JobType": "Email",
	"TrackingId": "Send basic Email",
	"EmailBody": {
		"Name": "body.html",
		"Content": "PGh0bWw+DQo8aGVhZGVyPg0KPG1ldGEgY2hhcnNldD0iVVRGLTgiPg0KPC9oZWFkZXI+DQo8Ym9keT4NClRoaXMgaXMgYW4gZW1haWwgdGVzdCBmcm9tIE9keXNzZXkgTWVzc2FnaW5nLg0KPC9ib2R5Pg0KPC9odG1sPg==",
		"Type":2
	},
	"AdhocRecipients" : [
		{
			"Address":"usern@gmail.com",
			"Name":"John",
			"OptionalFields": [
				"My Company",
				"BirthDate"
			]
		}
	],
	"Parameter": {
		"Media" : 5,
		"Subject": "My Email subject",
		"ReplyTo":"support@myCompany.com"
	}
}

Email advanced parameters description

In addition to the parameters presented above, there are advanced parameters allowing to configure specific parameters to Email sending (subject, reply-to, from address, …).

{
	"JobType": "Email",
	"TrackingId": "Send Email with advanced parameters",
	"EmailBody": {
		"Name": "body.html",
		"Content": "PGh0bWw+DQo8aGVhZGVyPg0KPG1ldGEgY2hhcnNldD0iVVRGLTgiPg0KPC9oZWFkZXI+DQo8Ym9keT4NClRoaXMgaXMgYW4gZW1haWwgdGVzdCBmcm9tIE9keXNzZXkgTWVzc2FnaW5nLg0KPGJyLz4NCjxhIGhyZWY9Imh0dHA6Ly93d3cub2R5c3NleS1tZXNzYWdpbmcuY29tIj5UaGlzIGlzIGEgbGluayB0byB0ZXN0IHRoZSB0cmFja2luZyBvcHRpb248L2E+DQo8L2JvZHk+DQo8L2h0bWw+",
		"Type":2
	},
	"AdhocRecipients": [
		{
			"Address":"usern@gmail.com",
			"Name":"John",
			"OptionalFields": [
				"My Company",
				"BirthDate"
			]
		}
	],
	"Attachments": [
		{
			"Name": "Attachment1.txt",
			"Content": "VGhpcyBpcyBhbiBhdHRhY2hlbWVudCBmaWxl",
			"Type":4
		}
	],
	"Parameter": {
		"Media" : 5,
		"Subject": "My Email subject",
		"ReplyTo":"support@myCompany.com",
		"From":"\"Mycompany\" <MyCompany@ods2.net>",
		"ActivateAutoPull": true,
		"ActivateTracking": true
	}
}

Send an Email using a file list

You can also use a file list for your recipient. You will have to replace the “AdhocRecipients” list by a “Lists” of File Reference (see the structure above). List format accepted : .xlsx, .xls, .csv, .tab.

By Default, the email address should be in the first column of the first (and only) sheets of your file.
The other columns can be used for personalizations.

{
	"JobType": "Email",
	"TrackingId": "Send Email with file list",
	"EmailBody": {
		"Name": "body.html",
		"Content": "PGh0bWw+DQo8aGVhZGVyPg0KPG1ldGEgY2hhcnNldD0iVVRGLTgiPg0KPC9oZWFkZXI+DQo8Ym9keT4NClRoaXMgaXMgYW4gZW1haWwgdGVzdCBmcm9tIE9keXNzZXkgTWVzc2FnaW5nLg0KPC9ib2R5Pg0KPC9odG1sPg==",
		"Type":2
	},
	"Lists": [
		{
			"Name": "test.tab",
			"Type":0,
			"Content": "dXNlcm5AZ21haWwuY29tCUpvaG4JTXkgQ29tcGFueQlCaXJ0aERhdGU="
		}
	],
	"Parameter": {
		"Media" : 5,
		"Subject": "My Email subject",
		"ReplyTo":"support@myCompany.com"
	}
}

Sucessful response

Status: 200 : OK

Parameters list:

{
  "JobNumber": 44608862
}

Error response

Status: 400: Bad request

{
  "Message": "The request is invalid.",
  "ModelState": {
    "job": [
      "An error has occurred."
    ]
  }
}

More Usage Examples

Message personalization

You can personalize your Email body using “`BCFX” values. X being the position of the data you want to send.
For Adhoc sending, `BCF1 is the email address,`BCF2 is the Name, `BCF3 the first optional field, `BCF4 the second optional field, …
For List sending, the number is the position in the column. `BCF1 is the first column (usually the email address), `BCF2 is the second column, …

In the following AdHoc Sample,
We use the text : “Hi `BCF2, Are you from `BCF3 ?”
the resulting test of the 1st Recipient will be : “Hi Dupont, Are you from Company A ?”.
the resulting test of the 2nd Recipient will be : “Hi James, Are you from Company B ?”.

{
	"JobType": "Email",
	"TrackingId": "Send Email with personalisation",
	"EmailBody": {
		"Name": "body.html",
		"Content": "PGh0bWw+DQo8aGVhZGVyPg0KPG1ldGEgY2hhcnNldD0iVVRGLTgiPg0KPC9oZWFkZXI+DQo8Ym9keT4NCkhpIGBCQ0YyLCBBcmUgeW91IGZyb20gYEJDRjMgPw0KPC9ib2R5Pg0KPC9odG1sPg==",
		"Type":2
	},
	"AdhocRecipients": [
		{
			"Address":"usern@gmail.com",
			"Name":"Dupont",
			"OptionalFields": [
				"Company A",
				"BirthDate"
			]
		},
		{
			"Address":"usern@gmail.com",
			"Name":"James",
			"OptionalFields":[
				"Company B",
				"BirthDate"
			]
		}
	],
	"Parameter":{
		"Media" : 5,
		"Subject": "My Email subject",
		"ReplyTo":"support@myCompany.com"
	}
}

Scheduled job

Use the “ScheduledStartTime” value to delay your sending.
In our example you will send a message the 1st of January 2019.

{
	"JobType": "Email",
	"TrackingId": "Send a scheduled Email",
	"ScheduledStartTime": "2019-01-01T00:00:00.688Z", 
	"EmailBody": {
		"Name": "body.html",
		"Content": "PGh0bWw+DQo8aGVhZGVyPg0KPG1ldGEgY2hhcnNldD0iVVRGLTgiPg0KPC9oZWFkZXI+DQo8Ym9keT4NClRoaXMgaXMgYW4gZW1haWwgdGVzdCBmcm9tIE9keXNzZXkgTWVzc2FnaW5nLg0KPC9ib2R5Pg0KPC9odG1sPg==",
		"Type":2
	},
	"AdhocRecipients" : [
		{
			"Address":"usern@gmail.com",
			"Name":"John",
			"OptionalFields": [
				"My Company",
				"BirthDate"
			]
		}
	],
	"Parameter": {
		"Media" : 5,
		"Subject": "My Email subject",
		"ReplyTo":"support@myCompany.com"
	}
}

Use Email Template created from customer portal

You can use a template email created on the email body editor (on customer portal) as an email body. To do that, on the FileReference of the email body you have to specified the name of the template into the field “Name” and put the field “Hosted” to true.

{
	"JobType": "Email",
	"TrackingId": "Send a scheduled Email",
	"ScheduledStartTime": "2019-01-01T00:00:00.688Z", 
	"EmailBody": {
		"Name": "TemplateName",
		"Hosted": True,
		"Type":2
	},
	"AdhocRecipients" : [
		{
			"Address":"usern@gmail.com",
			"Name":"John",
			"OptionalFields": [
				"My Company",
				"BirthDate"
			]
		}
	],
	"Parameter": {
		"Media" : 5,
		"Subject": "My Email subject",
		"ReplyTo":"support@myCompany.com"
	}
}