Quickstart with an API key

From a new key to a verified domain, a sent email and signed webhooks. Every request below is checked against the service's OpenAPI document.

Download Postman collectionPrefer clicking? Every step is in the collection.
Setup
export REACH_API_URL="https://api.tryreach.email"
export REACH_API_KEY="rk_..."   # step 1
  1. Step 1: Create an API key

    Sign in to the console, find the API keys section of the dashboard and create a key for your project. The full key (rk_…) is shown exactly once: copy it into your secret store immediately. Afterwards the console only shows a prefix and the last 4 characters, and a lost key can only be replaced, never retrieved. A key holds every scope and is scoped to one organisation and project.

    Send it as Authorization: Bearer $REACH_API_KEY on every /v1 call. Never put it in a URL, a log line or client-side code.

  2. Step 2: Create a tenant for your customer

    One tenant per customer of yours. externalId is your own id for that customer, and it makes the call idempotent: posting the same externalId again returns 200 and the existing tenant (a new tenant is 201), never a duplicate or an error.

    POST /v1/tenants

    Create a tenant (curl)
    curl -X POST "https://api.tryreach.email/v1/tenants" \
      -H "Authorization: Bearer $REACH_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
      "name": "Acme Corp",
      "externalId": "cust_8f2e1a"
    }'
    Response
    // 201 Created. 200 with the same tenant if "cust_8f2e1a" already has one.
    {
      "id": "tn_9f8c2a1d",
      "name": "Acme Corp",
      "externalId": "cust_8f2e1a",
      "status": "provisioning",
      "limits": { "perDay": 200, "perHour": 20, "burstPerSecond": 5 },
      "provider": { "mapped": false, "syncedAt": null, "syncError": null },
      "createdAt": "2026-09-29T12:00:00.000Z",
      "updatedAt": "2026-09-29T12:00:00.000Z"
    }

    A new tenant starts as provisioning while its provider-side twin is created. provisioning and provision_failed tenants cannot send; only active can. Read it back until it is active.

    GET /v1/tenants/{id}

    Read the tenant until it is active (curl)
    curl -X GET "https://api.tryreach.email/v1/tenants/tn_9f8c2a1d" \
      -H "Authorization: Bearer $REACH_API_KEY"
    Response
    // status is "provisioning", "active", "suspended" or "provision_failed".
    // Only "active" can send.
    { "id": "tn_9f8c2a1d", "status": "active", "...": "..." }
  3. Step 3: Add and verify the sending domain

    A tenant sends from its own domain, and only verified domains can send. Add the domain, publish the DNS records it returns, then poll.

    POST /v1/domains

    Add a sending domain (curl)
    curl -X POST "https://api.tryreach.email/v1/domains" \
      -H "Authorization: Bearer $REACH_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
      "tenant": "tn_9f8c2a1d",
      "domain": "acme.com"
    }'
    Response
    // 201 Created (200 if the tenant already has this domain).
    {
      "id": "dom_41c7a9e2",
      "tenant": "tn_9f8c2a1d",
      "domain": "acme.com",
      "status": "pending",
      "records": [
        {
          "purpose": "dkim",
          "type": "CNAME",
          "name": "abc123._domainkey.acme.com",
          "nameHostOnly": "abc123._domainkey",
          "value": "abc123.dkim.example-ses.com",
          "required": true,
          "status": "missing"
        }
      ],
      "...": "..."
    }

    Each entry in records is shaped for direct copy-paste:

    DNS record fields
    FieldMeaning
    purposedkim (CNAME), mail_from_mx (MX), mail_from_spf (TXT), dmarc (TXT).
    nameFully qualified. Paste as-is into most registrars.
    nameHostOnlyThe same name without your domain suffix. Use this if your registrar appends the domain for you; confusing the two is the most common cause of a record that never verifies.
    valueCopy exactly. For MX records priority is included.
    requiredFalse only for the recommended DMARC record, which is never needed for verified.
    statusPer-record diagnosis: missing (not found in DNS), mismatch (found but different), ok. Compare expected with found.

    GET /v1/domains/{id}

    Poll the domain until it is verified (curl)
    curl -X GET "https://api.tryreach.email/v1/domains/dom_41c7a9e2" \
      -H "Authorization: Bearer $REACH_API_KEY"
    Response
    // status: "pending" -> "verified" (or "failed").
    // records[].status is "missing", "mismatch" or "ok" for each record.
    // verificationDeadline is when a still-pending domain becomes "failed":
    // read it from the response, it is configurable and not a constant.
    {
      "id": "dom_41c7a9e2",
      "status": "pending",
      "verificationDeadline": "2026-10-02T12:00:00.000Z",
      "lastCheckedAt": "2026-09-29T12:05:00.000Z",
      "...": "..."
    }
  4. Step 4: Send an email

    tenant, from, to and subject are required, plus html and/or text. to is a single recipient in this version; cc, bcc and an array in to are not supported yet (coming soon) and are rejected with 422 unsupported_field, never silently dropped. The from domain must be one of the tenant's verified domains.

    POST /v1/emails

    Send an email (curl)
    curl -X POST "https://api.tryreach.email/v1/emails" \
      -H "Authorization: Bearer $REACH_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
      "tenant": "tn_9f8c2a1d",
      "from": "billing@acme.com",
      "to": "customer@example.com",
      "subject": "Your invoice is ready",
      "html": "<p>Hi, your invoice for September is ready.</p>",
      "idempotencyKey": "invoice-2026-09-cust_8f2e1a"
    }'
    Response
    // 202 Accepted. Delivery happens afterwards, in a worker.
    // Repeating the request with the same idempotencyKey returns this same id
    // and the response header x-reach-idempotent-replay: true.
    // A brand-new organisation's first sends come back as "status": "held"
    // instead of "queued": expected, not an error (see "Held sends" below).
    {
      "id": "em_5b1e7c40",
      "status": "queued",
      "tenant": "tn_9f8c2a1d",
      "acceptedAt": "2026-09-29T12:00:00.000Z"
    }

    Attachments

    attachments is an array of { filename, content, contentType?, contentId? }. content is the file as standard base64 (RFC 4648 section 4: padded, no line breaks); anything else is 422 validation_failed. There is no URL or path form: Reach never fetches a URL on your behalf, and an unknown key such as path is refused, not ignored. Add contentId to make a file inline and reference it from the HTML as <img src="cid:THE_ID">; without it the file is a regular attachment.

    POST /v1/emails

    Send an email with attachments and an inline image (curl)
    curl -X POST "https://api.tryreach.email/v1/emails" \
      -H "Authorization: Bearer $REACH_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
      "tenant": "tn_9f8c2a1d",
      "from": "billing@acme.com",
      "to": "customer@example.com",
      "subject": "Your invoice is ready",
      "html": "<p>Your invoice is attached.</p><img src=\"cid:logo\" alt=\"Acme\">",
      "attachments": [
        {
          "filename": "invoice-2026-09.pdf",
          "content": "JVBERi0xLjQK",
          "contentType": "application/pdf"
        },
        {
          "filename": "logo.png",
          "content": "iVBORw0KGgo=",
          "contentId": "logo"
        }
      ],
      "idempotencyKey": "invoice-2026-09-cust_8f2e1a-pdf"
    }'
    Response
    // 202 Accepted, same shape as any other send. The sample content above is
    // a few bytes of base64 so it stays readable; send the real file's base64.
    // logo.png has a contentId, so it is inline: the html reaches it as cid:logo.
    // invoice-2026-09.pdf has none, so it is a regular attachment.
    {
      "id": "em_5b1e7c41",
      "status": "queued",
      "tenant": "tn_9f8c2a1d",
      "acceptedAt": "2026-09-29T12:00:00.000Z"
    }
    Node: base64 from a file
    import { readFile } from "node:fs/promises";
    
    // content is the file's bytes as standard base64: pass the string as-is,
    // not a Buffer and not a number.
    const content = (await readFile("invoice-2026-09.pdf")).toString("base64");
    
    const attachments = [
      { filename: "invoice-2026-09.pdf", content, contentType: "application/pdf" },
    ];
    // Inline image: add contentId, then use <img src="cid:logo"> in your html.
    // { filename: "logo.png", content: logoBase64, contentId: "logo" }
    Attachment rules
    RuleDetail
    Count and sizeAt most 20 files and 10 MiB of decoded bytes in total (not the base64 length); these are the service defaults, so treat the error as the authority if they are ever tuned. Over either is 422 validation_failed with details[0].field attachments and reason too_many:max_20 or attachments_too_large.
    filename1-255 characters; no control characters (including CR/LF) or invisible formatting characters, and no / or \. Reasons: length_1_to_255, contains_control_or_format_characters, contains_path_separator.
    Unsupported extensionExtensions Amazon SES does not accept (.exe, .js, .bat and the rest of AWS's unsupported attachment types) are 422 unsupported_attachment_type with reason unsupported_extension:<ext>. Judged on the final extension, case-insensitively, ignoring trailing dots and spaces.
    contentTypeA media type such as application/pdf, up to 255 characters. When omitted it is inferred from the extension, and is application/octet-stream if the extension is unknown. Invalid: reason invalid_media_type.
    contentId1-255 characters, no whitespace, angle brackets or control characters, and unique (case-insensitive) within the email. Reasons: invalid_content_id, duplicate_content_id.
    Per-attachment errorsdetails[0].field names the exact attachment, for example attachments[1].content with reason invalid_base64.

    Attachment content waits only in the delivery queue. The email log never stores it, nor the filenames or content types: GET /v1/emails/{id} returns just attachments.count and size.attachmentBytes (decoded bytes, 0 when there are none).

    Custom headers, tags and Idempotency-Key

    POST /v1/emails

    Send with custom headers, tags and an Idempotency-Key header (curl)
    curl -X POST "https://api.tryreach.email/v1/emails" \
      -H "Authorization: Bearer $REACH_API_KEY" \
      -H "Idempotency-Key: newsletter-2026-10-cust_8f2e1a" \
      -H "Content-Type: application/json" \
      -d '{
      "tenant": "tn_9f8c2a1d",
      "from": "news@acme.com",
      "to": "customer@example.com",
      "subject": "October news",
      "text": "Hello! To stop these emails, use the unsubscribe link in your mail client.",
      "headers": {
        "List-Unsubscribe": "<https://your-app.example/unsubscribe/cust_8f2e1a>, <mailto:unsubscribe@acme.com>",
        "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
      },
      "tags": [
        {
          "name": "campaign",
          "value": "october-news"
        },
        {
          "name": "plan",
          "value": "pro"
        }
      ]
    }'
    Response
    // 202 Accepted. The Idempotency-Key header is the same thing as the body's
    // idempotencyKey (here it is sent only as a header).
    // Tags can also be a record: "tags": { "campaign": "october-news" }.
    {
      "id": "em_5b1e7c42",
      "status": "queued",
      "tenant": "tn_9f8c2a1d",
      "acceptedAt": "2026-10-01T09:00:00.000Z"
    }
    Headers, tags and idempotency
    FieldRules
    headersAn object of extra message headers, e.g. List-Unsubscribe. At most 15. Names: 1-126 printable ASCII characters, no :, unique case-insensitively. Values: 1-995 printable ASCII characters (space to ~: no tab, no CR/LF, no non-ASCII). Name and value together at most 996 characters. Header values are never stored.
    Reserved header namesRefused with 422 validation_failed (reason reserved_name:<name>), never dropped: From, To, Cc, Bcc, Subject, Reply-To, Sender, Return-Path, Message-ID, Date, MIME-Version, Received, and any name starting Content-, DKIM- or X-SES-. Other header reasons: too_many:max_15, invalid_name, duplicate_name, empty_value, value_too_long, value_non_printable_ascii, name_plus_value_too_long.
    tagsEither a record, { "campaign": "welcome" }, or the array form [{ "name": "campaign", "value": "welcome" }]. At most 50; every name and value is 1-256 characters from A-Z a-z 0-9 _ -. Tags are validated, not rewritten: an invalid tag is 422 validation_failed naming it (reasons such as name_invalid_characters:<name>, value_empty:<name>, too_many:max_50, duplicate_name). Earlier versions silently rewrote them (a b became a_b); that no longer happens. They are read back as the record form.
    Idempotency-KeyA request header equivalent to the body idempotencyKey (same 8-255 characters, same behaviour). Send either one. If you send both and they differ the request is 422 validation_failed (field Idempotency-Key, reason differs_from_body_idempotencyKey); identical is fine.
    Wrong JSON typesIn attachments, headers and tags, a value that is not a string (a number, an array, null) is refused with 422 validation_failed and reason must_be_a_string (or must_be_an_object for an array item). It is never converted: "content": 1234 is an error, not the base64 string "1234".
    Send behaviour
    SituationWhat you get
    idempotencyKey (8-255 chars)Scoped to (tenant, key). A repeat returns the original id and sends nothing, with the response header x-reach-idempotent-replay: true. Always set it on anything you might retry.
    Recipient is on the suppression listStill 202, with status: "suppressed" and no provider call. Release it with DELETE /v1/suppressions.
    Domain not verified422 domain_not_verified
    Tenant not active409 tenant_not_sendable or 409 tenant_suspended
    Your organisation's first send has not been approved yet202 with status: "held". Expected, not an error; see below.
    A send limit was hit (per tenant, or your organisation's plan ceiling)429 rate_limited with Retry-After; details[0].reason names the window and tells you which of the two limits it was. Never blocks a retry of an already-accepted idempotency key. See rate limits.
  5. Step 5: Read the status

    A 202 means the email is recorded and queued; delivery happens afterwards. Poll it, list the log, or (better) use webhooks. held means accepted but waiting for your organisation's first-send approval. sent means the provider accepted it, which is not delivered; a bounce or complaint arrives later and adds the address to the suppression list.

    GET /v1/emails/{id}

    Read the email's status (curl)
    curl -X GET "https://api.tryreach.email/v1/emails/em_5b1e7c40" \
      -H "Authorization: Bearer $REACH_API_KEY"
    Response
    // status: queued, held, dispatching, sent, dispatch_unconfirmed, delivered,
    // bounced, complained, failed, suppressed or canceled.
    // "held" = accepted, waiting for Reach to approve your organisation's first send.
    // "sent" means the provider accepted it, not that it was delivered.
    // size.attachmentBytes (decoded bytes) and attachments.count are 0 when there
    // are none. Filenames, content and header values are never stored or returned.
    // opens / clicks count email.opened / email.clicked events. Approximate (security
    // scanners click links, Apple Mail preloads the pixel) and 0 unless
    // tracking is on for the tenant (it is on by default; organisation and tenant can turn it off).
    {
      "id": "em_5b1e7c40",
      "status": "delivered",
      "size": { "htmlBytes": 46, "textBytes": 0, "attachmentBytes": 0 },
      "attachments": { "count": 0 },
      "tags": {},
      "events": [ "..." ],
      "opens": 0,
      "clicks": 0,
      "...": "..."
    }

    GET /v1/emails

    List emails (curl)
    curl -X GET "https://api.tryreach.email/v1/emails?tenant=tn_9f8c2a1d&status=bounced&limit=20" \
      -H "Authorization: Bearer $REACH_API_KEY"
    Response
    { "rows": [ "..." ], "total": 1 }

    Filtering the log

    Besides status, group, to, from_date and to_date, GET /v1/emails takes three more filters. They combine with AND, and every row carries opens and clicks (see the note below).

    Email log filters
    QueryMatches
    subjectSubject contains this text, case-insensitive, 1 to 200 characters. Matched literally: %, _ and \ are ordinary characters.
    senderSender address, exact and case-insensitive. Compared with the bare address (ada@example.com), not the display name. It is called sender because from is not a query parameter.
    tagOne tag as key:value, exact on both. Key and value are 1 to 256 characters of A-Z a-z 0-9 _ -.

    A malformed tag (no colon, or a character outside that set) is 422 validation_failed. So is a control character (U+0000 to U+001F, U+007F) in to, subject or sender. An unknown query name is also a 422, never silently ignored.

    GET /v1/emails

    Filter the email log (curl)
    curl -X GET "https://api.tryreach.email/v1/emails?tenant=tn_9f8c2a1d&subject=welcome&sender=hello%40your-app.example&tag=campaign%3Awelcome" \
      -H "Authorization: Bearer $REACH_API_KEY"
    Response
    { "rows": [ { "id": "...", "opens": 2, "clicks": 1, "...": "..." } ], "total": 1 }
  6. Step 6: Receive signed webhooks

    A subscription receives every email and domain event for its tenant; there is no per-event filter in this version. The URL must be https and must not point at a private address.

    POST /v1/webhook-subscriptions

    Register a webhook subscription (curl)
    curl -X POST "https://api.tryreach.email/v1/webhook-subscriptions" \
      -H "Authorization: Bearer $REACH_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
      "tenant": "tn_9f8c2a1d",
      "url": "https://your-app.example/webhooks/reach"
    }'
    Response
    // 201 Created. "secret" is shown exactly once: store it now.
    {
      "id": "whs_2a9d0c11",
      "tenant": "tn_9f8c2a1d",
      "url": "https://your-app.example/webhooks/reach",
      "status": "active",
      "secret": "rsec_...",
      "...": "..."
    }

    What a delivery looks like

    Webhook request headers
    HeaderValue
    x-reach-signatureLowercase hex HMAC-SHA256 of the signed string below.
    x-reach-timestampUnix seconds when the request was sent. Part of the signed string.
    x-reach-event-typeThe event type, e.g. email.delivered, domain.verified, email.opened, email.clicked. Treat unknown types as ignorable.
    x-reach-delivery-idThis delivery's id. Use it to de-duplicate.
    Request body
    {
      "id": "whd_abc",                      // this delivery
      "eventId": "evt_xyz",                 // the event; identical across subscribers
      "type": "email.delivered",
      "tenant": "tn_9f8c2a1d",
      "occurredAt": "2026-09-29T12:00:05.000Z",
      "data": { }                           // event detail; shape depends on type
    }

    Open and click events

    While tracking is on for a tenant, email.opened and email.clicked are delivered like any other email event and appear in the email's events list. Because a subscription receives every event type for its tenant, an endpoint on a tracked tenant starts receiving them without any change on your side: it must ignore types it does not know. They are history only: they never change the email's status (a delivered email stays delivered) and never add a suppression. A click carries only linkHost and linkHash in data, never the full URL, its path or query, and neither event carries the recipient's IP address or user agent. Two links of one email can be told apart by linkHash, but the URL cannot be recovered from it. Counts are approximate, see Read the status.

    Engagement events
    // type "email.clicked": which site, never the URL
    {
      "id": "whd_def",
      "eventId": "evt_uvw",
      "type": "email.clicked",
      "tenant": "tn_9f8c2a1d",
      "emailId": "em_5b1e7c40",
      "occurredAt": "2026-09-29T12:04:41.000Z",
      "data": {
        "linkHost": "shop.example.com",     // lower-case host of the clicked link
        "linkHash": "3fa94c0d1b27",         // first 12 hex chars of sha256(full URL)
        "...": "..."                        // plus provider bookkeeping fields
      }
    }
    
    // type "email.opened": the timestamp is the only engagement data
    { "type": "email.opened", "emailId": "em_5b1e7c40", "occurredAt": "2026-09-29T12:03:10.000Z", "data": { "...": "..." } }

    Verifying the signature

    The signed string is `${timestamp}.${rawBody}`, where rawBody is the exact bytes you received, not a re-serialisation of parsed JSON. The signature is hex(HMAC-SHA256(secret, signedString)). Compare in constant time, and reject any timestamp more than 5 minutes from your own clock, in the past or the future, even when the digest is valid.

    Verify a webhook (Verifier)
    import { createHmac, timingSafeEqual } from "node:crypto";
    
    const REPLAY_WINDOW_SECONDS = 300;
    
    /**
     * rawBody must be the exact bytes received (a string/Buffer from the raw
     * request), never JSON.stringify(parsedBody): a re-serialisation can reorder
     * keys or change whitespace and produce a different digest.
     */
    export function verifyReachWebhook({ secret, rawBody, headers, now = Date.now() }) {
      const timestamp = headers["x-reach-timestamp"];
      const signature = headers["x-reach-signature"];
      if (typeof timestamp !== "string" || typeof signature !== "string") return false;
    
      // Reject stale AND future timestamps, independently of the digest.
      const ts = Number.parseInt(timestamp, 10);
      if (String(ts) !== timestamp.trim()) return false;
      if (Math.abs(Math.floor(now / 1000) - ts) > REPLAY_WINDOW_SECONDS) return false;
    
      const expected = createHmac("sha256", secret)
        .update(`${timestamp}.${rawBody}`)
        .digest("hex");
    
      const a = Buffer.from(expected, "hex");
      const b = Buffer.from(signature, "hex");
      return a.length === b.length && timingSafeEqual(a, b); // constant time, never ===
    }

    Respond with any 2xx to mark a delivery succeeded. Otherwise it is attempted 6 times in total (the first attempt plus 5 retries, after roughly 5 minutes, 30 minutes, 2 hours, 6 hours and 14 hours, each with about ±20% jitter), then becomes failed; it is never left pending. The same event can reach you more than once, so handle it idempotently. Inspect and debug with:

    GET /v1/webhook-deliveries

    List webhook deliveries (curl)
    curl -X GET "https://api.tryreach.email/v1/webhook-deliveries?subscription_id=whs_2a9d0c11&status=failed" \
      -H "Authorization: Bearer $REACH_API_KEY"

    POST /v1/webhook-subscriptions/{id}/rotate-secret

    Rotate a webhook signing secret (curl)
    curl -X POST "https://api.tryreach.email/v1/webhook-subscriptions/whs_2a9d0c11/rotate-secret" \
      -H "Authorization: Bearer $REACH_API_KEY"