General & Technical

  • Email Authentication

    Postmark DKIM Setup

    Unimarket has adopted the use of Postmark as our tool to help manage Unimarket emails. Postmark was selected because they are experts in the area of emails. They provide better guarantees around delivery and bounce handling, as well as provide higher levels of email security. Postmark uses the DKIM (DomainKeys Identified Mail) for the authentication of an email that’s being sent.  DKIM is an open standard for email authentication and a preferred method of authentication. This setup will make sure all emails from Unimarket are coming from your email domain.

    A PO notification to the supplier will come from example@customerdomain.com.

     

    Mail From

    By default (without any configuration), Unimarket sets the MAIL FROM in the email header to bounce@<your unimarket domain>, e.g. bounce@customer.unimarket.com. This stops emails from bouncing. We then set the FROM to your community defined customer email domain so that the recipient's email client displays the FROM address (your email domain) but 'via Unimarket.com'. Please note that this can display in email clients differently. Some show ‘via Unimarket’ ,while others may just show your email domain.

    A PO notification to the supplier will come from example@customerdomain.com via unimarket.com

     

    Return Path Setup

    If you want to ensure that all emails display as coming from your email domain and not 'via Unimarket', then a Return Path can be configured. This tells the recipient's email client that Unimarket is authorised to send emails on your behalf and it doesn't get marked as spam.

    With a custom Return-Path, you can set your own return path email address e.g. bounce@bounce.customerdomain.com in place of ours.

    The Return-Path is used to set the SMTP header MAIL FROM

    When using the Return Path option you must setup a CNAME entry to your DNS that maps the domain you provide to our domain. So if your return path is bounce@bounce.customerdomain.com and the CNAME should be bounce.customerdomain.com---> unimarket.com. Use the Validate Return Path button to test if the CNAME you have setup in your DNS matches the Return Path.

    87292897-7E4D-4EE3-BFE4-58824F06802A.jpeg

    Once setup, your Community administrator can enter the return path (e.g. bounce@bounce.customerdomain.com) under Email Delivery Authentication on the Administration / Settings / Profile screen. Please note that the return path needs to have the same suffix as the From addresses, i.e. if the From address is customerdomain.com, then the return path needs to be <something>.customerdomain.com.

  • Simplifying SPF maintenance

    Overview

    Unimarket has an SPF Include that you can use rather than directly referring to specific ip addresses. The advantage is that you will not need to make any SPF changes when Unimarket makes infrastructure changes or adds additional mail servers.

    Unimarket will continue to support customers using this method however this is no longer available for new customers or for existing customers to switch to.

    Please add the following to your SPF record:

    include:_spf.unimarket.com

    Your resulting SPF should look something like (note: this is just an example, your SPF record may look quite different):

    v=spf1 mx include:_spf.unimarket.com ~all

     

    Unimarket Production Email Server IP addresses: 

    • AU Production: 35.201.28.55
    • NZ Production: 35.244.97.153
    • US Production: 34.72.64.51
  • Webservice Integration Technical Documentation & Examples

    Integration Message Types

    Unimarket XML Integration Points (uXML)

    Below is a link to the technical documentation and examples for the Unimarket XML (uXML) integration points:

    cXML Integration Points

    Where possible Unimarket uses the Commerce XML (cXML) standard for common integration points with suppliers and buying organizations such as Orders and Invoices.

  • Sending POX (Plain Old XML) Messages to Unimarket

    Overview

    POX stands for Plain Old XML and is a simpler alternative protocol for sending messages to Unimarket.


    Basic getting started guide

    • Contact Unimarket to provide you with the authentication details required (tenant identifier, integration username and shared secret).
    • Review the Unimarket xml schema and identify the top-level request element to send to Unimarket.
    • Create a request message that conforms to the xml schema.
    • Send a valid POX message containing the request message and the authentication header element wrapped in a pox-envelope to one of the following two applicable urls.
    1. Supplier:
      1. https://supplier.unimarket.com/ws - US
      2. https://supplier.unimarket.co.nz/ws - NZ
      3. https://supplier.unimarket.com.au/ws - AU
    2. Community:
      1. https://<community code>.unimarket.com/ws - US
      2. https://<community code>.unimarket.com/ws - NZ
      3. https://<community code>.unimarket.com/ws - AU
    Note: Please note that cXML requests (e.g. OrderRequest, InvoiceDetailRequst) do not need to be wrapped in a pox-envelope element as the authentication details are already included in the cXML request.

     

    Example POX message

    <?xml version="1.0" encoding="UTF-8"?>
    <u:pox-envelope xmlns:u="http://www.unimarket.com/schema/unimarket-ws">
        <u:header>
            <u:authentication>
                <!-- Unique identifier of the Unimarket tenant (community or supplier) -->
                <u:tenant-ref identity="7f251a49-bd4d-4527-b234-d3d4a3e14e1b" domain="UNIMARKET_ID_DOMAIN"/>
                <u:sender>
                    <!-- Unique identifier of the Unimarket integration user -->
                    <u:user-ref identity="6cd91828-a4f4-4b70-b9ac-5f6f4d9e4082" domain="UNIMARKET_USERNAME_DOMAIN"/>
                    <!-- Password used to authenticate the request -->
                    <u:shared-secret>password1</u:shared-secret>
                </u:sender>
            </u:authentication>
        </u:header>
        <u:body>
            <create-quote-request xmlns='http://www.unimarket.com/schema/unimarket-ws'>
                <header>
                    <to>
                        <!-- Unique Unimarket username of the user the quote is for -->
                        <user-ref identity='user1'/>
                        <!-- Unique Unimarket code of the user's community -->
                        <tenant-ref identity='AACC'/>
                    </to>
                    <summary>summary value</summary>
                    <reference-code>quote ref value</reference-code>
                    <expiry>2009-08-01T15:30:00</expiry>
                </header>
                <!-- e.g. line with tax -->
                <line quantity="2">
                    <code>product code</code>
                    <name>name value</name>
                    <description>desc value</description>
                    <unit-of-measure unit="EA"/>
                    <unit-price iso-currency-code="USD">50.00</unit-price>
                    <subtotal iso-currency-code="USD">100.00</subtotal>
                    <tax iso-currency-code="USD">15</tax>
                    <total iso-currency-code="USD">115</total>
                </line>
            </create-quote-request>
        </u:body>
    </u:pox-envelope>
  • Sending SOAP Messages to Unimarket

    Overview

    SOAP is a protocol specification for exchanging structured information (XML) in the implementation of Web Services. Clients using this protocol will usually use the Unimarket wsdl to generate the required code on their chosen platform.

    Basic getting started guide

    • Contact Unimarket to provide you with the authentication details required (tenant identifier, integration username and shared secret).
    • Download the Unimarket wsdl (see Webservice Integration Documentation) and identify the operation for sending the chosen request element to Unimarket.
    • Download the Unimarket xml schema (see Webservice Integration Documentation) and identify the top-level request element to send to Unimarket.
    • Create a request message that conforms to the xml schema.
    • Send a valid SOAP message containing the request message and the authentication header element to one of the following two applicable urls.
    1. Supplier
    2. Commmunity
    Tip: Use the free soapUI client to test sending messages to Unimarket.

     

    Example SOAP message

    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
        <SOAP-ENV:Header>
            <header xmlns="http://www.unimarket.com/schema/unimarket-ws">
                <authentication>
                    <!-- Unique identifier of the Unimarket tenant (community or supplier) -->
                    <tenant-ref domain="UNIMARKET_ID_DOMAIN" identity="782965bc-f39b-4589-8949-5530e6d1b287"/>
                    <sender>
                        <!-- Unique identifier of the Unimarket integration user -->
                        <user-ref identity="AACCUMKT" domain="UNIMARKET_USERNAME_DOMAIN"/>
                        <!-- Password used to authenticate the request -->
                        <shared-secret>shared secret</shared-secret>
                    </sender>
                </authentication>
            </header>
        </SOAP-ENV:Header>
        <SOAP-ENV:Body>
            <update-account-code-format-request xmlns="http://www.unimarket.com/schema/unimarket-ws">
                <account-code-format code="PROJECT_A">
                    <account-code-format-part code="part-a" required="true">
                        <regular-expression-part max-length="1">
                            <expression>.*</expression>
                        </regular-expression-part>
                    </account-code-format-part>
            </update-account-code-format-request>
        </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>