Content-Type: application/json; charset=UTF-8

Authorization: api-key YiuyotGtRNDXik56lgq6
Content-Type: application/json; charset=UTF-8

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8

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"
}

    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"
    }

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

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

GET /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8

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 /campaigns?start={start}&stop={stop}&name={name}&state={state} HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8

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" 
}]

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
}

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"
        }
}

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

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

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

    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 "
        }
    }

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

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"
        }
}]

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"
}

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"
}

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

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"
}

POST /reachable/ebank HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
{
    "recipient": "19800101xxxx"
}

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

    POST /reachable/ebank HTTP/1.1
    Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
    Content-Type: application/json; charset=UTF-8
    {
        "sender": "0000001.000002.SEB.SE",
    }

    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

{
    "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"
}

{
    "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"
    }
}

    {
    "$type": "postal",
    "name": [
    "Company Inc.",
    "c/o John Doe"
    ],
    "street": [
    "Street no. 37"
    ],
    "postal_code": "65421",
    "city": "Gothenburg",
    "country": "SE",
    "use_coverpage": true
    }

{
    "$type": "email",
    "subject": "Invoice 9923891",
    "recipient": "johndoe@johndoe.com"
}

{
    "$type": "sms",
    "from_name": "FöretagetAB",
    "recipients": ["+46739XXXXXX", "+46739XXXXXY", "+46739XXXXXZ"]
}

    {
        "$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"
        }
    }

{
    "$type": "einbox",
    "subject": "Invoice 9923891",
    "recipient": "19800101xxxx"
}

{
    "$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,
        }
    ]
}

{
    "$type": "einvoice",
    "format": "svefaktura-1.0",
    "sender": "556838-4118",
    "sender_type": "SE.REGNO",
    "recipient": "556838-4118",
    "recipient_type": "SE.REGNO",
    "intermediator": null
}

    {
    "$type": "lookup",
    "recipient": "18750710XXXX"
    }

{
    "$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"
}

    "transaction" : {
        "state" : "completed",
        "state_changed_at" : "2015-01-01T12:00:00"
    }

{
    "id": 100,
    "mime": "application/pdf",
    "length": 1024,
    "type": "document",
    "created_at": "2015-01-01T12:00:00"
}

{
    "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."
}

PM >  Install-Package Ekopost

5 step walkthrough

Initialization

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:

• eko.CampaignSet.Create();
• eko.EnvelopeSet.Create(Guid campaignId);
• eko.ContentSet.Create(Guid campaignId, Guid envelopeId);

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.

Using the Ebank Address object

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