Skip to main content

Digital Communications: API Summary

Marquis provides the following location where you can view information about and use our Digital Communication APIs:

 

https://api.documatix.com/DMXService

 

Any posts to these APIs will be live (the link does not use a Sandbox or UAT environment). When you use the SendEmails API, a live email will be sent. This allows you to interact with the APIs and experience the full loop process.

 

 

Available APIs (as of September 2024):

The following are the APIs currently available.

  • Campaigns > GetRecipientHistory
  • Campaigns > GetEmails
  • Campaigns > SendEmails
  • Campaigns > GetEmailPerformance
  • Campaigns > GetEmailInteractions
  • Campaigns > GetUnsubscribesList
  • Campaigns > GetPermanentBlocks
  • Campaigns > GetBouncebacks
  • Surveys > GetSurveyResponseHistory

 

General Information

To use the APIs, work with your Relationship Manager and support to get an API key. This will give you access to interact with your data using the link above. Unless otherwise noted, if you have multiple Digital Communication accounts for your organization, each API will return results across all your Digital Communication accounts.

 

Any date and time listed is in Mountain Time (MST/MDT).

 

 

Campaigns > GetRecipientHistory

Summary:

Provides a list of emails sent to requested email addresses (or up to 10 email addresses in one request).

  • This will default to provide the emails sent over the last 90 days, but that parameter can be changed in the request.

Highlight of parameters you can include in your request:

  • EmailAddress—The email address(es) that you want to get the list of emails sent to. You can request up to 10 email addresses in one request.
  • LicenseNumber—Leave this blank. This is used when returning the list of emails to Marquis’ CRM.
  • StartDate—If you do not provide a date, this will default to 90 days in the past.
  • EndDate—If you do not provide a date, this will default to the current date and time.

Highlight of fields in the response:

  • EmailAddress—The email address where the email was sent
  • CampaignName—The name given to the email when you created the email. If you have a user interface where the user confirms which email they want to send, the email name is a more user-friendly name to display.
  • CampaignID—An internal unique identifier for the email
  • DeliveredDate—The date and time the email was sent by the Digital Communication platform
  • LinkClickCount—The number of times that the recipient clicked on a link within the email (through the day of the request)
  • RenderedEmailURL—The link to see a browser-based version of the email (which will include the merge fields sent)

Use case examples:

Show a list of recent emails sent from Digital Communications within:

  • CRM (Marquis CRM uses this API for the Communication list.)
  • Teller system
  • Core
  • Etc.

Additional Information:

This will show all emails sent within the timeframe (StartDate and EndDate) that you requested.

 

Campaigns > GetEmails

Summary:

Provides a list of emails that can be used as part of the SendEmails API. This API has an option that allows you to choose if you want to get the merge fields. For example, if you need only the email names and IDs, you can choose not to get the merge fields and return results faster.

Highlight of parameters you can include in your request:

  • IncludeMergeField—Allows you determine if you only want to receive the list of reusable emails or if you want to include Merge fields that have been defined for those emails

Highlight of fields in the response:

  • EmailID—An indicator pointing to the email you want to send.
  • EmailName—The name given to the email. When you create the email, if you have a user interface where the user confirms which email they want to send, the email name is a more user-friendly name to display.
  • HasAntiPhishing—The anti-phishing code you use for this customer/member if you use this feature
  • UsedMergeFields—Will provide all the merge fields defined within the email.
  • VersionCode—This is used for the Marketing Data Platform/ExecuTrax integration process.
  • FullVersionCode—This is used for the Marketing Data Platform/ExecuTrax integration process.
  • ProcessType—This will be used by the Marketing Data Platform/ExecuTrax integration process. It shows how your Digital Communication accounts are set up, and the following ProcessType options are possible in the results:

 

Process type Description
1 Marquis managed—This means that Marquis is creating your emails and coordinating the integration between Marketing Data Platform/ExecuTrax and Digital Communication.
2 Client managed—This means that you are creating your emails and using the Marketing Data Platform/ExecuTrax integration process and/or files through Digital Communication On Demand (DOD).
Null Your account hasn’t been defined to use the Marketing Data Platform/ExecuTrax integration process.

 

  • InstitutionID—This relates to the Marketing Data Platform/ExecuTrax integration process and is the unique identifier Marquis uses for that integration.

Use case examples:

  • We use this within Marketing Data Platform to display the emails someone can use within a one-off campaign or Journeys.
  • Use with the SendEmails API to know the information (email ID and merge fields) needed to send an email.

Additional Information:

  • Will only show reusable “Triggered” email types that are in published status.
  • Because we are showing the EmailName, consider how you are naming the emails within Digital Communication. The name of an email can be changed even after it is published (without having to create a revision).
  • Digital Communication has a feature that allows you to provide a code that you have established with your customers/members. This is a safety feature that allows them extra comfort to distinguish your legitimate email from an email from a scammer. For example, if you use this feature, you may say in your onboarding emails that the person can know this email is from you if they see the last three digits of their primary account number in the footer of their email. The code you use and the placement of the code are completely up to your organization. The HasAntiPhishing indicator will tell you if the email has been created to use an Anti-Phishing merge field.

Campaigns > SendEmails

Summary:

This API allows you to send emails from Digital Communication.

  • To be used with the GetEmails API to know the EmailID, merge fields, etc. required to send the email

Highlight of parameters you can include in your request:

  • EmailID—An indicator pointing to the email you want to send
  • EmailLaunches—A section separator after which you can include groups of email parameters to send the email to up to 10 email addresses. (This will send up to 10 separate emails.)
    • EmailAddress—The email address where you want to send the email
    • MobileNumber—A placeholder for a future use
    • UsedMergeFields—A section separator where you will provide the information for each merge field defined within the email
      • Name—This is the name the person creating the email gave to the merge field name within the email (or it is a standard merge field name if you are using the Marketing Data Platform/ExecuTrax integration process).
      • Value—This is the value you want to use in the merge field for the email.
      • ReplaceName—This is the system-defined name for the merge field.
    • CustomField1—This is one of two fields that you can use to add additional data that will not be included in the email sent, for example, a unique customer/member number or an additional field that you want to use to integrate with other systems.
    • CustomField2—This is the second of two fields that you can use to add additional data that will not be included in the email sent.
    • AntiPhishingField—This is the Anti-Phishing code you use for this customer/member if you use this feature.

Highlight of fields in the response:

  • Will give you messaging to let you know if the email delivery request was saved for processing

Use case examples:

Create a standard and branded email to be sent from a variety of systems, which will allow the email results to be tracked and included in your existing Digital Communication reporting. Send an email from:

  • A new account/loan application
  • Your CRM system
  • Your Core or Teller system
  • Etc.

Additional Information:

  • Must have DOD (Digital Communication On Demand) to use Triggered email types.
  • Create a “Triggered” email within Digital Communication—this is a reusable email type and allows for changes to be made without reconfiguring the Email ID if you create a revision and not a copy or a new email.
  • Triggered emails must be in a published status to be used (cannot be in draft).
    • You can revise a Triggered email; this API will use the latest published version.
  • Digital Communication has a feature that allows you to provide a code that you have established with your customers/members. This is a safety feature that allows them extra comfort to distinguish your legitimate email from an email from a scammer. For example, if you use this feature, you may say in your onboarding emails that the person can know this email is from you if they see the last three digits of their primary account number in the footer of the email. The code you use and the placement of the code are completely up to your organization. The AntiPhishingField is where you will place this customer/member-specific code you want to include in the email.

 

Campaigns > GetEmailPerformance

Summary:

Within Digital Communication Product Suite application, each email that has been sent has an Email Performance report that gives information about the email and interactions from the recipients. You can use this to get information on reusable “Triggered” emails only. Some of the information you can get includes:

  • Number of emails sent
  • Number of emails where we received a bounceback message saying the email couldn’t be delivered
  • Number of people who clicked on any link
  • Total number of clicks
  • Clickthrough rate
  • and other statistics

This API allows you to get the statistics from the Email Performance report through an API instead of using the report.

Highlight of parameters you can include in your request:

  • EmailID—Use the GetEmails API to obtain the EmailID if you want to pull performance statistics for a specific email (this will show reusable “Triggered” emails only). If you don’t provide an EmailID, then all performance statistics for emails sent between the StartDate and EndDate will be returned.
  • StartDate—If you do not provide a date, this will default to 90 days in the past.
  • EndDate—If you do not provide a date, this will default to the current date and time.

Highlight of fields in the response:

  • CompanyID—A unique identifier for your Digital Communication account.
  • CampaignID—An internal unique identifier for the email.
  • EmailID—A unique indicator pointing to the email.
  • CampaignName—The name given to the email. When you create the email, if you have a user interface where the user confirms which email they want to send, the email name is a more user-friendly name to display.
  • CreatedDate—The date the email was created.
  • PublishDate—The date the email was published.
  • VersionCode—This is used for the Marketing Data Platform/ExecuTrax integration process.
  • Subject—This is the subject defined for the email.
  • From—The name used on the delivered email.
  • FromEmail—The email address that the email is from.
  • ReplyToEmail—The reply-to email address on the email. This can be changed per email and/or per email delivery.
  • MailSize—Within the timeframe, the number of email addresses uploaded to be sent.
  • Delivered—Within the timeframe, the number of emails sent.
  • TotalOpens—The total number of emails opened since the email was delivered. This will include a count of each time a recipient opened the email. This is not limited to the timeframe.
  • UniqueOpens—The count of individuals who opened the email at least once since the email was delivered. This is not limited to the timeframe.
  • UniqueOpensPercent—The ratio of unique opens to actual delivered (delivered minus undelivered) emails.
  • Unopened—The number of emails that were not opened (not including the emails that were undelivered). This is not limited to the timeframe.
  • UnopenedPercent—The percent of unopened emails compared to actual delivered (delivered/undelivered) emails.
  • TotalClickThroughs—The total number of links clicked since the email was delivered. This will include a count of each time a recipient clicked any link. This is not limited to the timeframe.
  • UniqueClickThroughs—The count of individuals who clicked on one or more links since the email was delivered. This is not limited to the timeframe.
  • ClickThroughPercent—The percent of individuals who clicked on a link, out of the total number of delivered emails.
  • Undeliverable—The number of emails where Marquis received a bounceback stating that the email could not be delivered. This is not limited to the timeframe.
  • UndeliverablePercent—The percent of undelivered emails, out of the total emails sent.
  • Unsubscribed—The count of individuals who unsubscribed using the link at the bottom of the email. This is not limited to the timeframe.
  • UnsubscribedPercent—The percent of individuals who unsubscribed, out of the total number of emails sent.
  • CTOR—The Click-to-Open-Ratio. The percent of the individual recipients who opened an email and also clicked on a link. This is not limited to the timeframe.
  • Rejected—Within the timeframe, the number of email addresses uploaded to be sent that couldn’t be sent for a variety of reasons (e.g., the email address is invalid, has a known invalid domain, is on the permanently blocked list, has previously unsubscribed, etc.)

Use case examples:

  • Update an executive dashboard (e.g., within a data warehouse/data lake) with information about emails delivered within a timeframe.
  • If you are sending emails using the SendEmail API, create a report to follow up on the emails sent.

Additional information:

If you choose not to include an EmailID, this will show all performance statistics for emails sent (one-time emails and reusable emails within the timeframe).

 

This will show reusable “Triggered” emails only.

 

Campaigns > GetEmailInteractions

Summary:

When an email is sent, there are a variety of actions that can happen with the email (we also call these interactions). The following three interactions are available from this API:

 

ActionType Description
SNT The email was sent.
BBK The email provider returned a message that the email couldn’t be delivered (similar to the Post Office sending back a letter or mailed item with a “Return to Sender”).
LNK The recipient clicked on a link within the email.

 

Highlight of parameters you can include in your request:

  • EmailAddress—(required) The email address(es) whose interactions you want to get. You can include up to 10 email addresses in each request.
  • EmailID—(required) The email identifier for the email whose interaction statistics you want to get. Use the GetEmails API to obtain the email ID. This will show reusable “Triggered” emails only.
  • ActionType—Include one of the three ActionTypes above if you want to see the instances of that specific interaction with the email. If you leave this blank, then all possible interactions will be provided for that timeframe.
  • StartDate—If you do not provide a date, this will default to 90 days in the past.
  • EndDate—If you do not provide a date, this will default to the current date and time.

Highlight of fields in the response:

  • Interactions—A section separator where you will get information about each email address that has unsubscribed.
    • CompanyID—A unique identifier for your Digital Communication account.
    • CampaignID—The internal unique identifier for the email with the person’s interactions.
    • CampaignName—The name given to the email when it was created.
    • EmailID—A unique indicator for the email.
    • VersionCode—This is used for the Marketing Data Platform/ExecuTrax integration process.
    • ActionType—The type of interaction the person had with the email. See previous table for the ActionTypes included in this API.
    • ActionDateTime—The date and time of the interaction.
    • EmailAddress—The email address of the person who interacted with the email.
    • ClickedLinkURL—If the interaction type was LNK, this is the URL that the person clicked on within the email. If the person clicked on more than one URL during the timeframe you requested, you will receive multiple interactions in the response to represent each interaction.
    • CustomFields1–10—When uploading a file to send an email, you will have between 2 and 10 custom fields to which you can add additional reference information for the email. The custom fields will not be displayed to the recipient.
    • Reason—If the interaction type is BBK, this is the reason the Email Provider returned saying the message could not be delivered.

Use case examples:

If you have an email introducing a particular offer and the recipient clicks on the email, you can use this API to see if the recipient was interested and create a process to have someone follow up with the recipient.

 

This can be used in the future for Marketing Data Platform journeys to allow different paths:

  • If an email is returned, an alternate path of sending a direct mail to the customer/member can be created.
  • If a recipient clicked on a specific link within the email, a particular follow-up action can be taken.

Additional Information:

This is available for Triggered email types.

 

Campaigns > GetUnsubscribesList

Summary:

This API allows you to retrieve the email addresses that have unsubscribed from receiving emails from you.

Highlight of parameters you can include in your request:

  • StartDate—If you do not provide a date, this will default to 90 days in the past.
  • EndDate—If you do not provide a date, this will default to the current date and time.

Highlight of fields in the response:

  • Unsubscribes—A section separator where you will get information about each email address that has unsubscribed (opted out).
    • CompanyID—A unique identifier for your Digital Communication account.
    • CampaignID—If the person opted out using the unsubscribe link within the email, this is an internal unique identifier for the email.
    • CampaignName—The name given to the email when it was created.
    • CreatedDate—The date and time of the unsubscribe.
    • EmailAddress—The email address that is permanently blocked.
    • CustomFields1–10—When uploading a file to send an email, you will have between 2 and 10 custom fields to which you can add additional reference information for the email. The custom fields will not be displayed to the recipient.
    • Reason—If provided, the reason the person gave for unsubscribing.

Use case examples:

Flag any unsubscribed email addresses as opted out in your source systems so you do not continue to send emails to those addresses. Systems to update include:

  • Your Core or Teller system
  • Your CRM system
  • Etc.

Additional information:

  • If you have multiple email providers (e.g., a campaign-specific email that goes out through a different provider), this allows you to sync from your main unsubscribe list within Digital Communications to the third-party provider.
  • Unsubscribes are part of CAN-SPAM compliance through Marquis’ Digital Communication platform.

 

Campaigns > GetPermanentBlocks

Summary:

This API allows you to retrieve the email addresses that have been permanently blocked because we have received “hard” bouncebacks for them.

Highlight of parameters you can include in your request:

  • StartDate—If you do not provide a date, this will default to 90 days in the past.
  • EndDate—If you do not provide a date, this will default to the current date and time.

Highlight of fields in the response:

  • Blocks—A section separator where you will get information about each email address that has been permanently blocked due to bouncebacks.
    • EmailAddress—The email address that is permanently blocked.
    • CompanyID—A unique identifier for your Digital Communication account.
    • CampaignID—An internal unique identifier for the email .
    • CampaignName—The name given to the email when it was created.
    • CreatedDate—The date and time of the block.
    • EmailID—A unique indicator pointing to the email.
    • Reason—The reason the email provider gave for the bounceback.
    • CustomFields1–10—When uploading a file to send an email, you will have between 2 and 10 custom fields to which you can add additional reference information for the email. The custom fields will not be displayed to the recipient.

Use case examples:

Flag any permanently blocked email addresses as invalid in your source systems so you do not continue to send emails to the email addresses. Systems to update:

  • Your Core or Teller system
  • Your CRM system
  • Etc.

Set a prompt within your Core, Teller, and/or Online/Mobile Banking system to prompt the user to provide a new email address.

Additional information:

  • Hard bouncebacks are due to permanent condition(s) with the email inbox or email provider. If Marquis receives multiple “Hard” bounces, the email will be permanently blocked. “Soft” bounces are not used to determine if the email address will be permanently blocked.

 

Campaigns > GetBouncebacks

Summary:

This API allows you to retrieve all the bounceback or undeliverable messages we have received for your emails sent from Digital Communication. This will allow you to see these and act before the email is added to the permanent blocked list of emails.

Highlight of parameters you can include in your request:

  • StartDate—If you do not provide a date, this will default to 90 days in the past.
  • EndDate—If you do not provide a date, this will default to the current date and time.

Highlight of fields in the response:

  • Bouncebacks—A section separator where you will get information about each email address for which we received a bounceback message from the email provider
    • EmailAddress—The email address for which we received a bounceback.
    • PermanentlyBlocked—An indicator of whether this email address is on the permanent blocked list.
    • CompanyID—A unique identifier for your Digital Communication account.
    • CampaignID—An internal unique identifier for the email.
    • CampaignName—The name given to the email when it was created.
    • CreatedDate—The date and time of the bounceback.
    • EmailID—A unique indicator pointing to the email.
    • BounceTypeCode—A code to indicate if this was a soft or hard bounceback. See following table.
    • BounceTypeDescription—Whether this was a soft or hard bounceback. See following table.

 

Code Description
1 Soft bounce
2 Hard bounce

 

  • Reason—The reason the email provider gave for the bounceback.
  • CustomFields1–10—When uploading a file to send an email, you will have between 2 and 10 custom fields to which you can add additional reference information for the email. The custom fields will not be displayed to the recipient.

Use case examples:

If there is a hard bounce, you can place this email address in a state within your source systems that will not include the email address in future emails.

 

If you are using Digital Communication On Demand (DOD) and have a multiple-step Marketing Automation decision tree, this will allow you to update your source system and flag an email address as invalid. Additional use-case considerations:

  • You can set up an internal process to have the person who opened the account or loan request an updated email address.
  • Update your Core, Teller, and/or Online/Mobile Banking systems to prompt the user to provide a new email address.
  • Switch their communication preference to mail.

Additional information:

  • Both soft and hard bouncebacks will be provided.
    • Soft bouncebacks are due to temporary condition(s) with the email inbox or email provider, and you could attempt a different email. Soft bounces are not used to determine if the email address will be permanently blocked.
    • Hard bouncebacks are due to permanent condition(s) with the email inbox or email provider. If Marquis receives multiple hard bounces, the email will be permanently blocked.

 

Surveys > GetSurveyResponseHistory

Summary:

Provides a list of emails that were sent with tracked surveys and whether the recipient responded to the survey.

  • You can request up to 10 email addresses in one request.
  • This will default to provide the surveys sent over the last 90 days, but that parameter can be changed in the request.
  • List will include a link to see a browser-based version of the survey, including responses the person provided.
  • If there was a Net Promoter Score® question type on the survey, there will be an indicator showing that and the NPS response and categorization (Detractor, Passive, Promoter).

Also provides a list of surveys responded to by requested email addresses (even if the survey wasn’t provided to the recipient via email), if email address was included as a required contact field in the survey.

Highlight of parameters you can include in your request:

  • EmailAddresses—The email address(es) for which you want to get the list of survey responses. You can request up to 10 email addresses in one request.
  • LicenseNumber—Leave this blank. This is used when returning the list of emails to Marquis’ CRM.
  • StartDate—If you do not provide a date, this will default to 90 days in the past.
  • EndDate—If you do not provide a date, this will default to the current date and time.

Highlight of fields in the response:

  • History—A section separator where you will get information about the survey responses for each email address you included in the request.
    • EmailAddress—The email address whose survey responses you asked to receive.
    • EmailDeliveredDate—If the survey was delivered through an email, this is the date and time the email was sent.
    • CampaignID—If the survey was delivered through an email, this is the internal unique identifier for the email.
    • MemberGuid—A unique identifier assigned by Digital Communication for the email recipient.
    • Surveys—A section separator where you will get information about the survey
      • SurveyName—The name given to the survey when it was created.
      • SurveyID—A unique indicator assigned to the survey.
      • Responded—If this is true, the person responded to the survey sent in email.
      • IncludesNPSQuestion—If this is true, the survey included one or more NPS questions.
      • Responses—A section separator where you will get information about the survey responses.
        • ResponseDate—The date and time of the survey response.
        • ResponseUrl—A URL that will give you a view-only version of the survey responses.
        • NPSReponses—A section separator where you will get information about the person’s response to the NPS question(s) on the survey.
          • Category—The type of NPS question (Company, Branch, or Product/Service).
          • NPSAnswer—The answer or score the person gave for the NPS question.
          • NPSAnswerDescription—If there was a follow-up question, this is the answer the person gave.

Use case examples:

Show a list of recent survey responses or surveys still needing a response sent from Digital Communications.

 

Display this within:

  • CRM (Marquis CRM uses this API for the Communication list)
  • Teller system
  • Core
  • Etc.

 

If you are receiving the FTP Report package—and loading in all survey responses to a system where a department manager would follow up on surveys—this can be used to provide a view into the responses given for better customer/member service and follow-up.

 

Additional information:

  • Only surveys will be included that were either sent using the tracked survey feature from within an email or if the survey included email address within the survey.
  • Surveys that were anonymous (did not have email address) will not be included.
  • Responses cannot be edited (this is by design, because we simply want to report what the answer was).

Related articles