Skip to main content

Cordial — Authentication

B
Written by Ben Keeling

How to create a Cordial API key for Medialake, allow Medialake's servers to use it, and understand exactly what access it grants.



​

What to expect

Cordial is connected with an API key that you create in your own Cordial account, together with your account's API URL. There is no Cordial sign-in or consent screen during setup: nobody is redirected to Cordial to log in. Instead, a Cordial administrator creates the key, a Medialake administrator saves it in Medialake, and Medialake calls the Cordial API server-side from then on.

Cordial API keys only work from the IP addresses listed on the key, so Medialake's server IP addresses must be added to the key before anything else will work. Request the current list from [email protected] when you set up the key.

Cordial has no media library API, so Medialake works from the emails that use your images. It reads your batch messages and automation templates, asks Cordial to render each one, and picks out the image URLs in the finished HTML. Rendering is needed because emails built in Cordial's drag-and-drop editor, Sculpt, contain only placeholders until they are rendered. Rendering returns the HTML to Medialake and does not send anything. The Cordial connector only reads: it does not create, edit, send, or delete anything in Cordial.

 Cordial administrator           Medialake                   Cordial
      │  create an API key and        │                         │
      │  allow Medialake's IPs        │                         │
      │────────────────────────────────────────────────────────▶│
      │                               │                         │
 Medialake administrator              │                         │
      │  save the key and API         │                         │
      │  URL as an access key         │                         │
      │──────────────────────────────▶│                         │
      │                               │                         │
 Team member                          │                         │
      │  connect and choose           │                         │
      │  folders to sync              │                         │
      │──────────────────────────────▶│  list messages and      │
      │                               │  templates, render each │
      │                               │────────────────────────▶│
      │                               │  rendered HTML          │
      │                               │◀────────────────────────│
      │                               │  download each image    │
      │                               │  from its own URL       │


​

Before you begin

You will need:

  • A Cordial user whose role allows creating API keys

  • Medialake's current server IP addresses, from [email protected]

  • Administrator privileges in Medialake, to add the key to the Cordial integration

>Keep the key private. Store it in an approved password manager or secret-management system. Do not email it, paste it into a support ticket, or commit it to source control. Medialake stores the values you enter encrypted.


​

Step 1: Get Medialake's IP addresses

Email [email protected] and ask for the IP addresses Medialake uses to call the Cordial API. Use the list support sends you rather than addresses copied from another document, so the key allows exactly the servers that will use it.


​

Step 2: Create an API key in Cordial

  1. In Cordial, go to Settings → API Keys.

  2. Click New.

  3. Give the key a unique, recognizable name, such as Medialake.

  4. Add each IP address from Step 1 to the key's allowed IP addresses. Cordial accepts single addresses and CIDR ranges, but not wildcard patterns.

  5. In the Permissions pane, select the four API calls in the table below, and nothing else.

  6. Click Generate Key, then copy the key from the API keys list.

API call

How Medialake uses it

GET /v2/batchmessages

List your batch messages. Medialake also uses this call to confirm the key works.

GET /v2/batchmessages/{id}/renderedwip/{contactID}

Render each batch message.

GET /v2/automationtemplates

List your automation templates.

GET /v2/automationtemplates/{key}/renderpublished/{contactID}

Render the published version of each automation template.

Medialake renders with the contact ID 0 rather than a real contact's ID, so it does not render any email for a specific contact.

Use a key dedicated to Medialake rather than one shared with another system. That way its allowed IP addresses and permissions can be set for Medialake alone, and it can be revoked without affecting anything else.


​

Step 3: Find your API URL

In Cordial, your account's API URL is shown under Account Settings → Account → API. It depends on which Cordial admin site you sign in to, and is usually one of these:

https://api.cordial.io/v2
https://api.usw2.cordial.io/v2

Medialake accepts only https:// addresses on Cordial's own cordial.io domain, because the API key is sent to this address. If you leave off /v2, Medialake adds it.


​

Step 4: Add the key to Medialake

You need administrator privileges in Medialake for this step.

  1. In Medialake, open Administration → Integrations from the sidebar.

  2. Open the Cordial integration.

  3. In the Access Keys section, click Create New Setting.

  4. In the New access key panel, give the key a Name, such as Cordial email. The name is shown in the access key list and next to every account that connects with it.

  5. Under Credentials, fill in:

- Cordial API key: the key from Step 2. The field's label also reminds you that the key must allow Medialake's IP addresses.

- Cordial API URL for your account (Account Settings → Account → API): the URL from Step 3, for example https://api.cordial.io/v2.

  1. Under Who can use it?, choose which teams can connect Cordial with this key, or make it available to all teams.

  2. Click Save access key.

Medialake checks that the API URL is a valid Cordial address before saving. Saving does not contact Cordial.

To check the key against Cordial, click Test next to it in the Access Keys list. Medialake lists your batch messages, renders one of them, and lists your automation templates. An account with no messages yet still passes. If everything works, you see "The provider accepted these credentials."


​

Connect Cordial and choose what to sync

Any team member who can connect sources (a Team Manager or Write user), on a team that can use the access key, can add Cordial as a source.

  1. Open Connections → Catalogue from the side menu.

  2. Find Cordial and click Connect.

  3. Under Access key, select the access key from Step 4. You can click Test to check it again.

  4. Click Connect. There is no Cordial login page: Medialake connects with the saved key.

  5. Choose which folders to sync. Nothing is synced until you select it.

  6. Set the Frequency. Cordial syncs once a week by default. You can change this to once a day or once a month, or choose Manual.

Cordial always shows the same two folders:

Folder

What Medialake renders

Batch Messages

The current working version of every batch message.

Automation Templates

The published version of every automation template.

From each rendered email, Medialake picks up the images in image and source tags, srcset attributes, and CSS backgrounds, as long as they are a file type Medialake supports. Each synced file records the message or template it came from, its name and tags, and whether the image is hosted on Cordial's image CDN.

A few behaviors to be aware of:

  • Each image is stored once, however many emails, sizes, or folders it appears in.

  • Images on Cordial's image CDN are downloaded at their original size, even when an email uses a resized version.

  • Personalized content is synced in its generic form. Medialake renders without personalization, so a "recommended for you" image appears in its non-personalized version, and only the default variant of an A/B test is rendered. Image URLs that still contain personalization placeholders are skipped.

  • Images generated on every open are skipped. Countdown timers and similar live images from gen.sendtric.com and img.ltms.app are not synced.

  • Some content cannot be rendered. Cordial cannot render some older Sculpt messages, or automation templates that were never published. For those, Medialake syncs only the images already present in the saved HTML.

  • Every sync renders everything again. Each sync renders every message and template, so a sync of a large account can take several hours.


​

Limiting what Medialake can access

Three controls limit what the key can do, and Cordial enforces all of them:

  • Allowed IP addresses. The key works only from the addresses you listed, so it cannot be used from anywhere else.

  • Permissions. The key can call only the API calls selected in its Permissions pane. The four in Step 2 are all reads.

  • Account scope. A Cordial API key belongs to a single Cordial account.

Choosing folders in Medialake controls what is synced, but it does not narrow the key itself.


​

What Medialake can and cannot do

With the permissions above, Medialake can:

  • List your batch messages and automation templates, including their saved HTML

  • Render each message and template without personalization

  • Download the images those emails use, from their own URLs

Medialake cannot:

  • Read contacts, lists, audiences, or engagement data

  • Send, schedule, or change messages

  • Create, edit, or delete messages or templates

  • Use the key from any address that is not on its allowed list

Medialake sends your API key only to the API URL you entered. Images are downloaded from their own addresses without the key, and Medialake refuses to download from internal or private network addresses.


​

Staying connected

There is no token to refresh: Medialake uses the same key for every sync. If Cordial rejects the key during a sync, Medialake checks it again by listing batch messages, and if Cordial still rejects it, the connection is marked as unauthorized.

The connection stops working if the key is deleted in Cordial, if Medialake's IP addresses are removed from it, or if its permissions change. Cordial can answer a wrong key, a blocked IP address, and a missing permission with the same error, so check all three when a connection fails.

Cordial recommends rotating API keys regularly. To replace the key, create a new one with the same allowed IP addresses and the same permissions. Then add it in Medialake as a new access key and switch the connection to it. To switch, open the source's General tab, click Change Key in its Access Keys section, select the new key, and click Save. You can delete the old access key in Medialake once no connection uses it.


​

Revoking access

To revoke Medialake's access, delete the key in Cordial under Settings → API Keys. Medialake's requests fail from that moment.

Remove the Cordial connection in Medialake as well if it should no longer sync, then delete its access key from the Access Keys list.


​

Troubleshooting

Symptom

What to check

"must be a valid URL" or "format is invalid" for the API URL when saving

Enter the full https:// URL from Account Settings → Account → API. Only addresses on cordial.io are accepted.

Test shows "The provider rejected these credentials."

Cordial answers three different problems this way. Check that the key is correct, that Medialake's IP addresses are on the key's allowed list, and that the key has permission for GET /v2/batchmessages. Also check that the API URL matches the admin site you sign in to.

Test shows "The Cordial API key can list batch messages but not render them."

The key needs permission for GET /v2/batchmessages/{id}/renderedwip/{contactID}. If you create a new key that has it, add it to Medialake as a new access key.

Test shows "The Cordial API key can list batch messages but not automation templates."

The key needs permission for GET /v2/automationtemplates. If you create a new key that has it, add it to Medialake as a new access key.

Test shows "These credentials look right, but the provider couldn't confirm them just now."

Cordial could not be reached or was rate-limiting. Try again in a few minutes.

Automation Templates fails to sync, but Test passes

Test does not check the template rendering endpoint. Check that the key has permission for GET /v2/automationtemplates/{key}/renderpublished/{contactID}.

An email's images are missing

The email may be an older Sculpt message or a never-published template that Cordial cannot render, or the images may be personalized or generated on open.

A sync takes hours

Every sync renders every message and template again. This is expected for large accounts.

The connection is marked as unauthorized

The key was deleted, Medialake's IP addresses were removed from it, or its permissions changed.

If the issue continues, contact [email protected] with your API URL, the folders you selected, and the error message. Do not include the API key.


​

Further reading


Questions about connecting Cordial? Contact [email protected].

Did this answer your question?