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
In Cordial, go to Settings → API Keys.
Click New.
Give the key a unique, recognizable name, such as
Medialake.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.
In the Permissions pane, select the four API calls in the table below, and nothing else.
Click Generate Key, then copy the key from the API keys list.
API call | How Medialake uses it |
| List your batch messages. Medialake also uses this call to confirm the key works. |
| Render each batch message. |
| List your automation templates. |
| 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.
In Medialake, open Administration → Integrations from the sidebar.
Open the Cordial integration.
In the Access Keys section, click Create New Setting.
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.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.
Under Who can use it?, choose which teams can connect Cordial with this key, or make it available to all teams.
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.
Open Connections → Catalogue from the side menu.
Find Cordial and click Connect.
Under Access key, select the access key from Step 4. You can click Test to check it again.
Click Connect. There is no Cordial login page: Medialake connects with the saved key.
Choose which folders to sync. Nothing is synced until you select it.
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.comandimg.ltms.appare 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 |
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 |
Test shows "The Cordial API key can list batch messages but not render them." | The key needs permission for |
Test shows "The Cordial API key can list batch messages but not automation templates." | The key needs permission for |
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 |
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
Cordial API reference: authentication and the base API URL
RESTful API summary and usage: Cordial's overview of its REST API
API keys: creating a key, adding allowed IP addresses, and choosing its permissions
Questions about connecting Cordial? Contact [email protected].
