Skip to content
LabelZoom Docs

C# Quickstart

Install

Section titled “Install”
Terminal window
dotnet add package LabelZoom.Sdk

Targets netstandard2.0 (so .NET Framework 4.6.1+, .NET Core 2.0+, .NET 5+) and net8.0.

Convert ZPL to PDF

Section titled “Convert ZPL to PDF”

An API key is optional — without one you get the free tier.

using LabelZoom.Sdk;


using var client = new LabelZoomClient();   // reads LABELZOOM_API_KEY; anonymous if unset


var result = await client.Convert()
    .FromZpl("^XA^FO50,50^ADN,36,20^FDLabelZoom^FS^XZ")
    .ToPdf()
    .WithLabelSize(widthInches: 4f, heightInches: 6f)
    .WithDpi(203)
    .ExecuteAsync();


result.Save("label.pdf");
Console.WriteLine("Wrote label.pdf");

result.Bytes is authoritative — five of the thirteen targets are binary. result.Text decodes it with the response charset for the textual ones, and result.Save(path) writes it straight to disk. result.RequestId is the X-LZ-Request-Id support handle.

Passing the key explicitly:

using var client = new LabelZoomClient("lz_live_...");
using var fromEnvironment = new LabelZoomClient();  // reads LABELZOOM_API_KEY

Converting a PDF to ZPL

Section titled “Converting a PDF to ZPL”
var result = await client.Convert()
    .FromFile(SourceFormat.Pdf, "shipping-label.pdf")
    .ToZpl()
    .WithLabelSize(widthInches: 4f, heightInches: 6f)
    .WithPdfPage(0)                                 // 0-based; omit for every page
    .ExecuteAsync();


Console.WriteLine(result.Text);

SourceFormat and TargetFormat are distinct types, so .ToEpl() does not exist and .To(SourceFormat.Pdf) does not compile. Jpg and Url are source-only on the server, and the type system says so rather than letting you find out from a 404.

The printer languages epl, ipl, tspl, dpl and sbpl are targets — .FromPdf(bytes).ToEpl() is a real conversion. Read result.Bytes rather than the decoded text for those: EPL’s GW and TSPL’s BITMAP commands inline raw binary.

Filling variable fields

Section titled “Filling variable fields”

Each record produces one label:

var result = await client.Convert()
    .FromZpl(template)
    .ToPdf()
    .WithData(
        new { name = "ACME Corp", sku = "12345" },
        new { name = "Globex",    sku = "67890" })
    .ExecuteAsync();                                // a 2-page PDF

Calling the REST API directly

Section titled “Calling the REST API directly”

The SDK is a wrapper over one HTTP endpoint; HttpClient works just as well (.NET 6+).

using System.Net.Http.Headers;


var zpl = "^XA^FO50,50^ADN,36,20^FDLabelZoom^FS^XZ";
var apiKey = Environment.GetEnvironmentVariable("LABELZOOM_API_KEY");


using var client = new HttpClient();
// The API key is optional — omit the Authorization header if it isn't set.
if (!string.IsNullOrEmpty(apiKey))
{
    client.DefaultRequestHeaders.Authorization =
        new AuthenticationHeaderValue("Bearer", apiKey);
}


var content = new StringContent(zpl, System.Text.Encoding.UTF8, "text/plain");
var response = await client.PostAsync(
    "https://api.labelzoom.com/api/v2/convert/zpl/to/pdf?label.width=4&label.height=6&dpi=203",
    content);


response.EnsureSuccessStatusCode();
await File.WriteAllBytesAsync("label.pdf", await response.Content.ReadAsByteArrayAsync());
Console.WriteLine("Wrote label.pdf");

To convert a PDF to ZPL, post a ByteArrayContent with Content-Type: application/pdf to /convert/pdf/to/zpl and read await response.Content.ReadAsStringAsync().

Notes

Section titled “Notes”