← Jellybooks Technical Documentation
This guide explains how to deliver publication assets to Jellybooks for ingestion into our platform. Each publication requires three files — the ebook, a cover image, and an Onix metadata record — and there are two supported ways to organise them for transfer.
Jellybooks operates two SFTP servers for asset delivery:
The two servers are identical in content and capability. Use whichever is geographically closer to you; you will get a more reliable connection.
You will have been assigned a dedicated username for SFTP access. This is not the same as any username you may have for Jellybooks web-based resources.
Connect using your assigned username and the hostname of your preferred server:
sftp <your-username>@assets.jellybooks.com sftp <your-username>@usa-assets.jellybooks.com
Depending on your SFTP client you may need to supply the username and hostname as separate fields rather than in the combined user@host form above.
When you connect, you will see a directory called incoming. Place all your asset files inside that directory, following the structure described in the Asset delivery structure section below.
For each publication, Jellybooks requires the following three assets in order to process and integrate the title into our platform:
| Asset | Extension | Notes |
|---|---|---|
| Ebook | .epub, .pdf |
ePub version 3.0 or greater is preferred. Version 2 is still accepted but deprecated. PDF files must be valid, contain at least one page, and must not be encrypted or password-protected in any way, including permissions-only (owner password) protection. Deliver one ebook format per ISBN-13. If an ePub and a PDF are delivered together for the same ISBN-13, we use the ePub and ignore the PDF. To replace a PDF we have already ingested, deliver the new file with its Onix through the same SFTP account. |
| Cover image | .jpg, .jpeg | High-resolution cover image. A long edge of 1200 px or greater is preferred; 800 px is the minimum we accept. The vast majority of covers are portrait, so this corresponds to a preferred height of ≥ 1200 px and a minimum height of ≥ 800 px. |
| Onix metadata | .xml | Book metadata should be in Onix version 3.0 or 3.1. Version 2 is still accepted but deprecated. |
An Onix message can carry a wide range of metadata. We require at a minimum the following fields:
The Onix metadata, and therefore the ISBN-13 code, must be for the ebook product form of the publication.
In addition, we strongly recommend including the following fields where applicable:
Tag format: For Onix 3.0 and 3.1 we accept both short tags and long (reference) tags. Onix 2 files must use long tags.
All assets are placed inside the incoming directory on the SFTP server. To allow us to associate the three asset files for a single publication with each other, two formats are supported.
Create a sub-directory inside incoming whose name is the publication's ISBN-13. Place the ebook, cover image, and Onix file inside that directory.
In this format the individual filenames within the directory may be arbitrary, but it is good practice to prefix them with the same ISBN-13.
incoming/
9123456123456/
9123456123456.epub
9123456123456.jpg
9123456123456.xml
9321321654654/
9321321654654_epub3.epub
9321321654654_hires.jpg
9321321654654_onix.xml
9456789456789/
9456789456789.pdf
9456789456789.jpg
9456789456789.xml
Alternatively, all assets may be placed directly inside the incoming directory without sub-directories. In this case every file must be named exactly with its publication's ISBN-13 followed by the file extension, with nothing else in the name, so that the three assets can be grouped correctly.
incoming/ 9123456123456.epub 9123456123456.jpg 9123456123456.xml 9456789456789.pdf 9456789456789.jpg 9456789456789.xml
ISBNs used in directory and file names must not contain spaces, hyphens, or other separators. Use the strictly numeric 13-digit format as specified in the Onix standard.