logo
API docs by Redocly

Marigold Engage Delivery Cloud API (1.0.0)

Team Marigold Engage: info@meetmarigold.com URL: https://developers.meetmarigold.com/engage/
https://developers.meetmarigold.com/engage

Marigold Engage Delivery Cloud API

By providing a fully documented API reference, we want to enable everyone to maximize the usage of the Marigold Engage Platform for automating & exchange data.

The Marigold Engage API is organized around the REST protocol with the use of HTTP verbs and a RESTful endpoint structure. The API provides resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. We strive to make the endpoints so self-explanatory and informative as possible, by providing clear validation, error and success responses.

The API style is inspired by the Microsoft API guidelines.

REST API

The EDC API endpoints are segmented.

Base URL

https://customername.module.slgnt.eu

Example: https://contoso.sdc.slgnt.eu/api/mobile/v1/push/send

Definition

  1. Customer name: refers to a unique subdomain per customer. In the example the customer is "contoso".

  2. Module: refers to a unique subdomain per product/application module. For this API reference the module is Engage ( Marigold Engage).

  3. slgnt.eu/slgnt.us: refers to the geographical area for which the customer instance is active.

    Europe: https://customername.module.slgnt.eu / United States: https://customername.module.slgnt.us

  4. Touchpoint: refers to the grouped entrypoint for the user to interact/interface with the application. For this API reference the touch point is the API.

  5. Component/Channel: refers to the channels (email/mobile/sms) or towards a specific component (like messages, reporting, …). In the example the channel is "push".

URI parts

https://baseUrl/chapter/versioning/entity(_type)/{identifier}/operation|result

Examples:

- Portal          https://contoso.sdc.slgnt.eu/api/portal/v1/policies/1234567890
- Mail            https://contoso.sdc.slgnt.eu/api/mail/v1/send

Definition

  1. Part 0: Base URL - The base url is a reference to the customer domain.
  2. Part 1: Channel - Refers to the EDC channels: e-mail, mobile, sms, ...
  3. Part 2: Version number - major numbering only - example: v2. In case no version number is part, it refers to the initial API version.
  4. Part 3: Entity(_type) - Refers to entity or entity type. This is depends on the chapter, if it is needed or not.
  5. Part 4: Identifier - Refers to the unique identifier for a specific entity.
  6. Part 5: Operation|Result - Refers to additional operations or specific sub-entities of the parent entity. This is depends on the chapter, if it is needed or not. Examples: lists > fields / journeys > send

Versioning

Currently, we are introducing a new version of the EDC REST API. The version number is part of the URI part of the API endpoint.

When we make improvements to the current version of the API endpoints, we strive to make only backwards-incompatible changes. We release improvements or new endpoints regularly. Read our API changelog to stay up-to-date with the latest changes.

Example for V2 for push: https://contoso.sdc.slgnt.eu/api/mobile/v2/push

Example for V3 for push: https://contoso.sdc.slgnt.eu/api/mobile/v3/push

Authentication

The Marigold Engage Delivery Cloud API uses the Oauth2.0 authorisation protocol, through bearer JSON Web Tokens (JWT), to authenticate requests. Engage will provide you with a dedicated client ID and secret to authorize using OAuth.

With each API call, you will need to set request headers including your access key to authenticate yourself.

The client ID and secret carry significant privileges. Please ensure to keep them 100% secure. Do not share your Oauth client ID and Oauth client secret in publicly accessible areas such as versioning systems (GitHub, Bitbucket,... ) or client-side code.

Per tenant, you can receive up to 3 credentials. One is a default one created when the tenant is created. The default one should serve for dev purposes. The other 2 can be used as staging environment and production environment. For each of those credentials, different privileges can be assigned in terms of:

  • Account(s) it can access
  • Resources it can access
  • Messages it can send

Errors

Engage uses the conventional HTTP response codes to indicate successful or failed API requests.

Codes in the 2xx range indicate success.

Codes in the 4xx range indicate an input related error or validation restrictions.

Codes in the 5xx range indicate an error with Marigold Engage servers.

HTTP Status Codes Description
200 - OK We found the request resource
201 - Created The resource is successfully created
204 - No Content The requested resources is empty
400 - Bad Request There was an error with the request. The body of the response will have more info.
401 - Unauthorized The access key was incorrect
404 - Not found The resources cannot be found
405 - Method Not Allowed The method is not allowed
408 - Request Timeout The request is taking too long to respond
422 - Unprocessable Entity The resource couldn't be created
429 - Too Many Requests Too many requests hit the API too quickly
5xx - Server errors Something went wrong on our end. Please try again

400/422 - Bad / Validation request

In the case of a validation of bad request error, the body of the response includes a JSON formatted response that tells you exactly what's wrong.

Attributes

https://www.rfc-editor.org/rfc/rfc7807.txt

Attribute
Type Description
type String A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be "about:blank"
title String A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see [RFC7231], Section 3.4) codes.
status Integer The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem type.
detail String A human-readable explanation specific to this occurrence of the problem.
traceId String A reference ID to trace log within the SMC platform. This can be relevant for reporting to the support team.
errors[] Array An array of details about specific errors that led to this reported error.
errors[].field String The problematic field in your request related to the error if the error is specific.
errors[].error Integer A short string indicating the error code reported, for some errors that could be handled programmatically. In some cases, it can contain custom errors which are not documented error codes.
errors[].detail String An optional human-readable description of the error. You can use this to let the user know what they can do about the error.
errors[].index Integer An optional value which gives additional information about the position of the entity in the given entity batch/array. Only available when dealing with batch.

Entity failure :

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Validation errors",
  "status": 400,  
  "detail": "One or more validation errors occurred.",
  "traceId": "00-03f4894fecc1ae4498599fb8d5d16b5e-9d0a2aab93c57d41-00",
  "errors": [
      {        
        "field": "PhoneNumber",
        "error": "REQUIRED_FIELD",
        "message": "this field must not be null."
      },
      {
        "field": "age",
        "error": "INVALID_RANGE",
        "message": "value should be between 0 and 99."
      },
      {
        "field": "Address",
        "error": "INVALID_ADDRESS",
        "message": "Address is not valid."
      },
      {
        "field": "customField1",
        "error": "the format of field 'customField1' is invalid."
      }
    ]
}

Bached entities :

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Validation errors",
  "status": 400,  
  "detail": "One or more validation errors occurred.",
  "traceId": "00-03f4894fecc1ae4498599fb8d5d16b5e-9d0a2aab93c57d41-00",
  "errors": [
      {
        "index": 0,
        "field": "reference",
        "error": "INVALID_REFERENCE_EMPTY",
        "detail": "Reference is empty"
      },
      {
        "index": 1,
        "field": "context.tags",
        "error": "INVALID_TAG_EMPTY",
        "detail": "Tag can not be null or empty!"
      },
      {
       "index": 2,
       "field": "content.title",
       "error": "INVALID_EMPTY_TITLE",
       "detail": "Title cannot be empty"
      }
    ]
}

Global error codes

Code Description
REQUIRED_PROPERTY property is required.
INVALID_REFERENCE_EMPTY Message reference can not be empty.
INVALID_REFERENCE_LENGTH Message reference length threshold exceeded (64).
INVALID_REFERENCE_CHAR Message reference can only contain letters,'-' and digits.
INVALID_TYPE Request property type doesn't match expected type.
INVALID_TAG_LENGTH Tag length can not be more than 96 bytes.
INVALID_TAG_EMPTY Tag can not be null or empty.
INVALID_TAG_CHAR Tag contains an invalid character: '/'.
INVALID_METADATA_LENGTH Metadata can not contain more than 140 characters
INVALID_PROFILE_LENGTH Profile can not contain more than 140 characters

e-mail error codes

Code Description
INVALID_SUBJECT_EMPTY e-mail 'Subject' can not be empty.
REQUIRED_TO_HEADER To: header is required.
REQUIRED_TO_ADDRESS To: Address is required.
REQUIRED_FROM_HEADER From: header is required.
REQUIRED_FROM_ADDRESS From: Address is required.
REFERENCE_DUPLICATE_DETECTED Duplicate references have been detected in the batch
Duplicate headers detected: [{0}]. Duplicate headers detected: [{0}]. '{0}' contains the list of duplicated headers
Error for optional header: name can not be null or empty. Error for optional header: name can not be null or empty.
Error for optional header: name can not be null or empty. Error for optional header: name can not be null or empty.
Error for optional header [{header.Name}]: value can not be null or empty Error for optional header [{header.Name}]: value can not be null or empty
Error for header [{header.Name}]: name of custom headers should start with 'X-'. Error for header [{header.Name}]: name of custom headers should start with 'X-'.
Error for header {header.Name}: A field name MUST be composed of printable US - ASCII characters (i.e., characters that have values between 33 and 126, inclusive), except colon Error for header {header.Name}: A field name MUST be composed of printable US - ASCII characters (i.e., characters that have values between 33 and 126, inclusive), except colon
Error for header {header.Value}:A field value MUST be composed of US - ASCII characters Error for header {header.Value}:A field value MUST be composed of US - ASCII characters
The api call does not support recipient overrides. Change the addressee instead. The api call does not support recipient overrides. Change the addressee instead.

Mobile error codes

Code Description
INVALID_EMPTY_TOKEN Device token is required for bulk send.
INVALID_EMPTY_TITLE Push notification title is mandatory when sending none silent notification.
INVALID_EMPTY_BODY Push notification body is mandatory when sending none silent notification.
MISSING_APP_CONFIG No configuration available for this Mobile App.";
MISSING_PROVIDER_CONFIG_APPLE Not credentials are defined for 'apple'.
MISSING_PROVIDER_CONFIG_GOOGLE Not credentials are defined for 'google'.
MISSING_PROVIDER_CONFIG_HUAWEI Not credentials are defined for 'huawei'.
UNKNOWN_PROVIDER Unknown provider '{0}'.
BRCST_OPERATION_NOT_FOUND Broadcast operation not found.
INAPP_CONTENT_NOT_ALLOWED InApp content is not allowed for simple push type. Use 'PushWithInApp' type of 'Silent'.
INVALID_INAPP_EMPTY_TITLE InApp content title is mandatory.
INVALID_INAPP_EMPTY_BODY InApp content body is mandatory.
INVALID_TEMPLATE_REFERENCE Invalid template reference specified.

OpenAPI specification

We provide the API specification in the format of OpenApi files which can be found in the openapi/ directory:

The older Swagger/OpenAPI 2.0 is also available, but will be deprecated over time, since we are in favor of newer OpenAPI specification 3.0.

Postman collection

To get you up and running and provide a hands-on experience, we provide an up-to-date Postman collection of the EDC API V1.

Import the Postman collection through any of the methods specified below.

This collection takes advantage of Postman variables and environments to store/access your Marigold Engage Oauth Client key/secret and base URL.

Message sending

Early Access

When you want to send a series of messages to a range of contacts, it is advised to group the messages and send them to EDC in bulk. EDC will process all messages in the payload one by one (bulk processing).

/email/v1/messages/send - Send a range of e-mail messages
/mobile/v1/messages/push/send - Send a range of mobile push messages

All the API operations are described in detail per type.

Send e-mail messages

Send a single e-mail message or messages in bulk to a range of recipients.

Limitations:

  • Maximum 100 messages per request are accepted.
  • Maximum JSON body size is 4 MB (message including encoded attachments).
header Parameters
Authorization
string
Default: Bearer {{oauth_access_token}}
Example: Bearer {{oauth_access_token}}

Oauth2 token to authorize requests.

Content-Type
required
string
Default: application/json
Example: application/json

Define the file type and format for the request object.

Request Body schema: application/json
Array
reference
required
string non-empty

A reference for keeping track of the message. This reference can be chosen freely and should be unique. Note that uniqueness is not enforced.

required
object

The content of the e-mail message.

required
object

The mail headers of the e-mail message.

object

Use the context to pass relevant information along with each message.

custom_send_time
string or null

Can be used to specify a date time for sending message, instead of sending it instantly. The date time can be entered in UTC format. Sending cannot be scheduled more than 24 hours in advance.

time_to_live
string or null
Default: "P2D"

The expiration time after which the message is deleted, regardless of state. This value is expressed as an ISO 8601 duration. The maximum time-to-life that can be defined is 2 days or 48 hours.

Examples: P2D = 2 days, PT30M = 30 minutes, PT10S = 10 seconds

archive_enabled
boolean or null

Only available with Message Archiving
Overwrites the default tenant setting for archiving messages.
If true, the message will be archived.
If false, the message will not be archived.
If null or not provided, the default setting for the tenant will be used.

archive_duration
string or null

Only available with Message Archiving
Overwrites the default tenant setting for how long messages will be archived.
The value should be expressed in the ISO 8601 duration format and must at minimum be 1 day.
If set, the message will be archived for the specified duration, unless that duration is bigger than the default setting specified on the tenant.
If null or not provided, the default setting for the tenant will be used.
Examples: P2D = 2 days, P5M = 5 months, P2Y = 2 years

priority
string or null
Default: "low"
Enum: "low" "normal" "high"

The priority level for this email. Emails with a higher priority will be pushed higher in the queue for processing.
The system applies a smart structure to not starve other mailings. For that reason, there are limits in place for each level of priority:

  • high: 1000 / min
  • medium: 5000 / min
  • low: No limit
If the cap is reached, new mailings will be pushed one step lower in priority
(high -> medium, medium -> low), without warning in the response of the API.
We will never block mails in a specific priority level if the rate is hit.

Responses

Request samples

Content type
application/json
Example
[
  • {
    • "reference": "2a0a0b3e71874163860d496b0283a790",
    • "content": {
      • "html": "<html>This is the HTML content of the message</html>",
      • "text": "This is the Text content of the message",
      • "attachments": [
        ]
      },
    • "headers": {
      • "subject": "Hello world from EDC",
      • "to": {
        },
      • "from": {
        },
      • "reply": {
        },
      • "list_unsubscribe": "<https://www.example.com/unsubscribe.aspx?ID=123456>, <mailto:unsubscribe@example.com?subject=unsubscribe 123456>",
      • "optional": [
        ]
      },
    • "context": {
      • "tags": [
        ],
      • "metadata": "{\"name\":\"john\",\"ref\":123}",
      • "profile": "12345-ABCDEFG-6789"
      },
    • "custom_send_time": "2022-09-02T12:00:00",
    • "time_to_live": "P2D",
    • "archive_enabled": true,
    • "archive_duration": "P30D"
    }
]

Statistics

Get the deliverabiliy statistics

Retrieves the deliverability statistics in the specified timerange

query Parameters
start
string
Example: start=2022-01-01T13:00:56Z

Beginning of time range, expressed as ISO-8601 timestamp in UTC.

end
string
Example: end=2022-12-31T13:00:56Z

End of time range, expressed as ISO-8601 timestamp in UTC.

header Parameters
Authorization
string
Default: Bearer {{oauth_access_token}}
Example: Bearer {{oauth_access_token}}

Oauth2 token to authorize requests.

Content-Type
required
string
Default: application/json
Example: application/json

Define the file type and format for the request object.

Responses

Response Schema: application/json
[ 0 .. 100 ] items
Array of objects

An array of statistic items per time window

Array
window
required
string

The time window in which the metrics occurred

object

The actual metrics of the totals per event type within the window

Response samples

Content type
application/json
{
  • "value": [
    • {
      • "window": "2022-04-08T13:36:00+00:00",
      • "counters": {
        }
      }
    ]
}

Message archive

Early Access

Marigold Engage Delivery cloud stores the exact message of what was send and make it accessible via the Message Archive API to review and get the content per message/per contact.

The Message Archive API provides a search facility to find the message, or messages, tied to an profile of the recipient.

/archive - Lists all messages for a profile
/archive/{messageId} - Gets all the data for a single message
/archive/{messageId}/download - Downloads a message
/archive/{messageId}/download/{fileName} - Downloads an attachment of the message
/archive/{messageId}/preview - Preview a message in html or as PDF file

All the API operations are described in detail per type.

Get messages for a profile

Browse through the list of archived messages for a profile.

Currently limited to the last 100 messages. Paging & date range filtering are available.

path Parameters
profileId
required
string or null
Example: 12345-ABCDEFG-6789

The unique identifier of a profile. For SMC customers, this would be a combination of the reference of properties : LISTID.USERID

query Parameters
start
string
Example: start=2023-01-01

Beginning of date range, expressed as ISO-8601 format. If not set, all the data since the 1st record will be returned.

end
string
Example: end=2022-12-31

End of date range, expressed as ISO-8601 format. If not set, all the items up untill now will be returned.

$top
integer <int32>
Default: 100

The number of records to return, used for pagination.

$skip
integer <int32>
Default: 0

The number of items to skip over before returning items

$count
boolean
Default: false

Request a count of matching items included with the results.

header Parameters
Authorization
string
Default: Bearer {{oauth_access_token}}
Example: Bearer {{oauth_access_token}}

Oauth2 token to authorize requests.

Content-Type
required
string
Default: application/json
Example: application/json

Define the file type and format for the request object.

Responses

Response Schema: application/json
Array of objects

List of sent messages, based on the query options.

Array
message_id
required
string

This is a unique message ID, which can be referenced to the message ID used in the sending API.

channel
required
string or null
Enum: "email" "mobile" "sms"

This is the channel of the sent message.

tags
Array of strings or null

A list of tags for the send message. Tags are useful for group reporting & filtering.

metadata
string or null

A custom field that can be used for passing on external metadata through the sending API. The metadata will be included in the feedback data. This can be a string or stringified JSON object.

profile
string

A unique reference for the recipient of the message. The profile reference can be used in all channels for search & filter capabilities in reporting & for looking up messages in the archive.

Array of objects

OPTIONAL: The list of filed attachments, that is attached to the message. Only applicable for e-mail messages.

subject
string

OPTIONAL: The subject of message. Only applicable for e-mail messages.

timestamp
required
string

The time the event happened, expressed in UTC.

time_to_live
required
integer

The expiration time in seconds after which the message is deleted, regardless of state. For example, 1 month is 2630000 seconds, 1 year is 31536000 seconds.

@count
integer <int64>

The total amount of items across all pages. Add $count=true to the querystring to indicate to the server that this value is required.

@previous_link
string

An opaque URL that can be used to paginate the results of the request.

@next_link
string

An opaque URL that can be used to paginate the results of the request.

Response samples

Content type
application/json
{}

Delete messages for a profile

Delete all archived messages for a profile. The messages are deleted in an asynchronous way.

path Parameters
profileId
required
string or null
Example: 12345-ABCDEFG-6789

The unique identifier of a profile. For SMC customers, this would be a combination of the reference of properties : LISTID.USERID

header Parameters
Authorization
string
Default: Bearer {{oauth_access_token}}
Example: Bearer {{oauth_access_token}}

Oauth2 token to authorize requests.

Content-Type
required
string
Default: application/json
Example: application/json

Define the file type and format for the request object.

Responses

Get a message

Get all the metadata for a single message.

path Parameters
profileId
required
string or null
Example: 12345-ABCDEFG-6789

The unique identifier of a profile. For SMC customers, this would be a combination of the reference of properties : LISTID.USERID

messageId
required
string
Example: message-12345-abcde-6789

The unique identifier of the message.

query Parameters
$tracking
boolean
Default: false

Request the tracking events for the matching message, to be included with the returned results

header Parameters
Authorization
string
Default: Bearer {{oauth_access_token}}
Example: Bearer {{oauth_access_token}}

Oauth2 token to authorize requests.

Content-Type
required
string
Default: application/json
Example: application/json

Define the file type and format for the request object.

Responses

Response Schema: application/json
message_id
required
string

This is a unique message ID, which can be referenced to the message ID used in the sending API.

channel
required
string or null
Enum: "email" "mobile" "sms"

This is the channel of the sent message.

tags
Array of strings or null

A list of tags for the send message. Tags are useful for group reporting & filtering.

metadata
string or null

A custom field that can be used for passing on external metadata through the sending API. The metadata will be included in the feedback data. This can be a string or stringified JSON object.

profile
string

A unique reference for the recipient of the message. The profile reference can be used in all channels for search & filter capabilities in reporting & for looking up messages in the archive.

Array of objects

OPTIONAL: The list of filed attachments, that is attached to the message. Only applicable for e-mail messages.

Array
file_name
string unique

The file name of the attached file. This has to be unique within the list of attachments of the message.

mime_type
string

The mime type of the attached file

subject
string

OPTIONAL: The subject of message. Only applicable for e-mail messages.

timestamp
required
string

The time the event happened, expressed in UTC.

time_to_live
required
integer

The expiration time in seconds after which the message is deleted, regardless of state. For example, 1 month is 2630000 seconds, 1 year is 31536000 seconds.

Array of objects

List of tracking events for a message.

Array
id
string

Unique reference for the tracking event.

external_reference
required
string non-empty

A reference for keeping track of the message. This reference can be chosen freely and should be unique. Note that uniqueness is not enforced.

type
required
string
Enum: "sdc.archive.email.archived" "sdc.api.email.accepted" "sdc.imports.email" "sdc.deliveries.email.deferred" "sdc.deliveries.email.sent" "sdc.deliveries.email.failed" "sdc.bounces.email.bounced" "sdc.bounces.email.complaintfiled" "sdc.bounces.email.listunsubscribed"

Possible values are all the possible steps a message will take within the system.

timestamp
required
string <date-time>

The time the event happened, expressed in UTC.

description
required
string

The description of the event.

Response samples

Content type
application/json
{
  • "message_id": "674d25d7319b4549a88cefdda049989e_92233793802426",
  • "channel": "email",
  • "tags": [
    • "zuppy-bounce",
    • "resto-order-now-campaign-feb"
    ],
  • "metadata": "{\"name\":\"jane.doe\",\"ref\":123456789}",
  • "profile": "crm-id-123456789",
  • "attachments": [
    • {
      • "file_name": "message_attachment.pdf",
      • "mime_type": "application/pdf"
      }
    ],
  • "subject": "Hello world from EDC",
  • "timestamp": "2022-03-16T12:56:00.1260605+00:00",
  • "time_to_live": 31536000,
  • "tracking": [
    • {
      • "id": "351395fa8d2c4fe3ad0fcce08f561491",
      • "external_reference": "2a0a0b3e71874163860d496b0283a790",
      • "type": "com.sdc.deliveries.email.sent",
      • "timestamp": "2022-03-16T12:56:00Z",
      • "description": "Message ID 202203161230539493 accepted for delivery"
      }
    ]
}

Delete a message

Synchronously deletes a specific archived message.

path Parameters
profileId
required
string or null
Example: 12345-ABCDEFG-6789

The unique identifier of a profile. For SMC customers, this would be a combination of the reference of properties : LISTID.USERID

messageId
required
string
Example: message-12345-abcde-6789

The unique identifier of the message.

header Parameters
Authorization
string
Default: Bearer {{oauth_access_token}}
Example: Bearer {{oauth_access_token}}

Oauth2 token to authorize requests.

Content-Type
required
string
Default: application/json
Example: application/json

Define the file type and format for the request object.

Responses

Download a message

Get an archived message in channel specific format (.eml, .push, .sms).

path Parameters
profileId
required
string or null
Example: 12345-ABCDEFG-6789

The unique identifier of a profile. For SMC customers, this would be a combination of the reference of properties : LISTID.USERID

messageId
required
string
Example: message-12345-abcde-6789

The unique identifier of the message.

header Parameters
Authorization
string
Default: Bearer {{oauth_access_token}}
Example: Bearer {{oauth_access_token}}

Oauth2 token to authorize requests.

Content-Type
required
string
Default: application/json
Example: application/json

Define the file type and format for the request object.

Responses

Response Schema: application/octet-stream
string <binary>

Download an attachment

Get the attachment of an archived message.

path Parameters
profileId
required
string or null
Example: 12345-ABCDEFG-6789

The unique identifier of a profile. For SMC customers, this would be a combination of the reference of properties : LISTID.USERID

messageId
required
string
Example: message-12345-abcde-6789

The unique identifier of the message.

fileName
required
string
Example: message_attachement.pdf

The unique filename for a message attachment.

header Parameters
Authorization
string
Default: Bearer {{oauth_access_token}}
Example: Bearer {{oauth_access_token}}

Oauth2 token to authorize requests.

Responses

Response Schema: application/octet-stream
string <binary>

Preview a message

Preview a single archived message as HTML or as PDF file.

path Parameters
profileId
required
string or null
Example: 12345-ABCDEFG-6789

The unique identifier of a profile. For SMC customers, this would be a combination of the reference of properties : LISTID.USERID

messageId
required
string
Example: message-12345-abcde-6789

The unique identifier of the message.

header Parameters
Authorization
string
Default: Bearer {{oauth_access_token}}
Example: Bearer {{oauth_access_token}}

Oauth2 token to authorize requests.

Accept
required
string
Default: */*
Example: application/pdf

Determines the format in which you want to preview. Allowed types: */*, text/html or application/pdf

Responses

Response Schema:
string <binary>

Response samples

Content type
No sample

Message tracking

Track a message

Get all message proccing & delivery events for a specific message reference.

path Parameters
messageId
required
string
Example: message-12345-abcde-6789

The unique identifier of the message.

header Parameters
Authorization
string
Default: Bearer {{oauth_access_token}}
Example: Bearer {{oauth_access_token}}

Oauth2 token to authorize requests.

Content-Type
required
string
Default: application/json
Example: application/json

Define the file type and format for the request object.

Responses

Response Schema: application/json
required
Array of objects

List of processing events for a message.

Array
id
string

Unique reference for the tracking event.

external_reference
required
string non-empty

A reference for keeping track of the message. This reference can be chosen freely and should be unique. Note that uniqueness is not enforced.

type
required
string
Enum: "sdc.archive.email.archived" "sdc.api.email.accepted" "sdc.imports.email" "sdc.deliveries.email.deferred" "sdc.deliveries.email.sent" "sdc.deliveries.email.failed" "sdc.bounces.email.bounced" "sdc.bounces.email.complaintfiled" "sdc.bounces.email.listunsubscribed"

Possible values are all the possible steps a message will take within the system.

timestamp
required
string <date-time>

The time the event happened, expressed in UTC.

description
required
string

The description of the event.

Response samples

Content type
application/json
{
  • "value": [
    • {
      • "id": "351395fa8d2c4fe3ad0fcce08f561491",
      • "external_reference": "2a0a0b3e71874163860d496b0283a790",
      • "type": "com.sdc.deliveries.email.sent",
      • "timestamp": "2022-03-16T12:56:00Z",
      • "description": "Message ID 202203161230539493 accepted for delivery"
      }
    ]
}

Bounces

Get Bounces

Get Bounces

query Parameters
start
string
Example: start=2023-01-01

Beginning of date range, expressed as ISO-8601 format. If not set, all the data since the 1st record will be returned.

end
string
Example: end=2022-12-31

End of date range, expressed as ISO-8601 format. If not set, all the items up untill now will be returned.

$top
integer <int32>
Default: 100

The number of records to return, used for pagination.

$skip
integer <int32>
Default: 0

The number of items to skip over before returning items

type
string
Enum: "direct" "indirect"
Example: type=direct

Bounce Mode

accountId
string
Default: null
header Parameters
Authorization
string
Default: Bearer {{oauth_access_token}}
Example: Bearer {{oauth_access_token}}

Oauth2 token to authorize requests.

Content-Type
required
string
Default: application/json
Example: application/json

Define the file type and format for the request object.

Responses

Response Schema: application/json
Array of objects

List of Bounces.

Array
account_id
string non-empty

The unique ID for the account.

mapping
string
Enum: "soft" "hard" "spam"

Bounce type

mode
required
string
Enum: "direct" "indirect"

Bounce Mode

external_reference
required
string non-empty
timestamp
required
string <date-time>
domain
string or null
outcome
string or null
outcome_category
string
Enum: "none" "error" "ok" "greyListed" "blackListed" "badUser" "unavailable" "senderProblem" "mailboxFull" "spam" "receiverProblem" "exclusion"

The SMTP outcome response outcome_category:

  • none - Unable to categorize the outcome.
  • error - Something went wrong in the Smtp protocol, for example a network or protocol error.
  • ok - The message was delivered successfully.
  • greyListed - The message is greylisted and MUST be deferred and then be sent over the same route.
  • blackListed - The message is not delivered and marked as undeliverable.
  • badUser - The message is not delivered because of varies reasons such as an invalid or unknown user, an unrouteable address, bad authentication etc... .
  • unavailable - The message is not delivered because the user or account is inactive or the mailbox has been blocked.
  • senderProblem - The message is not delivered and will be retried.
  • mailboxFull - The message is not delivered because the recipient mailbox was full.
  • spam - The message is not delivered because it is marked as spam.
  • receiverProblem - The message is not delivered and will be retried. Causes can be a temporary receiver issue, too busy mailbox, local server issues, etc... .
  • exclusion - The message hit an exclusion and further messages should not be sent to the same domain over the same IP until the duration has expired.
finalize_reason
string
Enum: "tooManyRetries" "tooManyDeferrals" "importBlacklist" "importFailed" "expired" "restriction" "mxServersDenied" "noMxServersAssigned" "nonExistingDomainName" "hardBounce" "badTemplate" "cancelled" "clientCancelled" "greyListed"

The reason why the mail could not be delivered:

  • tooManyRetries - The message is not delivered and will not be retried. Applicable for outcome categories None, Error, SenderProblem and ReceiverProblem.
  • tooManyDeferrals - The message is not delivered and will not be retried. Applicable for outcome categories Excluded and GreyListed and for Restrictions.
  • importBlacklist - The message is not delivered and marked as blacklisted on our side.
  • importFailed - The message could not be properly processed during the importing phase because of various reasons such as DKIM issues, account and tenant validation errors, etc.. .
  • expired - The message is not delivered and marked as expired because it has been in our system for too long (> 48 hours).
  • restriction - The message is not delivered and cancelled due to internal restriction.
  • mxServersDenied - The message is not delivered because the resolved MX servers are marked as denied on our side.
  • noMxServersAssigned - The message is not delivered because there where no MX servers assigned to the domain.
  • nonExistingDomainName - The message is not delivered because the recipient domain does not exist.
  • hardBounce - The message is not delivered because of a permanent reason, see the outcome category for more information.
  • badTemplate - The message is not delivered because the provided template could not be rendered properly.
  • cancelled - The message is not delivered because it has been restricted or because and administrator decided to cancel its import.
  • clientCancelled - The message is not delivered because the client decided to cancel it.
  • greyListed - The message is greylisted and MUST be deferred and then be sent over the same route.
mailbox
string or null
list_unsubscribe_header
string or null

Response samples

Content type
application/json
{
  • "value": [
    • {
      • "account_id": "3822afb319684af18b9664ee327b7c44",
      • "mapping": "hard",
      • "mode": "direct",
      • "external_reference": "674d25d7319b4549a88cefdda049989e_92233793802426",
      • "timestamp": "2023-07-25T19:19:00.0378723+00:00",
      • "finalize_reason": "hardBounce",
      • "outcome": "452 System is busy",
      • "outcome_category": "exclusion",
      • "domain": "example.com"
      },
    • {
      • "account_id": "3822afb319684af18b9664ee327b7c44",
      • "mapping": "spam",
      • "mode": "indirect",
      • "external_reference": "674d25d7319b4549a88cefdda049989e_92233793802426",
      • "timestamp": "2023-07-26T19:19:00.0378723+00:00",
      • "mailbox": "bounces@yourdomain.slgnt.us",
      • "domain": "example.com"
      }
    ]
}

Get List Unsubscribes

Get List Unsubscribes

query Parameters
start
string
Example: start=2023-01-01

Beginning of date range, expressed as ISO-8601 format. If not set, all the data since the 1st record will be returned.

end
string
Example: end=2022-12-31

End of date range, expressed as ISO-8601 format. If not set, all the items up untill now will be returned.

$top
integer <int32>
Default: 100

The number of records to return, used for pagination.

$skip
integer <int32>
Default: 0

The number of items to skip over before returning items

accountId
string
Default: null
header Parameters
Authorization
string
Default: Bearer {{oauth_access_token}}
Example: Bearer {{oauth_access_token}}

Oauth2 token to authorize requests.

Content-Type
required
string
Default: application/json
Example: application/json

Define the file type and format for the request object.

Responses

Response Schema: application/json
Array of objects

List of Bounces.

Array
account_id
string non-empty

The unique ID for the account.

external_reference
string non-empty
timestamp
required
string <date-time>
mailbox
string or null
domain
string or null
list_unsubscribe_header
string or null

Response samples

Content type
application/json
{
  • "value": [
    • {
      • "account_id": "3822afb319684af18b9664ee327b7c44",
      • "external_reference": "674d25d7319b4549a88cefdda049989e_92233793802426",
      • "timestamp": "2023-07-25T19:19:00.0378723+00:00",
      • "mailbox": "unsubscribe@yourdomain.slgnt.us",
      • "list_unsubscribe_header": "<http://www.example.com/unsubscribe.aspx?ID=123456>, <mailto:unsubscribe@example.com?subject=unsubscribe 123456>",
      • "domain": "example.com"
      },
    • {
      • "account_id": "3822afb319684af18b9664ee327b7c44",
      • "external_reference": "674d25d7319b4549a88cefdda049989e_92233793802426",
      • "timestamp": "2023-07-26T19:19:00.0378723+00:00",
      • "mailbox": "unsubscribe@yourdomain.slgnt.us",
      • "list_unsubscribe_header": "<http://www.example.com/unsubscribe.aspx?ID=123456>, <mailto:unsubscribe@example.com?subject=unsubscribe 123456>",
      • "domain": "example.com"
      }
    ]
}

Get Complaints

Get Complaints

query Parameters
start
string
Example: start=2023-01-01

Beginning of date range, expressed as ISO-8601 format. If not set, all the data since the 1st record will be returned.

end
string
Example: end=2022-12-31

End of date range, expressed as ISO-8601 format. If not set, all the items up untill now will be returned.

$top
integer <int32>
Default: 100

The number of records to return, used for pagination.

$skip
integer <int32>
Default: 0

The number of items to skip over before returning items

accountId
string
Default: null
header Parameters
Authorization
string
Default: Bearer {{oauth_access_token}}
Example: Bearer {{oauth_access_token}}

Oauth2 token to authorize requests.

Content-Type
required
string
Default: application/json
Example: application/json

Define the file type and format for the request object.

Responses

Response Schema: application/json
Array of objects

List of Bounces.

Array
account_id
string non-empty

The unique ID for the account.

external_reference
required
string non-empty
timestamp
required
string <date-time>
mailbox
string or null
domain
string or null

Response samples

Content type
application/json
{
  • "value": [
    • {
      • "account_id": "3822afb319684af18b9664ee327b7c44",
      • "external_reference": "674d25d7319b4549a88cefdda049989e_92233793802426",
      • "timestamp": "2023-07-25T19:19:00.0378723+00:00",
      • "mailbox": "complaints@yourdomain.slgnt.us",
      • "domain": "example.com"
      },
    • {
      • "account_id": "3822afb319684af18b9664ee327b7c44",
      • "external_reference": "674d25d7319b4549a88cefdda049989e_92233793802426",
      • "timestamp": "2023-07-26T19:19:00.0378723+00:00",
      • "mailbox": "complaints@yourdomain.slgnt.us",
      • "domain": "example2.com"
      }
    ]
}

Find a bounce by external reference id

Find a bounce by external reference id

path Parameters
messageId
required
string
Example: message-12345-abcde-6789

The unique identifier of the message.

header Parameters
Authorization
string
Default: Bearer {{oauth_access_token}}
Example: Bearer {{oauth_access_token}}

Oauth2 token to authorize requests.

Content-Type
required
string
Default: application/json
Example: application/json

Define the file type and format for the request object.

Responses

Response Schema: application/json
account_id
string non-empty

The unique ID for the account.

mapping
string
Enum: "soft" "hard" "spam"

Bounce type

mode
required
string
Enum: "direct" "indirect"

Bounce Mode

external_reference
required
string non-empty
timestamp
required
string <date-time>
domain
string or null
outcome
string or null
outcome_category
string
Enum: "none" "error" "ok" "greyListed" "blackListed" "badUser" "unavailable" "senderProblem" "mailboxFull" "spam" "receiverProblem" "exclusion"

The SMTP outcome response outcome_category:

  • none - Unable to categorize the outcome.
  • error - Something went wrong in the Smtp protocol, for example a network or protocol error.
  • ok - The message was delivered successfully.
  • greyListed - The message is greylisted and MUST be deferred and then be sent over the same route.
  • blackListed - The message is not delivered and marked as undeliverable.
  • badUser - The message is not delivered because of varies reasons such as an invalid or unknown user, an unrouteable address, bad authentication etc... .
  • unavailable - The message is not delivered because the user or account is inactive or the mailbox has been blocked.
  • senderProblem - The message is not delivered and will be retried.
  • mailboxFull - The message is not delivered because the recipient mailbox was full.
  • spam - The message is not delivered because it is marked as spam.
  • receiverProblem - The message is not delivered and will be retried. Causes can be a temporary receiver issue, too busy mailbox, local server issues, etc... .
  • exclusion - The message hit an exclusion and further messages should not be sent to the same domain over the same IP until the duration has expired.
finalize_reason
string
Enum: "tooManyRetries" "tooManyDeferrals" "importBlacklist" "importFailed" "expired" "restriction" "mxServersDenied" "noMxServersAssigned" "nonExistingDomainName" "hardBounce" "badTemplate" "cancelled" "clientCancelled" "greyListed"

The reason why the mail could not be delivered:

  • tooManyRetries - The message is not delivered and will not be retried. Applicable for outcome categories None, Error, SenderProblem and ReceiverProblem.
  • tooManyDeferrals - The message is not delivered and will not be retried. Applicable for outcome categories Excluded and GreyListed and for Restrictions.
  • importBlacklist - The message is not delivered and marked as blacklisted on our side.
  • importFailed - The message could not be properly processed during the importing phase because of various reasons such as DKIM issues, account and tenant validation errors, etc.. .
  • expired - The message is not delivered and marked as expired because it has been in our system for too long (> 48 hours).
  • restriction - The message is not delivered and cancelled due to internal restriction.
  • mxServersDenied - The message is not delivered because the resolved MX servers are marked as denied on our side.
  • noMxServersAssigned - The message is not delivered because there where no MX servers assigned to the domain.
  • nonExistingDomainName - The message is not delivered because the recipient domain does not exist.
  • hardBounce - The message is not delivered because of a permanent reason, see the outcome category for more information.
  • badTemplate - The message is not delivered because the provided template could not be rendered properly.
  • cancelled - The message is not delivered because it has been restricted or because and administrator decided to cancel its import.
  • clientCancelled - The message is not delivered because the client decided to cancel it.
  • greyListed - The message is greylisted and MUST be deferred and then be sent over the same route.
mailbox
string or null
list_unsubscribe_header
string or null

Response samples

Content type
application/json
{
  • "account_id": "3822afb319684af18b9664ee327b7c44",
  • "mapping": "soft",
  • "mode": "direct",
  • "external_reference": "674d25d7319b4549a88cefdda049989e_92233793802426",
  • "timestamp": "2023-07-25T19:19:00.0378723+00:00",
  • "finalize_reason": "hardBounce",
  • "outcome": "452 System is busy",
  • "outcome_category": "exclusion",
  • "domain": "example.com"
}

Accounts

Access information about your accounts and their settings.

Get all accounts

Returns a list of your EDC portal accounts for a certain tenant. The accounts are returned sorted by creation date.

header Parameters
Authorization
string
Default: Bearer {{oauth_access_token}}
Example: Bearer {{oauth_access_token}}

Oauth2 token to authorize requests.

Content-Type
required
string
Default: application/json
Example: application/json

Define the file type and format for the request object.

Responses

Response Schema: application/json
Array of objects

Result of the accounts for the tenant.

Array
id
string

The identifier of the account

name
string

The name of the account

enabled
boolean

Enable/disable an account

tags
Array of strings or null

Tags

description
string or null

A description of the account

archiveEnabled
boolean or null

Only available with Message Archiving
The default behavior for archiving messages in this tenant. This setting will be used if no explicit archiving settings are provided in requests.
If true, messages will be archived.
If false messages will not be archived.

archiveDuration
string or null

Only available with Message Archiving
The default tenant setting for how long messages will be archived.
This setting will be used if no explicit archiving settings are provided in requests.
This time is also the maximum allowed duration for storage of messages defined on this tenant.
The value isexpressed in the ISO 8601 duration format.
If set, the message will be archived for the specified duration by default, unless a shorter duration is provided in the request.
Examples: P2D = 2 days, P5M = 5 months, P2Y = 2 years

count
integer <int64>

The total amount of items across all pages. Add $count=true to the querystring to indicate to the server that this value is required.

previousLink
string

An opaque URL that can be used to paginate the results of the request.

nextLink
string

An opaque URL that can be used to paginate the results of the request.

Response samples

Content type
application/json
{}

Get a specific account

Retrieves the details of an existing account, by supplying the unique account identifier.

path Parameters
accountId
required
string or null
Example: account0-test-abcd-efgh-example12345

The unique identifier of the portal account.

header Parameters
Authorization
string
Default: Bearer {{oauth_access_token}}
Example: Bearer {{oauth_access_token}}

Oauth2 token to authorize requests.

Content-Type
required
string
Default: application/json
Example: application/json

Define the file type and format for the request object.

Responses

Response Schema: application/json
id
string

The identifier of the account

name
string

The name of the account

enabled
boolean

Enable/disable an account

tags
Array of strings or null

Tags

description
string or null

A description of the account

archiveEnabled
boolean or null

Only available with Message Archiving
The default behavior for archiving messages in this tenant. This setting will be used if no explicit archiving settings are provided in requests.
If true, messages will be archived.
If false messages will not be archived.

archiveDuration
string or null

Only available with Message Archiving
The default tenant setting for how long messages will be archived.
This setting will be used if no explicit archiving settings are provided in requests.
This time is also the maximum allowed duration for storage of messages defined on this tenant.
The value isexpressed in the ISO 8601 duration format.
If set, the message will be archived for the specified duration by default, unless a shorter duration is provided in the request.
Examples: P2D = 2 days, P5M = 5 months, P2Y = 2 years

Response samples

Content type
application/json
{
  • "id": "account0-test-abcd-efgh-example12345",
  • "name": "Contoso Marketing",
  • "enabled": true,
  • "tags": [
    • "Demo",
    • "Example"
    ],
  • "description": "example account",
  • "archiveEnabled": true,
  • "archiveDuration": "P365D"
}

Mail Domains

Retrieve all the maildomains belonging to a specific account.

Get all maildomains

Returns a list of your EDC portal maildomains for a certain tenant.

header Parameters
Authorization
string
Default: Bearer {{oauth_access_token}}
Example: Bearer {{oauth_access_token}}

Oauth2 token to authorize requests.

Content-Type
required
string
Default: application/json
Example: application/json

Define the file type and format for the request object.

Responses

Response Schema: application/json
Array of objects

Result of the maildomains for the tenant.

Array
name
required
string

The unique name of the mail domain

csaEnabled
boolean

Determines if a CSA header should be sent when using this maildomain. This value MUST be true for CSA companies and MUST be false for non-CSA companies.

listUnsubscribe
string or null

Determines the value of the list-unsubscribe header. (RFC 2369)

fromAddress
string

The default FROM address to use when sending with this maildomain.

fromEnvelope
string or null

The email address use to receive bounces.

replyAddress
string

The default REPLY address to use when sending with this maildomain.

object
count
integer <int64>

The total amount of items across all pages. Add $count=true to the querystring to indicate to the server that this value is required.

previousLink
string

An opaque URL that can be used to paginate the results of the request.

nextLink
string

An opaque URL that can be used to paginate the results of the request.

Response samples

Content type
application/json
{}

Get a specific maildomain

Retrieves the details of an existing maildomain, by supplying the unique name identifier.

path Parameters
mailDomainName
required
string or null
Example: service.example.eu

The unique identifier of the portal maildomain.

header Parameters
Authorization
string
Default: Bearer {{oauth_access_token}}
Example: Bearer {{oauth_access_token}}

Oauth2 token to authorize requests.

Content-Type
required
string
Default: application/json
Example: application/json

Define the file type and format for the request object.

Responses

Response Schema: application/json
name
required
string

The unique name of the mail domain

csaEnabled
boolean

Determines if a CSA header should be sent when using this maildomain. This value MUST be true for CSA companies and MUST be false for non-CSA companies.

listUnsubscribe
string or null

Determines the value of the list-unsubscribe header. (RFC 2369)

fromAddress
string

The default FROM address to use when sending with this maildomain.

fromEnvelope
string or null

The email address use to receive bounces.

replyAddress
string

The default REPLY address to use when sending with this maildomain.

object
selector
required
string

The selector of the DKIM configuration.

signatureDomain
required
string

The signature domain of the DKIM configuration.

identityDomain
required
string

The identity domain of the DKIM configuration.

publicKey
string

The public key of the DKIM configuration.

Response samples

Content type
application/json
{
  • "name": "service.slgnt.eu",
  • "csaEnabled": false,
  • "listUnsubscribe": "<mailto:list@host.com?subject=unsubscribe>",
  • "fromAddress": "info@test.eu",
  • "replyAddress": "noreply@test.eu",
  • "dkimSettings": {
    • "selector": "133742.tst",
    • "signatureDomain": "service.test.eu",
    • "identityDomain": "service.tst.eu"
    }
}

Webhook Events

EDC webhook events follow CloudEvents specification for describing event data in common formats to provide interoperability across services, platforms and systems.

Delivery sent events for EDC e-mail messages Webhook

Event that are triggered every time an e-mail message is sent.

Request Body schema: application/json
id
string

Identifies the event. The ID is unique for each source.

source
string

The context in which this event has happend.

type
string
Value: "com.sdc.deliveries.email.sent"

Type of processing & sending event. com.sdc.deliveries.email.sent in this case. An event that is triggered when the e-mail message is sent towards the ISP and EDC has gotten an success ISP response back.

subject
string or null

A description / additional info for the event in the context of the specified source.

time
string or null <date-time>

Timestamp of when the event happened. Expressed in UTC.

specversion
string
Default: "1.0"

The version of the CloudEvents specification which the event uses. For more information see cloudEvents.

dataschema
string or null

Represents a URI for the schema to which the data adheres to.

datacontenttype
string
Default: "application/json"

Content type of the 'data' field provided by the event.

object or null

CloudEvent 'data' content. The event payload.

result
string

The code for the message delivery state is:

  • success - The message was delivered, successfully.
outcome
string

The response from the SMTP server. (for analysis of bounces)

recipient
string

The target recipient of the message.

external_reference
string

This is the reference provided by the client in the payload of the message.

timestamp
string

The time the event happened, expressed in UTC.

account_id
string

The account ID this event is triggered for.

object

Use the context to pass relevant information along with each message.

outcome_category
string
Enum: "none" "error" "ok" "greyListed" "blackListed" "badUser" "unavailable" "senderProblem" "mailboxFull" "spam" "receiverProblem" "exclusion"

The SMTP outcome response outcome_category:

  • none - Unable to categorize the outcome.
  • error - Something went wrong in the Smtp protocol, for example a network or protocol error.
  • ok - The message was delivered successfully.
  • greyListed - The message is greylisted and MUST be deferred and then be sent over the same route.
  • blackListed - The message is not delivered and marked as undeliverable.
  • badUser - The message is not delivered because of varies reasons such as an invalid or unknown user, an unrouteable address, bad authentication etc... .
  • unavailable - The message is not delivered because the user or account is inactive or the mailbox has been blocked.
  • senderProblem - The message is not delivered and will be retried.
  • mailboxFull - The message is not delivered because the recipient mailbox was full.
  • spam - The message is not delivered because it is marked as spam.
  • receiverProblem - The message is not delivered and will be retried. Causes can be a temporary receiver issue, too busy mailbox, local server issues, etc... .
  • exclusion - The message hit an exclusion and further messages should not be sent to the same domain over the same IP until the duration has expired.

Responses

Request samples

Content type
application/json
{
  • "id": "1516952e520547049b8897b24e44553e",
  • "source": "/sdc",
  • "type": "com.sdc.deliveries.email.sent",
  • "time": "2022-03-16T12:56:04.8111884Z",
  • "specversion": "1.0",
  • "dataschema": "https://getstarted.slgnt.io/engage/events/sdc#message-sdc.deliveries.email.sent",
  • "datacontenttype": "application/json",
  • "subject": "674d25d7319b4549a88cefdda049989e_92233793802426",
  • "data": {
    • "result": "success",
    • "context": {
      • "profile": "crm-id-123456789",
      • "tags": [
        ],
      • "metadata": "{\"name\":\"jane.doe\",\"ref\":123456789}"
      },
    • "outcome": "250 Ok",
    • "recipient": "jane.doe@example.com",
    • "external_reference": "674d25d7319b4549a88cefdda049989e_92233793802426",
    • "timestamp": "2022-03-16T12:56:00.1260605",
    • "outcome_category": "ok"
    }
}

Delivery failed events for EDC e-mail messages Webhook

Event that are triggered every time an e-mail message is failed.

Request Body schema: application/json
id
string

Identifies the event. The ID is unique for each source.

source
string

The context in which this event has happend.

type
string
Value: "com.sdc.deliveries.email.failed"

Type of processing & sending event. com.sdc.deliveries.email.failed in this case. An event that is triggered when the e-mail message is sent towards the ISP and EDC has gotten an undeliverable ISP response back.

subject
string or null

A description / additional info for the event in the context of the specified source.

time
string or null <date-time>

Timestamp of when the event happened. Expressed in UTC.

specversion
string
Default: "1.0"

The version of the CloudEvents specification which the event uses. For more information see cloudEvents.

dataschema
string or null

Represents a URI for the schema to which the data adheres to.

datacontenttype
string
Default: "application/json"

Content type of the 'data' field provided by the event.

object or null

CloudEvent 'data' content. The event payload.

outcome
string

The response from the SMTP server. (for analysis of bounces)

recipient
string

The target recipient of the message.

external_reference
string

This is the reference provided by the client in the payload of the message.

timestamp
string

The time the event happened, expressed in UTC.

account_id
string

The account ID this event is triggered for.

object

Use the context to pass relevant information along with each message.

outcome_category
string
Enum: "none" "error" "ok" "greyListed" "blackListed" "badUser" "unavailable" "senderProblem" "mailboxFull" "spam" "receiverProblem" "exclusion"

The SMTP outcome response outcome_category:

  • none - Unable to categorize the outcome.
  • error - Something went wrong in the Smtp protocol, for example a network or protocol error.
  • ok - The message was delivered successfully.
  • greyListed - The message is greylisted and MUST be deferred and then be sent over the same route.
  • blackListed - The message is not delivered and marked as undeliverable.
  • badUser - The message is not delivered because of varies reasons such as an invalid or unknown user, an unrouteable address, bad authentication etc... .
  • unavailable - The message is not delivered because the user or account is inactive or the mailbox has been blocked.
  • senderProblem - The message is not delivered and will be retried.
  • mailboxFull - The message is not delivered because the recipient mailbox was full.
  • spam - The message is not delivered because it is marked as spam.
  • receiverProblem - The message is not delivered and will be retried. Causes can be a temporary receiver issue, too busy mailbox, local server issues, etc... .
  • exclusion - The message hit an exclusion and further messages should not be sent to the same domain over the same IP until the duration has expired.
finalize_reason
string
Enum: "tooManyRetries" "tooManyDeferrals" "importBlacklist" "importFailed" "expired" "restriction" "mxServersDenied" "noMxServersAssigned" "nonExistingDomainName" "hardBounce" "badTemplate" "cancelled" "clientCancelled" "greyListed"

The reason why the mail could not be delivered:

  • tooManyRetries - The message is not delivered and will not be retried. Applicable for outcome categories None, Error, SenderProblem and ReceiverProblem.
  • tooManyDeferrals - The message is not delivered and will not be retried. Applicable for outcome categories Excluded and GreyListed and for Restrictions.
  • importBlacklist - The message is not delivered and marked as blacklisted on our side.
  • importFailed - The message could not be properly processed during the importing phase because of various reasons such as DKIM issues, account and tenant validation errors, etc.. .
  • expired - The message is not delivered and marked as expired because it has been in our system for too long (> 48 hours).
  • restriction - The message is not delivered and cancelled due to internal restriction.
  • mxServersDenied - The message is not delivered because the resolved MX servers are marked as denied on our side.
  • noMxServersAssigned - The message is not delivered because there where no MX servers assigned to the domain.
  • nonExistingDomainName - The message is not delivered because the recipient domain does not exist.
  • hardBounce - The message is not delivered because of a permanent reason, see the outcome category for more information.
  • badTemplate - The message is not delivered because the provided template could not be rendered properly.
  • cancelled - The message is not delivered because it has been restricted or because and administrator decided to cancel its import.
  • clientCancelled - The message is not delivered because the client decided to cancel it.
  • greyListed - The message is greylisted and MUST be deferred and then be sent over the same route.

Responses

Request samples

Content type
application/json
{
  • "id": "1516952e520547049b8897b24e44553e",
  • "source": "/sdc",
  • "type": "com.sdc.deliveries.email.failed",
  • "time": "2022-03-16T12:56:04.8111884Z",
  • "specversion": "1.0",
  • "dataschema": "https://getstarted.slgnt.io/engage/events/sdc#message-sdc.deliveries.email.failed",
  • "datacontenttype": "application/json",
  • "subject": "674d25d7319b4549a88cefdda049989e_92233793802426",
  • "data": {
    • "result": "undeliverable",
    • "context": {
      • "profile": "crm-id-123456789",
      • "tags": [
        ],
      • "metadata": "{\"name\":\"jane.doe\",\"ref\":123456789}"
      },
    • "outcome": "5.1.1 https://support.google.com/mail/?p=NoSuchUser o10-20020aa7c50a000000b0050480da034asi8374813edq.27 - gsmtp",
    • "recipient": "jane.doe@example.com",
    • "external_reference": "674d25d7319b4549a88cefdda049989e_92233793802426",
    • "timestamp": "2022-03-16T12:56:00.1260605",
    • "outcome_category": "senderProblem",
    • "finalize_reason": "tooManyRetries"
    }
}

Bounce events for EDC e-mail messages Webhook

These Events are triggered every time a bounce message is received in the reply to inbox configured on the EDC side.

Request Body schema: application/json
id
string

Identifies the event. The ID is unique for each source.

source
string

The context in which this event has happend.

type
string
Enum: "com.sdc.bounces.email.bounced" "com.sdc.bounces.email.complaintfiled" "com.sdc.bounces.email.listunsubscribed"

Type of bounce that has occurred for this event.

subject
string or null

A description / additional info for the event in the context of the specified source.

time
string or null <date-time>

Timestamp of when the event happened. Expressed in UTC.

specversion
string
Default: "1.0"

The version of the CloudEvents specification which the event uses. For more information see cloudEvents.

dataschema
string or null

Represents a URI for the schema to which the data adheres to.

datacontenttype
string
Default: "application/json"

Content type of the 'data' field provided by the event.

object

CloudEvent 'data' content. The EDC bounce e-mail bounce payload.

account_id
string

The account ID this event is triggered for.

external_reference
string

This is the reference provided by the client in the payload of the message.

mailbox
string

The mailbox the async bounce was received on.

timestamp
string

The time the event happened, expressed in UTC.

Responses

Request samples

Content type
application/json
Example
{
  • "id": "4c5cdac78da04350b0b32700a66bbb51",
  • "source": "/sdc",
  • "type": "com.sdc.bounces.email.bounced",
  • "subject": "cd078723-7b40-4a00-90a8-83b0170be1d5",
  • "time": "2022-03-10T09:37:05.8198818Z",
  • "specversion": "1.0",
  • "dataschema": "https://getstarted.slgnt.io/engage/events/sdc#message-sdc.bounces.email.bounced",
  • "datacontenttype": "application/json",
  • "data": {
    • "account_id": "3822afb319684af18b9664ee327b7c44",
    • "external_reference": "4c5cdac78da04350b0b32700a66bbb51",
    • "subject": "This is a mail sent from EDC",
    • "mailbox": "bounce@service.slgnt.eu",
    • "timestamp": "2022-03-10T09:37:05.7299959+00:00"
    }
}

OAuth 2.0

All endpoints to authenticate yourself, to access the EDC API.

Get Oauth access Token

Request an access tokens to access EDC resources on behalf of an authenticated user.

Note:

  • Access Tokens expire after 2 hours.
  • Refresh Tokens don't expire until they are used.
header Parameters
Content-Type
required
string
Default: application/json
Example: application/json

Define the file type and format for the request object.

Request Body schema: application/json
client_id
required
string

The Oauth client ID provided by Marigold Engage

client_secret
required
string

The Oauth client secret provided by Marigold Engage

account_id
required
string

The Marigold Engage account ID, which refers to the account/tenant.

grant_type
required
string
Default: "client_credentials"

The method used to retrieve an access token

audience
required
string
Default: "https://sdc.slgnt.eu"

Refers to the application/server for which the token is requested.

Responses

Response Schema: application/json
access_token
required
string

The access token provided in the response

token_type
required
string
Value: "Bearer"

The token type (currently this is always "Bearer")

refresh_token
string

The refresh token provided in the response

scope
required
string

The scope of the access request

expires_in
required
number

The number of seconds until the access token expires

Request samples

Content type
application/json
{
  • "client_id": 12345,
  • "client_secret": "123abc",
  • "account_id": "12345ABCDE6789FGHIJ",
  • "grant_type": "client_credentials",
  • "audience": "https://sdc.slgnt.eu"
}

Response samples

Content type
application/json
{
  • "access_token": "abcdefghijklmnopqrstuvwxyz1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ",
  • "token_type": "Bearer",
  • "refresh_token": "1234567890abcdefghijklmnopqrstuvwxyz1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ",
  • "scope": "send:email",
  • "expires_in": 86400
}