Skip to content

Notifications

API information

The notification resource is managed by the Notifications API.

XPKit Portal

  • It is recommended campaigns and templates are configured in XPKit Portal, and notifications are triggered by your applications making direct API requests.
  • Rules can be created in XPKit Portal to send notifications to a visitor (profile) based on the creation of a particular type of activity.

Service URLs

Region URL
AMER https://notifications.amer.xpkit.net
APAC https://notifications.apac.xpkit.net
China https://notifications.china.xpkit.cn
EMEA https://notifications.emea.xpkit.net

OpenAPI Specification

Resource name Documentation Download
Campaign, Notification, Template View Link

Supported providers

Email

  • sendgrid (Sendgrid)
  • mandrill (Mandrill)
  • smtp (SMTP server)

SMS

  • sns (Amazon SNS)

Example email campaign (using Sendgrid)

{
    "campaign_name": "Welcome to the conference",
    "campaign_id": "welcome-to-the-conference",
    "experience_id": "developer-conference-2022",
    "object_id": "website",
    "gateway": "sendgrid",
    "notification_type": "email",
    "gateway_config": {
        "api_key": "f50f237e1ec54524877e",
        "opening_personalisation_tag": "-",
        "closing_personalisation_tag": "-",
        "uses_transactional_templates": false
    },
    "content": {
        "_default": "en",
        "en": {
            "from_email": "registration@conference.abc.com",
            "from_name": "ABC conference registration",
            "subject_line": "Thanks for registering -first_name-",
            "template_html": "https://devconference.s3.amazonaws.com/registration.html",
            "template_text": "https://devconference.s3.amazonaws.com/registration.txt"
        }
    },
    "webhook_url": "https://xpkit.abc.com/callback",
    "send_default_on_invalid": false
}
Languages

The value you select for content._default will determine which language will be used if one is not provided in a trigger request (see below).

The send_default_on_invalid boolean flag (optional, default false) can be used to request that the default is also sent if an invalid language is provided in a trigger request.

Notes on email templates

  • Email template URLs can be left blank in configurations and provided when a notification is triggered.
  • Any URLs you provide should be publicly available so if a template contains embargoed or confidential content it is recommended you either:
    • provide the URLs at send time or
    • use the template upload endpoint which generates private URLs (requires a valid access token to view)
  • When triggering a notification, as well as the option of defining template URLs, raw HTML can be provided. There is an example below in the trigger request section.
  • When personalising emails use the templating language your chosen provider supports. XPKit will pass on the templates as-is. If you are using an SMTP server configuration you should use the Jinja templating engine.

  • If you are using transactional templates (those are templates stored with the email provider), a template ID rather than URLs should be provided in the campaign. Example of the required changes:

    {
    "gateway_config": {
        "uses_transactional_templates": true
    },
    "content": {
        "_default": "en",
        "en": {
            "template_id": "d-73ba99853d22490f9c3fad726173e310"
        }
    }
}

Example SMS campaign (using SNS)

{
    "campaign_name": "Welcome to the conference",
    "campaign_id": "welcome-to-the-conference",
    "experience_id": "developer-conference-2022",
    "object_id": "website",
    "gateway": "sns",
    "notification_type": "sms",
    "gateway_config": {
        "aws_access_key_id": "1f69b7bc3a7342df8b88",
        "aws_secret_access_key": "eba61ee767bf4896ac8b",
        "aws_region_name": "us-east-1"
    },
    "content": {
        "_default": "en",
        "en": {
            "message": "Thanks for registering {{first_name}}"
        }
    },
    "webhook_url": "https://xpkit.abc.com/callback"
}

Note: it is possible to add personalisation to SMS messages. For substitutions use double curly brackets in tags: {{field_name}}.

Example email notification trigger request

{
    "campaign_id": "welcome-to-the-conference",
    "recipient_email": "sarah.jones@abc.com",
    "language": "en",
    "content": {
        "template": {
            "first_name": "Sarah",
            "last_name": "Jones"
        },
        "attachments": [
            {
                "file1.png": "http://www.bucket.com/file1.png"
            }
        ],
        "template_html": "https://overrides.s3.amazonaws.com/override.html",
        "template_text": "https://overrides.s3.amazonaws.com/override.txt",
        "template_html_raw": "<html><body><h1>Hello -first_name- -last_name-</p></body></html>",
        "template_text_raw": "Hello -first_name- -last_name-",
        "subject_line": "-first_name-, you have now registered!"
    },
    "webhook_url": "https://xpkit.abc.com/callback",
    "disable_activity_creation": true
}

Notes on email template content

  • Raw HTML and text content can be provided using the template_html_raw and template_text_raw fields.
  • These fields can contain personalisation tags.
  • If provided these fields take precedence over template_html and template_text fields in both the campaign and notification resources (if provided).
  • All these options are ignored if transactional templates have been enabled in the campaign.

Example SMS notification trigger request

{
    "campaign_id": "welcome-to-the-conference",
    "recipient_phone": "+44123456789",
    "recipient_id": "b0fc813f-c6b5-4334-97d5-153c4fe6053b",
    "language": "en",
    "content": {
        "template": {
            "first_name": "Sarah",
            "last_name": "Jones"
        },
        "message": "{{first_name}}, thanks for registering!"
    },
    "webhook_url": "https://xpkit.abc.com/callback",
    "send_at": "2021-03-01T14:00:00+11"
}

Notifications and activities

After a notification has been sent an activity will automatically be created for the recipient (if they have a profile). This functionality can be disabled by passing in the boolean field disable_activity_creation and setting it as true in the notification request.

If activity creation is enabled (default behaviour), the profile lookup will be based on either recipient_email (email notification) or recipient_phone (SMS notification) using the profile fields profile.email and profile.mobile_number respectively.

Note: as XPKit does not enforce a uniqueness constraint on profile.mobile_number, multiple profiles could be returned. To ensure the activity is created for the correct profile a profile ID can be provided in the form of a recipient_id field (example above).

In the created activity:

  • The activity.activity_type field will be set to either SMS_SENT or EMAIL_SENT.
  • The activity.payload.object_id and activity.experience_id fields will be set to the values provided in the campaign.
  • The field activity.payload.campaign_id will also be set.

Callbacks

The Notifications API supports callbacks. After a notification has been triggered the result will be posted to the provided webhook_url. Example requests:

Notification successful (email):

{
    "status": "Succeeded",
    "job_id": "74889870-9a76-490e-9a0f-8eb7eec071da",
    "error": null,
    "gateway_response": {
        "message_id": "WPisQq2tQmCM4oEmWOp5uQ",
        "status": "sent",
        "email": "sarah.jones@abc.com"
    }
}

Notification successful (SMS - Amazon SNS):

{
    "status": "Succeeded",
    "job_id": "74889870-9a76-490e-9a0f-8eb7eec071da",
    "error": null,
    "gateway_response": {
        "MessageId": "2bfe9e61-e89d-58ee-9392-c6ec85c497b7",
        "ResponseMetadata": {
            "RequestId": "c46dde4d-6e67-5496-a4cc-86c0033e7bd1",
            "HTTPStatusCode": 200,
            "RetryAttempts": 0,
            "HTTPHeaders": {
                "x-amzn-requestid": "e56dde4d-6e67-5496-a4cc-86c0033e7bf1",
                "content-type": "text/xml",
                "content-length": "294",
                "date": "Fri, 29 Jan 2021 11:32:56 GMT"
            }
        }
    }
}

Notification failure:

{
    "status": "Failed",
    "job_id": "74889870-9a76-490e-9a0f-8eb7eec071da",
    "error": "Cannot send email to sarah.jones@abc.com. The mandrill gateway responded with an error message: Invalid API key",
    "gateway_response": {}
}

Notes on campaigns and notifications

  • Notifications can be scheduled up to 5 days in the future using the send_at field
  • Maximum allowed file sizes:
    • email attachments - 25MB
    • email templates - 1MB
  • Do not provide a campaign_id field in campaign CRUD requests. The field will be ignored and auto generated from the provided campaign_name field.
  • It is possible to override campaign options when triggering a notification (see examples above). The following can be overridden:
    • Email: template_html, template_text, subject_line, webhook_url
    • SMS: message, webhook_url
  • To support template content, the maximum request size permitted is increased to 16kb for requests to the Notifications API.