Ekopost API
a thorough description of our API, from how to authorize to create and schedule an envelope for print & distribution, and more.
a thorough description of our API, from how to authorize to create and schedule an envelope for print & distribution, and more.
The REST API provide programmatic access to read and write Ekopost data. Create a new campaign, envelope, scheduele print & distribution, and more. The REST API identifies applications and users using Basic Authentication; responses are available in JSON.
If you're using .NET Framework you can download and install our nuget package directly, see the section Tools for more information.
During development and testing we recommend using our Sandbox Environment, see the section Sandbox for more information.
The REST API is only using JSON; all requests body should be in JSON and all responses will be JSON.
Make sure you set Request.Header.Content-Type
to “application/json”.
Content-Type: application/json; charset=UTF-8
UTF8 is the encoding that should be used at all times.
The API uses basic authorization, and all requests must be authorized at all times.
You can use a valid api-key or a base64 encoded string based on your user credentials to build the authorize header value. We recommend that you always use the api-key apprach over the base64 encoded string, as you can create/revoke/reactive/remove api-keys with ease while using the base64 approach your integrations may fail if the password of the used account would ever be changed.
Set the Request.Header.Authorization
value to “api-key key”, to get your key you need to generate a new API key after you've signed in to your account, you'll be able to generate and manage your API keys from the account/api section.
Authorization: api-key YiuyotGtRNDXik56lgq6
Content-Type: application/json; charset=UTF-8
Set the Request.Header.Authorization
value to “Basic auth_token”, auth_token should be replaced with a base64 encoded string formatted like: "username:password", where username is your username and password is your password.
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
All handled errors will result in bad request (code: 400) and the body will contain an error object for debugging and development purpose with further information how to validate the request, you can see a list of error codes in the section Error under Error code values.
Resources not found will result in not found (code: 404) and any unhandled exception will return internal error (code: 500).
To send an envelope you must first create a campaign, then an envelope within that campaign, then create a content (read: upload a document/attachment) within that envelope, once this is done you'll have to close both the campaign and the envelope/s to mark them as ready for production, each envelope in the campaign will be printed & distributed as an individual postal item, the items will be printed & distributed on the campaign output date.
To schedule print and distribution of a envelope – follow these steps (all requests must be authorized).
The Content object field named data must be a PDF version 1.4, support for later versions does exist, but printing quality nor result can not be guaranteed without testnig. We always recommend that you send your self a copy of the documents you'll be sending to inspect the result, any deviations should be reported to our support team.
Download our content template to learn about our page margins, reserved page areas and where to place your destination adress and return adress for optimal visibility.
Campaigns allow for easy management of multiple envelopes and set a date when content should be distributed.
Creates a new campaign with state opened.
POST /campaigns
Parameter | Type | Description |
---|---|---|
name | String | A friendly name to identify the campaign. |
output_date | Date | Date in UTC format representing the date when you would like your envelope printed & distributed. |
cost_center | String | Value representing an internal cost center. |
POST /campaigns HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
{
"name": "Invoice March 2015",
"output_date": "2015-06-01T12:00:00",
"cost_center": "Finance Office"
}
Parameter | Type | Description |
---|---|---|
id | Guid | The campaign object's unique id. |
name | String | A friendly name to identify the campaign. |
output_date | Date | Date in UTC format representing the date when you would like your envelope printed & distributed. |
cost_center | String | Value representing an internal cost center. |
envelope_count | Int | Value representing the total number of envelopes in the campaign. |
state | String | State type denominator, see the section State values for valid values. |
state_changed_at | Date | Date in UTC format representing the date when the campaign state was changed. |
created_at | Date | Date in UTC format representing the date when the campaign was created. |
signing | Boolean | Value showing if campaign has envelopes with digital agreement. |
HTTP/1.1 200 OK
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
{
"id": "4ebeab48-ee03-474f-bc79-c6db082c2bad",
"name": "Invoice March 2015",
"output_date": "2015-01-01T12:00:00",
"cost_center": "Finance Office",
"envelope_count": 1,
"state": "opened",
"state_changed_at": "2015-01-01T12:00:00",
"created_at": "2015-01-01T12:00:00",
"signing": "false"
}
Changes a campains state to closed and marks it and all related envelopes as ready for print & distribution.
POST /campaigns/{campaign_id}/close
Parameter | Type | Description |
---|---|---|
campaign_id | Guid | Guid that represents the specified campaign of which to change state to closed. |
POST /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/close HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
HTTP/1.1 200 OK
Changes a campains state to cancelled and marks it and all related envelopes as not ready for print & distribution.
POST /campaigns/{campaign_id}/cancel
Parameter | Type | Description |
---|---|---|
campaign_id | Guid | Guid that represents the specified campaign of which to change state to cancelled. |
POST /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/cancel HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
HTTP/1.1 200 OK
Gets a campaign.
GET /campaigns/{campaign_id}
Parameter | Type | Description |
---|---|---|
campaign_id | Guid | Unique id of the campaign to retrieve. |
GET /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
Parameter | Type | Description |
---|---|---|
id | Guid | The campaign object's unique id. |
name | String | A friendly name to identify the campaign. |
output_date | Date | Date in UTC format representing the date when you would like your envelope printed & distributed. |
cost_center | String | Value representing an internal cost center. |
envelope_count | Int | Value representing the total number of envelopes in the campaign. |
state | String | State type denominator, see the section State values for valid values. |
state_changed_at | Date | Date in UTC format representing the date when the campaign state was changed. |
created_at | Date | Date in UTC format representing the date when the campaign was created. |
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"id": "4ebeab48-ee03-474f-bc79-c6db082c2bad",
"name": "Invoice March 2015",
"output_date": "2015-01-01T12:00:00",
"cost_center": "Finance Office",
"envelope_count": 1,
"state": "opened",
"state_changed_at": "2015-01-01T12:00:00",
"created_at": "2015-01-01T12:00:00"
}
Get a list of all campaigns created within a given timespan.
GET /campaigns?start{start}&stop={stop}&name={name}&state={state}
Parameter | Type | |
---|---|---|
start | Date |
Optional Date in UTC format representing the start of a timespan. Remarks: Default value if not specified is today. |
stop | Date |
Optional Date in UTC format representing the stop of a timespan. Remarks: Default value if not specified is tomorrow. |
name | String | Optional Name of the requested campaign. |
state | String | Optional State type denominator, see the section State values for valid values. |
GET /campaigns?start={start}&stop={stop}&name={name}&state={state} HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
Parameter | Type | Description |
---|---|---|
Array | An array of all Campaigns found within the given timespan. |
The list will be in decending order based on the campaigns created_at date.
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[{
"id": "4ebeab48-ee03-474f-bc79-c6db082c2bad",
"name": "Invoice March 2015",
"output_date": "2015-01-01T12:00:00",
"cost_center": "Finance Office",
"envelope_count": 1,
"state": "opened",
"state_changed_at": "2015-01-01T12:00:00",
"created_at": "2015-01-01T12:00:00"
}]
Envelopes represents a single postal item that will be sent to a single recipient, an envelope can contain one document and several attachments.
Creates a new envelope with state opened linked to the specified campaign.
POST /campaigns/{campaign_id}/envelopes
Parameter | Type | Description |
---|---|---|
campaign_id | Guid | Unique id of a campaign within which to create the envelope. |
Parameter | Type | Description |
---|---|---|
name | String | A friendly name to identify the envelope. |
address | Object |
Address object that represents the destination, see the section Address objects for valid formats.
Remark: In the case of a postal address, the address needs to be embedded into the uploaded document. The one exception to an embedded address is when the flag 'use_coverpage' is lit on the postal address object. A 'null' value will be treated as an address of type postal |
postage | String |
Postage type denominator, see the section Postage values for valid values.
Remark: For customers registered to our Norwegian production site, this parameter can be considered redundant as it is ignored |
plex | String | Plex type denominator, see the section Plex values for valid values. |
color | Boolean | Print the content in color (CMYK), if set to false the content will be printed in black and white. |
agent | String | OptionalFor use when agent |
unique_id | String | OptionalUse with an external id to prevent duplication. Is per customer. |
POST /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/envelopes HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
{
"name": "Invoice 9923891",
"address": null,
"postage": "priority",
"plex": "simplex",
"color": true
}
Parameter | Type | Description |
---|---|---|
id | Guid | The envelope object's unique id. |
name | string | A friendly name to identify the envelope. |
address | Object |
Address object that represents the destination, see the section Address objects for valid formats.
Remark: In the case of a postal address, the address needs to be embedded into the uploaded document. The one exception to an embedded address is when the flag 'use_coverpage' is lit on the postal address object. A 'null' value will be treated as an address of type postal |
postage | String | Postage type denominator, see the section Postage values for valid values. |
plex | String | Plex type denominator, see the section Plex values for valid values. |
color | Boolean | Print the content in color (CMYK), if set to false the content will be printed in black and white. |
state | String | State type denominator, see the section State values for valid values. |
state_changed_at | Date | Date in UTC format representing the date when the envelope state was changed. |
created_at | Date | Date in UTC format representing the date when the envelope was created. |
transaction | Object | Transaction object that the state of the Envelop Transaction object. |
warning | String | Is in response if address is missing. If address is of type postal and the postal address not is complete an extra cost is added. |
agent | String | When agent is used |
unique_id | String | When uniqueId is used |
failed_reason | String | May contain info if state is failed |
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"id": "f6aa0f0a-4514-46e5-be2c-539278a58e70",
"name": "Invoice 9923891",
"address": {
"$type": "postal",
"name": [
"Company Inc.",
"c/o John Doe"
],
"street": [
"Street no. 37"
],
"postal_code": "65421",
"city": "Gothenburg",
"country": "SE",
"use_coverpage": false
},
"postage": "priority",
"plex": "simplex",
"color": true,
"state": "opened",
"state_changed_at": "2015-01-01T12:00:00",
"created_at": "2015-01-01T12:00:00",
"transaction" : {
"state" : "completed",
"state_changed_at" : "2015-01-01T12:00:00"
}
}
Changes an envelopes state to closed and marks it as ready for print & distribution.
POST /campaigns/{campaign_id}/envelopes/{envelope_id}/close
Name | Type | Description |
---|---|---|
campaign_id | Guid | Unique id of a campaign. |
envelope_id | Guid | Unique id of an envelope within the campaign. |
POST /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/envelopes/f6aa0f0a-4514-46e5-be2c-539278a58e70/close HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
HTTP/1.1 200 OK
Changes an envelopes state to cancelled and marks it as not ready for print & distribution.
POST /campaigns/{campaign_id}/envelopes/{envelope_id}/cancel
Name | Type | Description |
---|---|---|
campaign_id | Guid | Unique id of a campaign. |
envelope_id | Guid | Unique id of an envelope within the campaign. |
POST /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/envelopes/f6aa0f0a-4514-46e5-be2c-539278a58e70/cancel HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
HTTP/1.1 200 OK
Gets an envelope. See webhook alternative to get status for envelopes
GET /campaigns/{campaign_id}/envelopes/{envelope_id}
Name | Type | Description |
---|---|---|
campaign_id | Guid | Unique id of a campaign. |
envelope_id | Guid | Unique id of an envelope within the campaign. |
GET /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/envelopes/f6aa0f0a-4514-46e5-be2c-539278a58e70 HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
Parameter | Type | Description |
---|---|---|
id | Guid | The envelope object's unique id. |
name | string | A friendly name to identify the envelope. |
address | Object | Address object that represents the destination, see the section Address objects for valid formats. |
postage | String | Postage type denominator, see the section Postage values for valid values. |
plex | String | Plex type denominator, see the section Plex values for valid values. |
color | Boolean | Print the content in color (CMYK), if set to false the content will be printed in black and white. |
state | String | State type denominator, see the section State values for valid values. |
state_changed_at | Date | Date in UTC format representing the date when the envelope state was changed. |
created_at | Date | Date in UTC format representing the date when the envelope was created. |
transaction | Object | Transaction object that the state of the Envelop Transaction object. |
tracking | Object | If the envelope is a registered letter and is registered it will contain trackinginformation with parcelNo, trackingState and trackingUrl. |
warning | String | Is in response if address is missing. If address is of type postal and the postal address not is complete an extra cost is added. |
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"id": "f6aa0f0a-4514-46e5-be2c-539278a58e70",
"name": "Invoice 9923891",
"address": {
"$type": "postal",
"name": [
"Company Inc.",
"c/o John Doe"
],
"street": [
"Street no. 37"
],
"postal_code": "65421",
"city": "Gothenburg",
"country": "SE"
},
"postage": "priority",
"plex": "simplex",
"color": true,
"state": "opened",
"state_changed_at": "2015-01-01T12:00:00",
"created_at": "2015-01-01T12:00:00",
"transaction" : {
"state" : "completed",
"state_changed_at" : "2015-01-01T12:00:00"
},
"tracking": {
"tracking_state": "Init",
"track_url": https://tracking.postnord.com/se/?id=RRXXXXXXXXSE,
"parcel_no": RRXXXXXXXXSE "
}
}
Gets a list of all envelopes within a campaign.
GET /campaigns/{campaign_id}/envelopes?name={name}&state={state}
Name | Type | Description |
---|---|---|
campaign_id | Guid | Unique id of a campaign. |
name | String | Optional Name of the envelope or envelopes. |
state | String | Optional State type denominator, see the section State values for valid values. |
GET /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/envelopes?name={name}&state={state} HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
Parameter | Type | Description |
---|---|---|
Array | An array of all Envelopes within the campaign. |
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[{
"id": "f6aa0f0a-4514-46e5-be2c-539278a58e70",
"name": "Invoice 9923891",
"address": {
"$type": "postal",
"name": [
"Company Inc.",
"c/o John Doe"
],
"street": [
"Street no. 37"
],
"postal_code": "65421",
"city": "Gothenburg",
"country": "SE"
},
"postage": "priority",
"plex": "simplex",
"color": true,
"state": "opened",
"state_changed_at": "2015-01-01T12:00:00"
"created_at": "2015-01-01T12:00:00",
"transaction" : {
"state" : "completed",
"state_changed_at" : "2015-01-01T12:00:00"
}
}]
Content can either be a document or an attachment linked to an envelope, an envelope can only have one document linked to it, but several attachments, please read the section Limitation for further information.
Creates a content either as a document or attachment linked to the specified envelope, only one document can be linked to an envelope.
POST /campaigns/{campaign_id}/envelopes/{envelope_id}/content
Parameter | Type | Description |
---|---|---|
campaign_id | Guid | Unique id of a campaign within which the envelope exists. |
envelope_id | Guid | Unique id of an envelope to add the content to. |
Parameter | Type | Description |
---|---|---|
data | String |
The original file's data as a base64encoded string. Remark: In case of sms, a base64encoded string of the message text is required. |
mime | String | The original file's mime type. |
length | Int | The original file's size in bytes. |
type | String | Content type denominator, see the Type values section for valid values. |
return_address | Boolean | Optional Set as true to add a return address on the upper left corner of the letter. (The address that will show is the return address on your account.) |
address | Object |
Optional Address object that represents postal destination of returned letters, see the section Address objects. Object (postal) is the valid object.
Remark: For this address to be used as a return address on the letter, return_address must also have the value 'true' |
POST /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/envelopes/f6aa0f0a-4514-46e5-be2c-539278a58e70/content HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
{
"data": "YW55IGNhcm5hbCBwbGVhcw==",
"mime": "application/pdf",
"length": 1024,
"type": "document"
}
POST /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/envelopes/f6aa0f0a-4514-46e5-be2c-539278a58e70/content HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
{
"data": "YW55IGNhcm5hbCBwbGVhcw==",
"mime": "application/pdf",
"length": 1024,
"type": "document",
"return_address" : "true",
"address": null (See Address objects postal for exampel when not null)
}
POST /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/envelopes/f6aa0f0a-4514-46e5-be2c-53+9278a58e70/content HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
{
"data": "YW55IGNhcm5hbCBwbGVhcw==",
"mime": "text/plain",
"length": 1024,
"type": "sms"
}
Parameter | Type | Description |
---|---|---|
id | Guid | The content object's unique id. |
mime | String | The original file's mime type. |
length | Int | The original file's size in bytes. |
type | String | Content type denominator, see the Type values section for valid values. |
created_at | Date | Date in UTC format representing the date when the content was created. |
return_address | Boolean | Value to show if return address was triggered. |
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"id": "d2c5fedd-0749-482c-94b9-7f13bd442a04",
"mime": "application/pdf",
"length": 1024,
"type": "document",
"return_address" : "false",
"created_at": "2015-01-01T12:00:00"
}
Gets an envelope content.
GET /campaigns/{campaign_id}/envelopes/{envelope_id}/content/{content_id}
Name | Type | Description | |
---|---|---|---|
campaign_id | Guid | Unique id of a campaign. | |
envelope_id | Guid | Unique id of an envelope within the campaign. | |
content_id | Guid | Unique id of a content within the envelope. |
POST /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/envelopes/f6aa0f0a-4514-46e5-be2c-539278a58e70/content/d2c5fedd-0749-482c-94b9-7f13bd442a04 HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
Name | Type | Description |
---|---|---|
id | Guid | The content object's unique id. |
mime | String | The original file's mime type. |
length | Int | The original file's size in bytes. |
type | String | Content type denominator, see the Type values section for valid values. |
created_at | Date | Date in UTC format representing the date when the content was created. |
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"id": "d2c5fedd-0749-482c-94b9-7f13bd442a04",
"mime": "application/pdf",
"length": 1024,
"type": "document",
"created_at": "2015-01-01T12:00:00"
}
Through a reachable request you can figure out if a recipient is reachable or not.
Remarks: Returns 404 if the recipient is not reachable.
Remarks: Returns 200 and echoes the recipient parameter if the recipient is reachable.
POST /reachable/{type}
Parameter | Type | Description |
---|---|---|
type | String | The type of address to check reachable status for, valid values are 'einbox', 'ebank' and 'einvoice'. |
Parameter | Type | Description |
---|---|---|
recipient | String | The search parameter used to check reachable status. |
sender | String | Optional FUI or tenantKey, id to use instead of default. |
POST /reachable/ebank HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
{
"recipient": "19800101xxxx"
}
Parameter | Type | Description |
---|---|---|
recipient | String | Indicates success. A recipient has been found. |
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"recipient": "19800101xxxx.BNK.SE"
}
HTTP/1.1 404 NOT FOUND
Content-Type: application/json; charset=UTF-8
Remarks: Returns 404 if the recipient is not reachable.
Remarks: Returns 200 and echoes all reachable addresses.
POST /reachable/ebank_list
Parameter | Type | Description |
---|---|---|
sender | String | The FUI to get ebank receivers for |
POST /reachable/ebank HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
{
"sender": "0000001.000002.SEB.SE",
}
Parameter | Type | Description |
---|---|---|
recipient | Array | An arry of all receivers |
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"identifier": "19800101xxxx",
"address": "19800101xxxx.BNK.SE",
"reachable": true
},
{
"identifier": "19830704xxxx",
"address": "19830704xxxx.BNK.SE",
"reachable": true
}
]
HTTP/1.1 404 NOT FOUND
Content-Type: application/json; charset=UTF-8
Determines whether the setup of Einvoice sendouts is complete. Provides an error messages for various missing setup steps on non-success
POST /reachable/einvoiceready
Parameter | Type | Description |
---|---|---|
ReceiverCin | String | The corporate identity number (org no) of the receiver of an EDI invoice. |
SenderCin | String | The corporate identity number (org no) of the sender of an EDI invoice. |
ReceiverGln | String | The global location number of the receiver of an EDI invoice. |
SenderGln | String | The global location number of the sender of an EDI invoice. |
POST /reachable/einvoiceready HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
{
"ReceiverCin": "800101xxxx",
"SenderCin": "800102xxxx"
}
Parameter | Type | Description |
---|---|---|
ReceiverCin | String | An echo of the input parameter |
SenderCin | String | An echo of the input parameter |
ReceiverGln | String | An echo of the input parameter |
SenderGln | String | An echo of the input parameter |
Success | boolean | A 'true' result indicates that the setup process for einvoice sendouts is complete. |
ErrorMessage | String | A message describing any required missing steps regarding einvoice setup. |
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"ReceiverCin": "800101xxxx",
"SenderCin": "800102xxxx",
"Success": true,
"ErrorMessage": ""
}
This section describes all response objects within the REST API.
Representation of a campaign that will be posted.
Parameter | Type | Description |
---|---|---|
id | Guid | The campaign object's unique id. |
name | String | A friendly name to identify the campaign. |
output_date | Date | Date in UTC format representing the date when you would like your envelope printed & distributed. |
cost_center | String | Value representing an internal cost center. |
envelope_count | Int | Value representing the total number of envelopes in the campaign. |
state | String | State type denominator, see the section State values for valid values.. |
state_changed_at | Date | Date in UTC format representing the date when the campaign state was changed. |
created_at | Date | Date in UTC format representing the date when the campaign was created. |
{
"id": "4ebeab48-ee03-474f-bc79-c6db082c2bad",
"name": "Invoice March 2015",
"output_date": "2015-01-01T12:00:00",
"cost_center": "Finance Office",
"envelope_count": 1,
"state": "opened",
"state_changed_at": "2015-01-01T12:00:00",
"created_at": "2015-01-01T12:00:00"
}
String | Description |
---|---|
opened | The campaign is opened, you can add envelope, modify or change state to cancelled. |
closed | The campaign is marked as ready for production and can not be modified. |
transferred | The campaign and all linked envelopes has been transferred to our production facility. |
completed | The campaign and all linked envelopes has been printed and posted. |
cancelled | The campaign has been closed and all linked envelopes will not be printed or distributed. |
failed | The campaign could not be produced in our facility, contact our customer service for further details. |
Representation of an envelope that will be posted.
Parameter | Type | Description |
---|---|---|
id | Guid | The envelope object's unique id. |
name | string | A friendly name to identify the envelope. |
address | Object |
Address object that represents the destination, see the section Address objects for valid formats.
Remark:In the case of a postal address, the address needs to be embedded into the uploaded document. The one exception to an embedded address is when the flag 'use_coverpage' is lit on the postal address object. A 'null' value will be treated as an address of type postal |
postage | String |
Postage type denominator, see the section Postage values for valid values.
Remark: For customers registered to our Norwegian production site, this parameter can be considered redundant as it is ignored |
plex | String | Plex type denominator, see the section Plex values for valid values. |
color | Boolean | Print the content in color (CMYK), if set to false the content will be printed in black and white. |
state | String | State type denominator, see the section State values for valid values. |
state_changed_at | Date | Date in UTC format representing the date when the envelope state was changed. |
created_at | Date | Date in UTC format representing the date when the envelope was created. |
transaction | Object | Transaction object that the state of the Envelop Transaction object. |
{
"id": "f6aa0f0a-4514-46e5-be2c-539278a58e70",
"name": "Invoice 9923891",
"address": {
"$type": "postal",
"name": [
"Company Inc.",
"c/o John Doe"
],
"street": [
"Street no. 37"
],
"postal_code": "65421",
"city": "Gothenburg",
"country": "SE"
},
"postage": "priority",
"plex": "simplex",
"color": true,
"state": "opened",
"state_changed_at": "2015-01-01T12:00:00",
"created_at": "2015-01-01T12:00:00",
"transaction" : {
"state" : "completed",
"state_changed_at" : "2015-01-01T12:00:00"
}
}
Value | Description |
---|---|
priority | Your content will be delivered within one working day after it's been printed and posted. |
economy | Your content will be delivered within four working days after it's been printed and posted. |
rek | Mailings that needs to be signed by the recipient before hand out. |
Value | Description |
---|---|
simplex | We will only print on the front of each paper sheet. |
duplex | We will print on both the front and back of each paper sheet. |
Value | Description |
---|---|
opened | The envelope is in opened state, you can add content, modify or cancel the envelope. |
closed | The envelope is in closed state, it's marked as ready for print & distribution. |
transferred | The envelope has been transferred to our production facility, and can no longer be modified or cancelled. |
printed | The envelope has been printed in our production facility. |
posted | The envelope has been posted. |
cancelled | The envelope has been cancelled, and will not be printed or distributed. |
failed | The envelope could not be produced in our facility, contact our customer service for further information. |
There are three valid types of addresses; postal, einvoice, email.
The envelopes content will be printed and will be sent with regual postal mail. Note: The address is still required to be embedded inside the document unless the use_coverpage flag is used.
In case of Registered mail/REK, certain limitations apply to the different address rows. name and street have a max limit of 35 characters/row and posta_code a limit to five digits only (with or without blankspaces).
Parameter | Type | Description |
---|---|---|
$type | String |
Denominator for the address type, should always be set to 'postal'.
Remark: this parameter must come first in the json object. |
name | String[] | The recipient's name, each string in the array is considered to be a address line. |
street | String[] | The recipient's street name, each string in the array is considered to be a address line. |
postal_code | String | The recipient's postal/zip code. |
city | String | The recipient's city name. |
country | String | The recipient's country name or country code as a ISO 3166-1 encoded alpha-2 code. See an official list of country codes. |
use_coverpage | Boolean | On true: A flyleaf page will be added to the envelope containing the address details. |
{
"$type": "postal",
"name": [
"Company Inc.",
"c/o John Doe"
],
"street": [
"Street no. 37"
],
"postal_code": "65421",
"city": "Gothenburg",
"country": "SE",
"use_coverpage": true
}
The envelopes content will be attached to an email and sent to the specified recipient.
Parameter | Type | Description |
---|---|---|
$type | String |
Denominator for the address type, should always be set to 'email'.
Remark: this parameter must come first in the json object. |
subject | String | The value will be set as the email's subject field. |
recipient | String | The recipient's email adress, to where the contents of the envelope will be sent. |
{
"$type": "email",
"subject": "Invoice 9923891",
"recipient": "johndoe@johndoe.com"
}
The envelopes content will be sent as an sms to the specified recipient or recipients.
Parameter | Type | Description |
---|---|---|
$type | String |
Denominator for the address type, should always be set to 'sms'.
Remark: this parameter must come first in the json object. |
from | String |
The sender name or phone number that will appear in the sms.
Remark: this parameter is limited to 11 characters. |
recipients | String[] |
The recipient's phone number or numbers, to where the contents of the envelope will be sent.
Remark: A phone number should be given in international format (leading + sign) then numbers only. A typical swedish number would look like this: +46739112233. |
{
"$type": "sms",
"from_name": "FöretagetAB",
"recipients": ["+46739XXXXXX", "+46739XXXXXY", "+46739XXXXXZ"]
}
The content will be sent to kivra inbox (einbox_kivra) owned by the recipient, if the einbox doesn't exist the envelope will be printed and posted instead.
Parameter | Type | Description | ||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
$type | String |
Denominator for the address type, should always be set to 'einbox_kivra'.
Remark: this parameter must come first in the json object. |
||||||||||||||||||||||||||||||||||||
recipient | String | The recipient of the einbox's social security number, to where the contents of the envelope will be sent. | ||||||||||||||||||||||||||||||||||||
subject | String | The value will be displayed as subject in the recipient's e-inbox if supported. Remarks: if a template has been specified this value will be ignored and the stored subject of the template will be used instead. | ||||||||||||||||||||||||||||||||||||
sender_id | String | Optional to set other sender then the default. | ||||||||||||||||||||||||||||||||||||
kivra_type | Int |
0: Letter (Default), 1: Invoice, 2: Letter Salary, 3: Booking, |
||||||||||||||||||||||||||||||||||||
booking | Object |
Booking object
|
||||||||||||||||||||||||||||||||||||
invoice | Object |
Invoice object
|
{
"$type": "einbox_kivra",
"subject": "Bokning 1543",
"recipient": "19590422XXXX",
"kivra_type": 3,
"booking": {
"title": "Välkommen på årets besök",
"start_time": "2021-03-06 15:00",
"end_time": "2021-03-06 17:30",
"description": "Beskrivning av händelse",
"location": "Drottningtorget 5, 411 03 Göteborg",
"info_url": "https://www.ekopost.se"
}
}
{
"$type": "einbox_kivra",
"subject": "faktura 02102",
"recipient": "19830706XXXX",
"kivra_type": 1,
"invoice": {
"reference": "01253679",
"payable": true,
"currency": "SEK",
"due_date": "2021-06-28",
"total_owed": "123.75",
"use_ocr": false,
"use_bg": true,
"account": "0000-0000",
"payment_reference": "1234023"
}
}
The content will be sent to a digital inbox (einbox) owned by the recipient, if the einbox doesn't exist the envelope will be printed and posted instead. Used for Digipost (Norway) and MinaMeddelanden (Sweden)
Parameter | Type | Description |
---|---|---|
$type | String |
Denominator for the address type, should always be set to 'einbox'.
Remark: this parameter must come first in the json object. |
recipient | String | The recipient of the einbox's social security number, to where the contents of the envelope will be sent. |
template | String | The id of a predefinied ekopost template. The stored subject and content of the template will be used instead of any subject/content specified in the request. |
subject | String | The value will be displayed as subject in the recipient's e-inbox if supported. Remarks: if a template has been specified this value will be ignored and the stored subject of the template will be used instead. |
content | String | The specified content will be displayed as html/text message in the recipients e-inbox if supported. Remarks: if a template has been specified this value will be ignored and the stored content of the template will be used instead. |
sender_id | String | Optional to set other sender then the default. |
{
"$type": "einbox",
"subject": "Invoice 9923891",
"recipient": "19800101xxxx"
}
The content will be sent to a digital inbox (einbox) ,if it exist, owned by the recipient and also to a given email, if the einbox doesn't exist the document can be signed by bank-id login.
Parameter | Type | Description |
---|---|---|
$type | String |
Denominator for the address type, should always be set to 'einbox_signer'.
Remark: this parameter must come first in the json object. |
info_mail | String | Email inbox that should receive information and the covenant document when all parties has signed the document. |
sender_id | String | Optional to set other sender then the default. |
signers | Object[] | Signer object that represents the signers |
signers.email | String | Email address where the link for singing the document will be sent |
signers.recipient | String | The recipient's social security number. |
signers.issuer | Boolean |
The issuer of the signing document
Remark: Can be true for one signer. |
{
"$type": "einbox_signer",
"info_mail": "infoepost@företaget1.com",
"signers": [
{
"email": "johndoe1@johndoe1.com",
"recipient": "19800101xxxx",
"issuer": true,
},
{
"email": "johndoe2@johndoe2.com",
"recipient": "19800202xxxx",
"issuer": false,
}
]
}
The envelopes content will be transfered electronically to the recipient.
Parameter | Type | Description |
---|---|---|
$type | String |
Denominator for the address type, should always be set to 'einvoice'.
Remark: this parameter must come first in the json object. |
format | String | Format type denominator, see the section Format values for valid values. |
sender | String | Identifier of the sender, this is usually the sender's registration number. |
sender_type | String | Identifier type denominator, see the section Identifier type values for valid values. |
recipient | String | Identifier of the recipient, this is usually the recipient's registration number. |
recipient_type | String | Identifier type denominator, see the section Identifier type values for valid values. |
intermediator | String |
Intermediator type denominator, see the section Intermediator values for valid values.
Remark: If the recipient is using Ekopost to receive eletronic documents or the intermediator is not found or unkwon, set the value to 'null'. |
{
"$type": "einvoice",
"format": "svefaktura-1.0",
"sender": "556838-4118",
"sender_type": "SE.REGNO",
"recipient": "556838-4118",
"recipient_type": "SE.REGNO",
"intermediator": null
}
Value | Description |
---|---|
svefaktura-1.0 | This represents version 1.0 of svefaktura. |
svefaktura-2.0-invoice | This represents version 2.0 of svefaktura, type invoice. |
svefaktura-2.0-creditnote | This represents version 2.0 of svefaktura, type creditnote. |
Value | Description |
---|---|
SE.REGNO | This represents a swedish company registration number, format e.g. "556838-4118". |
SE.SSNNO | This represents a swedish personal social security number, format e.g. "YYMMDD-XXXX". |
GS1.GLN | This represents a global location number (GLN) based on the GS1 general specifications. |
Value | Description |
---|---|
peppol | Pan-European Public Procurement Online. |
Ekopost need information about your Navet-connection before this can be used.
Returns postal address-object that will be transformed and used as address for current envelope.
Parameter | Type | Description |
---|---|---|
$type | String |
Denominator for the address type, should always be set to 'lookup'.
Remark: this parameter must come first in the json object. |
recipient | String | Social security number |
{
"$type": "lookup",
"recipient": "18750710XXXX"
}
The envelopes content will be transfered electronically to the recipients internet bank.
Parameter | Type | Description |
---|---|---|
$type | String |
Denominator for the address type, should always be set to 'ebank'.
Remark: this parameter must come first in the json object. |
recipient | String | An identifier (FMI) of the recipient, the identifier is usually provided by the bank or through a lookup service. |
customer_number | String | External identifier of the customer, this is usually a number stored in the senders system. |
customer_name | String | Name of the customer. |
invoice_number | String | The external invoice number. |
reference_type | String | The external reference type used as a reference when paying the invoice, type can be either 'ocr' or 'message'. |
reference_value | String | The external reference value used as a reference when paying the invoice. |
giro_number | String | The giro account number of the payment recipient. Remark: This value should not contain dashes, only numbers. |
autogiro | Boolean |
Set to true if the invoice is payed through autogiro.
Remark: Setting this to true will disable manual payment of the invoice in the internet bank. |
amount | String | The total amount of the invoice. |
invoice_date | String | Date when the invoice was issued. |
due_date | String | Date when the invoice payment is due. |
issuer | String | Optional to send from this issuer instead of default issuer. |
presentation_reference | String | Optional to set presentation reference. |
{
"$type": "ebank",
"recipient": "5568384118.BNK.SE",
"customer_number": "556838-4118",
"customer_name": "No Ink AB",
"invoice_number": "556838",
"reference_type": "ocr",
"reference_value": "0000556838411800",
"giro_number": "55683841",
"autogiro": true,
"amount": 499.99,
"invoice_date": "2015-01-01T00:00:00",
"due_date": "2015-01-31T00:00:00"
}
The envelopes transaction information when it changed and to what state.
Parameter | Type | Description |
---|---|---|
state | String | State type denominator, see the section State values for valid values. |
state_changed_at | Date | Date in UTC format representing the date when the campaign state was changed. |
"transaction" : {
"state" : "completed",
"state_changed_at" : "2015-01-01T12:00:00"
}
Representation of a document or an attachment that will be printed.
Parameter | Type | Description |
---|---|---|
id | Guid | The content object's unique id. |
mime | String | The original file's mime type. |
length | Int | The original file's size in bytes. |
type | String | Content type denominator, see the Type values section for valid values. |
created_at | Date | Date in UTC format representing the date when the content was created. |
{
"id": 100,
"mime": "application/pdf",
"length": 1024,
"type": "document",
"created_at": "2015-01-01T12:00:00"
}
Value | Description |
---|---|
document | The object intance represents the main document. |
attachment | The object intance represents an attachment. |
markup | The object intance represents a xml markup. |
sms | The object intance represents a message string. |
Bad requests with http response code 400 does contains an error object with futher information about the bad request.
Parameter | Type | Description |
---|---|---|
error_code | String | Code that represents the error that occured. |
error_message | String | Description about what error occured. |
developer_message | String | Further description about the error for developers. |
{
"error_code": "0",
"error_message": "Invalid basic authentication token.",
"developer_message": "Please verify that the account is activated and the username and password are valid."
}
Value | Description |
---|---|
0 | Invalid basic authentication token. |
100A | The envelope must contain atleast one (1) document before being closed. |
100B | The envelope must contain atleast one (1) markup before being closed. |
101 | A campaign must contain atleast one (1) envelope before being closed. |
102 | All envelopes inside a campaign must be closed before closing the campaign. |
103 | An envelope may only contain one (1) document. |
104 | An envelope may only contain content with mime of 'application/pdf'. |
105 | Could not extract or identify a postal address in the envelopes main documents. |
106 | Campaign was not found. |
107 | Could not open the main document content or find any pages. |
108 | An envelope may only contain content of type 'attachment' with mime set to 'application/pdf'. |
109 | An envelope may only contain content of type 'markup' with mime set to 'application/xml'. |
110 | An envelope may only contain one (1) markup. |
111 | Envelope was not found. |
112 | Specified country is not a valid ISO 3166-1 encoded alpha-2 code. |
113 | You have exceeded your credit limit for the month, please contact our customer service to adjust your credit limit. |
114 | The searchparams is null. |
115 | The searchparams is invalid. |
116 | The timespan is invalid. |
117 | The document size is invalid. |
118 | The attachment size is invalid. |
119 | Missing recipient. |
120 | Missing email |
121 | Can not create more envelopes in campaign |
122 | One signer needed |
123 | Email address contains invalid characters. |
124 | FUI-number is not registrered |
125 | No applicants registrered for this FUI |
126 | Not unique |
127 | Invalid data |
128 | Wrong mime for sms. Mime should be 'text/plain' |
129 | Empty data field |
130 | Sms text message not encoded into base64 |
131 | Sms recipients contains invalid phone number. |
132 | Sms does not contain any recipients |
133 | Sms "FromName" is null or empty. |
134 | Sms too many recipients (100 000 is the max limit) |
135 | Address validation error, error contains more details such as "Name too long (max 35 characters)" |
Ekopost is quick and easy to integrate in a .NET environment using our nuget package, the package uses a fluent interface to schedule print & production.
PM > Install-Package Ekopost
the minimum required steps needed to schedule an envelope
Setting up the Ekopost class to target your account.
In order to integrate with Ekopost you must first provide an API key that is liked to your account, this key can be found in the portal https://secure.ekopost.se. Once you have your key you can use it as a parameter to instantiate an Ekopost object as seen in [CODE EXAMPLE 1] below
[CODE EXAMPLE 1] -initialize
- - - - - - - - - - - - - - - - - - - - -
using Ekopost.Contracts;
.
.
.
1 var eko = new Ekopost.Ekopost("apikeystring");
.
.
.
- - - - - - - - - - - - - - - - - - - - -
Now when we have an Ekopost object, [eko], there are 3 important functions to note:
In this tutorial we will go through each of the objects created by these functions with example of how to use them and in the process we will have scheduled our first mail for delivery using the Ekopost nuget package.
Content can be thought of as the letter that you wish to send. That letter needs to be put in an envelope and a campaign can contain multiple envelopes. When we code this using the nuget package we do it in reverse and create the campaign first, then the envelope and finally the content. Lets get started with the campaign
Campaign
[CODE EXAMPLE 2] -create a new campaign
- - - - - - - - - - - - - - - - - - - - -
.
.
.
1 var newCampaign = new Campaign("myFirstCampaign","", DateTime.Now.AddHours(2));
2
3 var campaignSet = eko.CampaignSet.Create();
4
5 var registeredCampaign = campaignSet
6 .Create(newCampaign)
7 .Resource;
.
.
.
- - - - - - - - - - - - - - - - - - - - -
first we create a campaign object on line 1. In the example it has been given a name [myFirstCampaign], providing a blank cost center and schedules the send outs to two hours from now.
Next we use the first function mentioned above to create a CampaignSet object, this is what we use when we want to manipulate campaigns.
Note that no interaction with Ekopost has yet occurred, on the line 5 however an API call is made by calling the Create() function campaignSet. This function return a wrapper object with metadata on the API call, the Resource property contains the registered campaign. We are interested in the returned campaign object because it contains an Id that needs to be referenced in our next step.
Envelope
[CODE EXAMPLE 3] -create a new Envelope
- - - - - - - - - - - - - - - - - - - - -
.
.
.
1 var postalAddress = new AddressPostal(
2 new[] { "Johnny Doh" },
3 new[] { "Ekovägen 12" },
4 "43215",
5 "Ekostaden",
6 "SE");
7 var envelope = new Envelope("firstLetter", postalAddress, Postage.Economy, Plex.Simplex, false);
8 var envelopeSet = eko.EnvelopeSet.Create(registeredCampaign.Id);
9 var registeredEnvelope = envelopeSet
10 .Create(envelope)
11 .Resource;
.
.
.
- - - - - - - - - - - - - - - - - - - - -
an envelope needs a destination, so we start by making an address object on line 1-6. There are multiple address types however this tutorial covers only a postal address type. Now when we have an address we can use it as a parameter when creating an envelope as is seen on line 7. Once again we create a Set item (line 8), this time the EnvelopeSet, so that we can manipulate envelopes in Ekopost, note that we need to use the Id of the campaign item [registeredCampaign] we received in [CODE EXAMPLE 2] Just like before we make an API call and register our envelope with Ekopost via the Create() method on line 9-11.
Content
[CODE EXAMPLE 4] -create a new Content
- - - - - - - - - - - - - - - - - - - - -
.
.
.
1 var content = new Content(ContentType.Document, "~path/to/file/on/disk/aletter.pdf");
2 var contentSet = eko.ContentSet.Create(registeredCampaign.Id, registeredEnvelope.Id);
3 contentSet.Create(content);
.
.
.
- - - - - - - - - - - - - - - - - - - - -
this is where we upload our letter, what we call content. It is required that an envelope contains a document type Content, this is the main content of any envelope, so on line 1 we create such content. In this example we point to the file that we want to upload from disk by using a path parameter. Next, line 2, we use our last Set item, namely that of a ContentSet, to manage our content, this time we need to supply the campaign [registeredCampaign] id from [CODE EXAMPLE 2] and also the envelope [registeredEnvelope] Id from [CODE EXAMPLE 3]. Finally on line 3 we make the API call.
OK all set? Not quite!
More envelopes and more content can be created as desired, once done we need to mark the campaign and the envelope as ready for delivery
Close
[CODE EXAMPLE 5] -close the campaign and envelope
- - - - - - - - - - - - - - - - - - - - -
.
.
.
1 envelopeSet.Close(registeredEnvelope.Id);
2 campaignSet.Close(registeredCampaign.Id);
.
.
.
- - - - - - - - - - - - - - - - - - - - -
by using our Set objects we call the close function on both envelopes and campaigns, this will mark them as ready for our system to send them on to their destination. Note that once they are closed you may no longer modify them, you may however cancel, provided you do it before the scheduled send out time.
Cancel and Review
[CODE EXAMPLE 6] - cancel and review objects
- - - - - - - - - - - - - - - - - - - - -
.
.
.
1 envelopeSet.Cancel(registeredEnvelope.Id);
2 campaignSet.Cancel(registeredCampaign.Id);
3 envelopeSet.List().Resource;
4 campaignSet.List().Resource;
.
.
.
- - - - - - - - - - - - - - - - - - - - -
Line 1 and 2 shows how to cancel envelopes and campaigns respectively
line 3 and 4 shows how to retrieve a collection of envelopes and campaigns respectively. The List() function also accepts parameters to filter the returned result.
When seding an invoice directly to a customers bank account, the Ebank address should be used. this object (ebankAddress) will replace the postalAddress object from [CODE EXAMPLE 3] when creating an Envelope.
[CODE EXAMPLE 7] - Creating an Ebank Address object
- - - - - - - - - - - - - - - - - - - - -
.
.
.
1 var ebankAddress = new AddressEbank(
2 "5568384118.BNK.SE",
3 "556838-4118",
4 "No Ink AB",
5 "556838",
6 ReferenceTypes.Ocr,
7 "0000556838411800",
8 "5568-3841",
9 false,
10 499.99M,
11 Convert.ToDateTime("2019-09-17T00:00:00"),
12 Convert.ToDateTime("2019-09-20T00:00:00"));
.
.
.
- - - - - - - - - - - - - - - - - - - - -
The parameters used when creating an Ebank address are further described in the Object (ebank) section above
The url for connecting to our sandbox environment is http://api.sandbox.ekopost.se
Remarks:
Sandbox do not use https!
Nothing that uploaded to sandbox will be sent to end customers.
Create a sandbox user. Click here to create.
If you already have created a sanbox-user, Click here to login
When you have created your sandbox account, you will automatically be signed in and you can immediately manually start uploading letter for testing or start using our API (http://api.sandbox.ekopost.se) with your user information that has been sent to your e-mail you entered when registering.
Set up Webhooks to receive status when campaign is completed.
You can access webhook-setup in secure API-settings menu here.
Webhooks allow you to build or set up integrations which subscribe to certain Ekopost events. When one of those events is triggered, we'll send a HTTP POST payload to the webhook's configured URL. Once installed, the webhook will be triggered each time one or more subscribed events occurs.
Webhooks are only subscribed to the campaign completed event for now. For example, if you subscribe to webhooks event you'll receive a payload every time a campaign is completed and statuses for all envelopes in the campaign.
You'll get a specific payload with the envelopes id and status information.
HTTP POST payloads that are delivered to your webhook's configured URL endpoint will contain one special header:
X-Ekopost-Signature The HMAC hex digest of the response body. The HMAC hex digest is generated using the sha1 hash function and the secret as the HMAC key.
POST /payload HTTPS/1.1
Host: localhost:4567
X-Ekopost-Signature: 7d38cdd689735b008b3c702edd92eea23791c5f6
Content-Type: application/json
[
{
"ObjectId": "5b161d7a-8a62-44ca-94c2-a2d9d2819be3",
"StatusName": "posted"
},
{
"ObjectId": "9916aa7a-442a-8a62-94c2-a2d672819b99",
"StatusName": "posted"
}
]
In these examples we're using Newtonsoft.Json and Newtonsoft.Json.Linq along with RestSharp.
private IRestResponse Get(string url)
{
var client = new RestClient();
var request = new RestRequest($"{_host}{url}");
request.Method = Method.GET;
request.AddHeader("Authorization", $"api-key {_apiKey}");
request.AddHeader("Content-Type", "application/json; charset=UTF-8");
return client.Get(request);
}
private IRestResponse Post(string url, string requestBody = null)
{
var client = new RestClient();
var request = new RestRequest($"{_host}{url}").AddJsonBody(requestBody);
request.Method = Method.POST;
request.AddHeader("Authorization", $"api-key {_apiKey}");
request.AddHeader("Content-Type", "application/json; charset=UTF-8");
return client.Post(request);
}
Please read about sms in the Address documentation and in the Content documentation for further information.
public void SendSms()
{
// Create Campaign
var campaignBody = new
{
name = "Example Sms Campaign",
output_date = DateTime.Now,
cost_center = "Sms cost center"
};
var createCampaignResult = Post($"/campaigns/", JsonConvert.SerializeObject(campaignBody, Formatting.None));
var createCampaignObject = JsonConvert.DeserializeAnonymousType(createCampaignResult.Content, new { id = "" });
/* ToDo: Check result */
// Create Envelope
var envelopeBody = new
{
name = "Sms Envelope",
postage = "priority",
plex = "simplex",
color = true,
address = new JObject
{
{ "$type", "sms" },
{ "from_name", "value2" },
{ "recipients", JToken.FromObject(new[] { "+46739000000", "+46000000ABC" }) }
}
};
var createEnvelopeResult = Post($"campaigns/{createCampaignObject.id}/envelopes",
JsonConvert.SerializeObject(envelopeBody, Formatting.None));
var createEnvelopeObject = JsonConvert.DeserializeAnonymousType(createEnvelopeResult.Content, new { id = "" });
/* ToDo: Check result */
// Create Content
var contentBody = new
{
data = "YW55IGNhcm5hbCBwbGVhcw==",
mime = "text/plain",
length = 1024,
type = "sms"
};
var createContentResult = Post($"campaigns/{createCampaignObject.id}/envelopes/{createEnvelopeObject.id}/content",
JsonConvert.SerializeObject(contentBody, Formatting.None));
var createContentObject = JsonConvert.DeserializeAnonymousType(createContentResult.Content, new { id = "" });
/* ToDo: Check result */
// Close Envelope
Post($"campaigns/{createCampaignObject.id}/envelopes/{createEnvelopeObject.id}/close");
// Close Campaign
Post($"campaigns/{createCampaignObject.id}/close");
// Use id's when getting delivery report
var envelopes = Get($"/campaigns/{createCampaignObject.id}/envelopes/{createEnvelopeObject.id}");
}
var campaignId = Guid.Parse("b67add0e-d895-4606-9418-697bd45e62e3");
var result = Get($"/campaigns/{campaignId}/envelopes");
[ { "id": "2c0978ca-2427-4765-b29d-e3fd7679ebba", "name": "Sms Envelope", "address": { "$type": "sms", "recipients": [ "+46000000000", "+46000000ABC" ], "from_name": "Ekopost", "delivery_report": [ { "id": 1750, "phone_number": "+46000000000", "status": "Delivered", "status_reason": "" }, { "id": 1751, "phone_number": "+46000000ABC", "status": "Failed", "status_reason": "Invalid destination number" } ] }, "state": "posted", "state_changed_at": "2021-06-07T10:49:40Z", "postage": "economy", "plex": "simplex", "color": false, "created_at": "2021-06-07T10:48:29Z" } ]
The Envelope's "state" is set to posted, meaning that both sms was sent. But only one of them was delivered to the recipient. The other one was an invalid number.
Make sure to read about valid numbers in the Address documentation
var campaignId = Guid.Parse("b67add0e-d895-4606-9418-697bd45e62e3");
var envelopeId = Guid.Parse("2c0978ca-2427-4765-b29d-e3fd7679ebba");
var result = Get($"/campaigns/{campaignId}/envelopes/{envelopeId}");
{ "id": "2c0978ca-2427-4765-b29d-e3fd7679ebba", "name": "Sms Envelope", "address": { "$type": "sms", "recipients": [ "+46000000000", "+46000000ABC" ], "from_name": "Ekopost", "delivery_report": [ { "id": 1750, "phone_number": "+46000000000", "status": "Delivered", "status_reason": "" }, { "id": 1751, "phone_number": "+46000000ABC", "status": "Failed", "status_reason": "Invalid destination number" } ] }, "state": "posted", "state_changed_at": "2021-06-07T10:49:40Z", "postage": "economy", "plex": "simplex", "color": false, "created_at": "2021-06-07T10:48:29Z" }
The result in this case is the same as the one above, except that it's not a list.
This endpoint is dedicated to single sms that will be sent out immediately. It is not meant to be used for mass sms.
private void SendDirectSms()
{
var req = new
{
From = "Ekopost",
Recipient = "+4673123456",
Text = "Direkt sms",
Title = "A direct sms campaign",
Cost_Center = "Direct cost center"
};
var result = Post("sms/", JsonConvert.SerializeObject(req, Formatting.None));
}
{ "campaign_id": "047b0ef0-12b2-4b0d-b72a-b6212cbb5ac4", "envelope_id": "bb02bb19-12e5-484f-9342-c911257b341c", "error": "", "from": "Ekopost", "recipient": "+4673123456", "text": "Direkt sms", "title": "A direct sms campaign", "cost_center": "Direct cost center" }