Skip to main content
Version: 1.0.143

Email Channel Service API Specification

This page describes how to integrate with the Email Channel Service on a technical level.

This service is a specialized downstream service, typically called by the central Notification Service. Its sole responsibility is to handle the formatting and dispatching of email notifications.

REST Resources​

The Email Channel Service provides a single resource for creating and sending an email notification.

The Email Notification Resource​

An email notification request defines everything needed to send a single email. It consists of:

  • reference: A unique ID for tracking this specific send request.
  • to, from, cc, bcc: Lists of recipients, senders, and other parties.
  • subject: The subject line of the email.
  • content: A list of content objects, typically text/plain and text/html, for the email body.
  • attachments: A list of Base64-encoded file attachments.

An example of an email notification request in JSON format:

{
  "reference": "email_ref_98765_xyz",
  "to": [
    "Peter Smith <peter.smith@example.com>"
  ],
  "from": [
    "Banqup <noreply@banqup.com>"
  ],
  "replyTo": [
    "Support <support@banqup.com>"
  ],
  "subject": "Your new invoice INV-1024",
  "content": [
    {
      "type": "text/plain",
      "value": "Hello Peter, your new invoice INV-1024 is available."
    },
    {
      "type": "text/html",
      "value": "<h1>Hello Peter,</h1><p>Your new invoice <strong>INV-1024</strong> is available.</p>"
    }
  ],
  "attachments": [
    {
      "content": "SGVsbG8gd29ybGQsIHRoaXMgaXMgYSB0ZXN0IFBERg==",
      "id": "doc_cid_123",
      "disposition": "attachment",
      "filename": "invoice-1024.pdf"
    }
  ]
}

When this email is successfully queued for sending, the service returns a unique notificationId:

{
  "notificationId": "e0c9b2a8-1b7c-4b3d-811c-9e2b6a4a1f2c"
}

Sending an Email​

To send a new email, you'll perform a POST request to the **/core/email/v1/emails ** endpoint, providing the full email notification object in the request body.

POST /v1/emails
Content-Type: application/json

{
  "reference": "email_ref_98765_xyz",
  "to": [
    "Peter Smith <peter.smith@example.com>"
  ],
  "from": [
    "Banqup <noreply@banqup.com>"
  ],
  "subject": "Your new invoice INV-1024",
  "content": [
    {
      "type": "text/html",
      "value": "<h1>Hello Peter,</h1><p>Your invoice is ready.</p>"
    }
  ]
}

A successful response (HTTP 202 Accepted) will return the notificationId confirming the email has been accepted for delivery.

Security​

Access to send emails is controlled by the email_send security scope. All requests to the Email Channel API must be authenticated using an OAuth security scheme and include a token with the required scope.

Authentication​

Security Scheme Type:

oauth2

OAuth Flow (clientCredentials):

Scopes:

  • info: Scopes are endpoint-specific, see each endpoint for required scope.

OAuth Flow (authorizationCode):

Scopes:

  • info: Scopes are endpoint-specific, see each endpoint for required scope.