Different types of Email Configuration APIs

Add or Update Provider Configuration

The Add or Update Provider Configuration API accepts the provider name and configuration properties as input parameters. You need to use this API to set up the email provider before sending emails by using the provider.

IMPORTANT:
  • This API sets the specified HTTP provider (SendGrid or Outlook) as the default email provider.
  • Only one email provider can be active at any point in time.

If you add an HTTP provider by using this API, all other HTTP providers and SMTP providers are deactivated.
Similarly, if you set an SMTP email provider by using the SMTP config URL, all HTTP providers are deactivated.

URL

http://<host or ip>:<port>/api/v1/emailconfig

Method

POST

The payload's request header includes Authorization headers and also includes Content-Type as application/json;charset=UTF-8.

Input Parameters

Input Parameter Level – Two Required Type Description
provider   Required String The name of the email provider, for example: SENDGRID, OUTLOOK
properties   Required Array of JSON An array of configuration properties
  key Required String

The name of the property. The properties are specific to the provider.

For example, the following values are applicable for SendGrid:

  • Account Key
  • Auth Token
  • From
  • To
  • Subject
  • Content

For more information, refer to the sample requests in the following section.
  value Required String A value that corresponds to the key, for example, a value for the From key, is user.name@temenos.com.
  encrypt Required Boolean
(true/false)		 Specifies whether the value must be encrypted in the request.
IMPORTANT:

The following points are applicable to the SendGrid provider.

  • The SendGrid URL must be publicly accessible.
  • Personalized attributes cannot be used if you are sending a group email.
  • The unsubscribe link is enabled for transactional emails but disabled for group emails.

The following points are applicable to the Outlook provider.

  • The Outlook provider contains sending limits and must not be used as a bulk email provider.
  • The SenderName value is fetched from the back-end server even if you provide a value in the request payload.

Sample Request

{
  "provider": "SENDGRID",
  "properties":
  [
    {
      "key": "ACCOUNT_KEY",
      "value": "<account-key>",
      "encrypt": "false"
    },	
    {
      "key": "AUTH_TOKEN",
      "value": "<auth-token>",
      "encrypt": "true"
    },
	{
      "key": "Unsubscribe",
      "value": "true",
      "encrypt": "false"
    },
    {
      "key": "From",
      "value": "user.one@temenos.com",
      "encrypt": "false"
    },
    {
      "key": "To",
      "value": "user.two@gmail.com",
      "encrypt": "false"
    },
    {
      "key": "Subject",
      "value": "SendGrid Mail Test Connection",
      "encrypt": "false"
    },
    {
      "key": "Content",
      "value": "SendGrid Mail Test Connection",
      "encrypt": "false"
    },
	{
		"key": "SenderName",
		"value": "User",
		"encrypt": "false"
	}
  ]
}
{
  "provider": "OUTLOOK",
  "properties":
  [
    {
      "key": "TENANT_ID",
      "value": "<tenant-id>",
      "encrypt": "false"
    },     
    {
      "key": "CLIENT_ID",
      "value": "<client-id>",
      "encrypt": "false"
    },
    {
      "key": "CLIENT_SECRET",
      "value": "<client-secret>",
      "encrypt": "true"
    },     
    {
      "key": "FROM_OBJECT_ID",
      "value": "<sender-object-id>",
      "encrypt": "false"
    },
    {
      "key": "GRANT_TYPE",
      "value": "client_credentials",
      "encrypt": "false"
    },     
    {
      "key": "SCOPE_URL",
      "value": "https://graph.microsoft.com/.default",
      "encrypt": "false"
    },
    {
      "key": "AUTHENTICATE_URL",
      "value": "https://login.microsoftonline.com/##TenantId##/oauth2/v2.0/token",
      "encrypt": "false"
    },     
    {
      "key": "SEND_MAIL_URL",
      "value": "https://graph.microsoft.com/v1.0/users/##SenderMailObjectId##/sendMail",
      "encrypt": "false"
    },
    {
      "key": "From",
      "value": "user.one@temenos.com",
      "encrypt": "false"
    },   
    {
      "key": "To",
      "value": "user.two@temenos.com",
      "encrypt": "false"
    },     
    {
      "key": "Subject",
      "value": "Outlook Mail Test Connection",
      "encrypt": "false"
    },
    {
      "key": "Content",
      "value": "Outlook Mail Test Connection",
      "encrypt": "false"
    },     
    {
      "key": "Unsubscribe",
      "value": "true",
      "encrypt": "false"
    },
    {
      "key": "SenderName",
      "value": "User",
      "encrypt": "false"
    }
  ]
}

Test Email Configuration

The Engagement Server supports testing an email configuration that is set up by using the Add or Update Provider Configuration API.

URL

http://<host or ip>:<port>/api/v1/emailconfig/test

Method

POST

Header

This API does not use a payload header.

Input Parameters

Input Parameter Level – Two Required Type Description
provider   Required String The name of the email provider, for example: SENDGRID, OUTLOOK
properties   Required Array of JSON An array of configuration properties
  key Required String

The name of the property. The properties are specific to the provider.

For example, the following values are applicable for SendGrid:

  • Account Key
  • Auth Token
  • From
  • To
  • Subject
  • Content

For more information, refer to the sample requests in the following section.
  value Required String A value that corresponds to the key, for example, a value for the From key, is user.name@temenos.com.
  encrypt Required Boolean
(true/false)		 Specifies whether the value must be encrypted in the request.

Sample Request

{
  "provider": "SENDGRID",
  "properties":
  [
    {
      "key": "ACCOUNT_KEY",
      "value": "<account-key>",
      "encrypt": "false"
    },	
    {
      "key": "AUTH_TOKEN",
      "value": "<auth-token>",
      "encrypt": "true"
    },
	{
      "key": "Unsubscribe",
      "value": "true",
      "encrypt": "false"
    },
    {
      "key": "From",
      "value": "user.one@temenos.com",
      "encrypt": "false"
    },
    {
      "key": "To",
      "value": "user.two@gmail.com",
      "encrypt": "false"
    },
    {
      "key": "Subject",
      "value": "SendGrid Mail Test Connection",
      "encrypt": "false"
    },
    {
      "key": "Content",
      "value": "SendGrid Mail Test Connection",
      "encrypt": "false"
    },
	{
		"key": "SenderName",
		"value": "User",
		"encrypt": "false"
	}
  ]
}
{
  "provider": "OUTLOOK",
  "properties":
  [
    {
      "key": "TENANT_ID",
      "value": "<tenant-id>",
      "encrypt": "false"
    },     
    {
      "key": "CLIENT_ID",
      "value": "<client-id>",
      "encrypt": "false"
    },
    {
      "key": "CLIENT_SECRET",
      "value": "<client-secret>",
      "encrypt": "true"
    },     
    {
      "key": "FROM_OBJECT_ID",
      "value": "<user-object-id>",
      "encrypt": "false"
    },
    {
      "key": "GRANT_TYPE",
      "value": "client_credentials",
      "encrypt": "false"
    },     
    {
      "key": "SCOPE_URL",
      "value": "https://graph.microsoft.com/.default",
      "encrypt": "false"
    },
    {
      "key": "AUTHENTICATE_URL",
      "value": "https://login.microsoftonline.com/##TenantId##/oauth2/v2.0/token",
      "encrypt": "false"
    },     
    {
      "key": "SEND_MAIL_URL",
      "value": "https://graph.microsoft.com/v1.0/users/##SenderMailObjectId##/sendMail",
      "encrypt": "false"
    },
    {
      "key": "From",
      "value": "user.one@temenos.com",
      "encrypt": "false"
    },   
    {
      "key": "To",
      "value": "user.two@temenos.com",
      "encrypt": "false"
    },     
    {
      "key": "Subject",
      "value": "Outlook Mail Test Connection",
      "encrypt": "false"
    },
    {
      "key": "Content",
      "value": "Outlook Mail Test Connection",
      "encrypt": "false"
    },     
    {
      "key": "Unsubscribe",
      "value": "true",
      "encrypt": "false"
    },
    {
      "key": "SenderName",
      "value": "User",
      "encrypt": "false"
    }
  ]
}

Response Codes

Status Code Description Retry

200

No error

False

201

Successfully created

False

204

Successfully deleted

False

400

Bad request

False

401

Requires authentication

False

403

From address doesn't match Verified Sender Identity. To learn how to resolve this error, see our Sender Identity requirements.

False

406

Missing Accept header. For example: Accept: application/json

False

429

Too many requests/Rate limit exceeded

True

500

Internal server error

True

999

Any other generic error not handled by SendGrid (like an I/O error).

True
Status code Status message Description Retry

400

Bad Request

Cannot process the request because it is malformed or incorrect.

False

401

Unauthorized

Required authentication information is either missing or not valid for the resource.

False

403

Forbidden

Access is denied to the requested resource. The user might not have enough permission.

Important: If conditional access policies are applied to a resource, a HTTP 403; Forbidden error=insufficient claims may be returned. For more details on Microsoft Graph and conditional access see Developer Guidance for Azure Active Directory Conditional Access

False

404

Not Found

The requested resource doesn’t exist.

False

405

Method Not Allowed

The HTTP method in the request is not allowed on the resource.

False

406

Not Acceptable

This service doesn’t support the format requested in the Accept header.

False

409

Conflict

The current state conflicts with what the request expects. For example, the specified parent folder might not exist.

False

410

Gone

The requested resource is no longer available at the server.

False

411

Length Required

A Content-Length header is required on the request.

False

412

Precondition Failed

A precondition provided in the request (such as an if-match header) does not match the resource's current state.

False

413

Request Entity Too Large

The request size exceeds the maximum limit.

False

415

Unsupported Media Type

The content type of the request is a format that is not supported by the service.

False

416

Requested Range Not Satisfiable

The specified byte range is invalid or unavailable.

False

422

Unprocessable Entity

Cannot process the request because it is semantically incorrect.

False

423

Locked

The resource that is being accessed is locked.

True

429

Too Many Requests

Client application has been throttled and should not attempt to repeat the request until an amount of time has elapsed.

True

500

Internal Server Error

There was an internal server error while processing the request.

True

501

Not Implemented

The requested feature isn’t implemented.

True

503

Service Unavailable

The service is temporarily unavailable for maintenance or is overloaded. You may repeat the request after a delay, the length of which may be specified in a Retry-After header.

True

504

Gateway Timeout

The server, while acting as a proxy, did not receive a timely response from the upstream server it needed to access in attempting to complete the request. May occur together with 503.

True

507

Insufficient Storage

The maximum storage quota has been reached.

True

509

Bandwidth Limit Exceeded

Your app has been throttled for exceeding the maximum bandwidth cap. Your app can retry the request again after more time has elapsed.

True

999

Other Error

Any other generic error not handled by Outlook (like an I/O error).

True