Emails Duty Labs Documentation


https://emails.dutylabs.ro

For the motivation, as well as a rough getting started, see https://rusu.io/emails

This is a simple service that one can use to send emails. One only needs to verify his domain, create the corresponding email templates and then make correct requests to the service.

TODO:

  • [x] Create customer

  • [x] Read customer

  • [x] Update customer

  • [x] Delete customer

  • [x] List customers

  • [ ] Allow scheduled send

  • [ ] Allow workflows

  • [ ] Add triggers/events

Customers

Creating a customers

When creating a customer, just add the email and the attributes for your customer such as first_name, last_name. Add these attributes under the metadata field.

Endpoint

POST /api/v1/customers

Parameters

Name Description
email The email of your customers
metadata The metadata associated with your customer. Put here a dictionary of values such as `first_name`, `last_name` or `plan`.

Request

Route

POST /api/v1/customers

Headers

Accept: application/json
Content-Type: application/json
X-Emails-Duty-Labs-Api-Key: iZRzFQ4ob91v3tAafvJYXDV8

Body

{
  "email": "customer@example.com",
  "metadata": {
    "first_name": "John",
    "last_name": "Doe",
    "plan": "standard"
  }
}

Response

Simulated Response

Status

201

Headers

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

Body

{
  "id": 2,
  "email": "customer@example.com",
  "metadata": {
    "first_name": "John",
    "last_name": "Doe",
    "plan": "standard"
  },
  "user_id": 1,
  "created_at": "2019-12-15T11:23:10.108Z",
  "updated_at": "2019-12-15T11:23:10.108Z"
}

No more than 100 metadata values

There is a strong limit of 100 values on metadata that you can send on each request.

Endpoint

POST /api/v1/customers

Parameters

Name Description
email The email of your customers
metadata The metadata associated with your customer. Put here a dictionary of values such as `first_name`, `last_name` or `plan`.

Request

Route

POST /api/v1/customers

Headers

Accept: application/json
Content-Type: application/json
X-Emails-Duty-Labs-Api-Key: x8Ui9rZ4ZFHhNhciLzoAn6uT

Body

{
  "email": "customer@example.com",
  "metadata": {
    "0": 0,
    "1": 1,
    "2": 2,
    "3": 3,
    "4": 4,
    "5": 5,
    "6": 6,
    "7": 7,
    "8": 8,
    "9": 9,
    "10": 10,
    "11": 11,
    "12": 12,
    "13": 13,
    "14": 14,
    "15": 15,
    "16": 16,
    "17": 17,
    "18": 18,
    "19": 19,
    "20": 20,
    "21": 21,
    "22": 22,
    "23": 23,
    "24": 24,
    "25": 25,
    "26": 26,
    "27": 27,
    "28": 28,
    "29": 29,
    "30": 30,
    "31": 31,
    "32": 32,
    "33": 33,
    "34": 34,
    "35": 35,
    "36": 36,
    "37": 37,
    "38": 38,
    "39": 39,
    "40": 40,
    "41": 41,
    "42": 42,
    "43": 43,
    "44": 44,
    "45": 45,
    "46": 46,
    "47": 47,
    "48": 48,
    "49": 49,
    "50": 50,
    "51": 51,
    "52": 52,
    "53": 53,
    "54": 54,
    "55": 55,
    "56": 56,
    "57": 57,
    "58": 58,
    "59": 59,
    "60": 60,
    "61": 61,
    "62": 62,
    "63": 63,
    "64": 64,
    "65": 65,
    "66": 66,
    "67": 67,
    "68": 68,
    "69": 69,
    "70": 70,
    "71": 71,
    "72": 72,
    "73": 73,
    "74": 74,
    "75": 75,
    "76": 76,
    "77": 77,
    "78": 78,
    "79": 79,
    "80": 80,
    "81": 81,
    "82": 82,
    "83": 83,
    "84": 84,
    "85": 85,
    "86": 86,
    "87": 87,
    "88": 88,
    "89": 89,
    "90": 90,
    "91": 91,
    "92": 92,
    "93": 93,
    "94": 94,
    "95": 95,
    "96": 96,
    "97": 97,
    "98": 98,
    "99": 99,
    "100": 100,
    "101": 101
  }
}

Response

Simulated Response

Status

400

Headers

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

Body

{
  "error": "Too many metadata values"
}

Return an existent user

To return a specific user, just put the corresponding id in the url

Endpoint

GET /api/v1/customers/:id

Parameters

Name Description
id The unique id of your customer

Request

Route

GET /api/v1/customers/4

Headers

Accept: application/json
Content-Type: application/json
X-Emails-Duty-Labs-Api-Key: hgkerddq1NRmf61j7y1DHtQx

Response

Simulated Response

Status

200

Headers

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

Body

{
  "id": 4,
  "email": "customer@example.com",
  "metadata": {
    "last_name": "Customer",
    "first_name": "Your"
  },
  "user_id": 3,
  "created_at": "2019-12-15T11:23:10.169Z",
  "updated_at": "2019-12-15T11:23:10.169Z"
}

Return the list of your associated users

Endpoint

GET /api/v1/customers

Request

Route

GET /api/v1/customers

Headers

Accept: application/json
Content-Type: application/json
X-Emails-Duty-Labs-Api-Key: 5yzw3JyV1AcMJY6stgqkyEFB

Response

Simulated Response

Status

200

Headers

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

Body

[
  {
    "id": 5,
    "email": "customer@example.com",
    "metadata": {
      "last_name": "Customer",
      "first_name": "Your"
    },
    "user_id": 4,
    "created_at": "2019-12-15T11:23:10.202Z",
    "updated_at": "2019-12-15T11:23:10.202Z"
  }
]

Delete a customers

Endpoint

DELETE /api/v1/customers/:id

Parameters

Name Description
id The unique id of your customer

Request

Route

DELETE /api/v1/customers/6

Headers

Accept: application/json
Content-Type: application/json
X-Emails-Duty-Labs-Api-Key: jftXCgGJpGFxxQHsyPRenXk9

Response

Simulated Response

Status

204

Emails

Sending an email template

Sending a simple email is very easy, just specify the to_email and the template_code

Endpoint

POST /api/v1/emails

Parameters

Name Description With Example
email[to_email] to_email true
email[template_code] template_code true

Request

Route

POST /api/v1/emails

Headers

Accept: application/json
Content-Type: application/json
X-Emails-Duty-Labs-Api-Key: a9rtwVEPwhd38yc8tXW4LHyj

Body

{
  "email": {
    "to_email": "sendto@dutylabs.ro",
    "template_code": "welcome_email"
  }
}

Response

Simulated Response

Status

201

Headers

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

Body

{
  "id": 1,
  "user_id": 6,
  "email_template_id": 1,
  "to_email": "sendto@dutylabs.ro",
  "from_email": null,
  "first_name": null,
  "last_name": null,
  "subject": null,
  "template_code": "welcome_email",
  "sent_at": "2019-12-15T11:23:10.294Z",
  "created_at": "2019-12-15T11:23:10.298Z",
  "updated_at": "2019-12-15T11:23:10.298Z"
}

Overriding email template defaults

You can also override some of the fields from the email template. Currently only from_email and subject is supported

Endpoint

POST /api/v1/emails

Parameters

Name Description With Example
email[to_email] to_email true
email[template_code] template_code true

Request

Route

POST /api/v1/emails

Headers

Accept: application/json
Content-Type: application/json
X-Emails-Duty-Labs-Api-Key: WTcnxFJ6SG1s6dxHtp422Vii

Body

{
  "email": {
    "to_email": "sendto@dutylabs.ro",
    "template_code": "welcome_email",
    "from_email": "another@dutylabs.ro",
    "subject": "Hello there"
  }
}

Response

Simulated Response

Status

201

Headers

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

Body

{
  "id": 2,
  "user_id": 7,
  "email_template_id": 2,
  "to_email": "sendto@dutylabs.ro",
  "from_email": "another@dutylabs.ro",
  "first_name": null,
  "last_name": null,
  "subject": "Hello there",
  "template_code": "welcome_email",
  "sent_at": "2019-12-15T11:23:11.268Z",
  "created_at": "2019-12-15T11:23:11.270Z",
  "updated_at": "2019-12-15T11:23:11.270Z"
}

X-Emails-Duty-Labs-Api-Key missing

If you don’t specify the correct API Key in the header, you will get a 401 back

Endpoint

POST /api/v1/emails

Parameters

Name Description With Example
email[to_email] to_email true
email[template_code] template_code true

Request

Route

POST /api/v1/emails

Headers

Accept: application/json
Content-Type: application/json
X-Emails-Duty-Labs-Api-Key: 

Body

{
  "email": {
    "to_email": "sendto@dutylabs.ro",
    "template_code": "welcome_email"
  }
}

Response

Simulated Response

Status

401

Headers

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

Body

{
  "error": "Invalid Api Key"
}

X-Emails-Duty-Labs-Api-Key wrong

If you don’t specify the correct API Key in the header, you will get a 401 back

Endpoint

POST /api/v1/emails

Parameters

Name Description With Example
email[to_email] to_email true
email[template_code] template_code true

Request

Route

POST /api/v1/emails

Headers

Accept: application/json
Content-Type: application/json
X-Emails-Duty-Labs-Api-Key: s14234123412

Body

{
  "email": {
    "to_email": "sendto@dutylabs.ro",
    "template_code": "welcome_email"
  }
}

Response

Simulated Response

Status

401

Headers

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

Body

{
  "error": "Invalid Api Key"
}