API reference

1. Create an account. Your account and its wallet exist immediately — no KYC, no top-up.
2. Generate a sandbox key on the API keys screen and pick its scopes. The secret is shown exactly once.
3. Call GET /v1/me with it (right) to confirm it works.
4. Build the whole integration against sandbox, then submit KYC, fund the wallet and swap in a live key. Nothing else about the request changes.

The split is deliberate: a leaked send credential must not be able to mint itself a live key or repoint your webhook at somebody else’s server.

Sandbox mirrors live on purpose. Anything you can observe from your side — statuses, timings, webhook bodies, failure codes — behaves the same, so an integration that works against a test key works against a live one without a code change.

A schema rejection carries an issues array naming the field and the rule that failed. Submitted values are never echoed back, so a rejected payload cannot leak into your logs through ours.

The shipped default is 120 requests per 60 seconds per key. Read the headers rather than hard-coding it: a limit can be raised for an account, and a client that respects X-RateLimit-Remaining keeps working when it is.

Keys are scoped to your account, so you are free to use any scheme that is unique within it — an order id, a UUID, a hash of the message. A replay is flagged with "duplicate": true in the response so you can tell the two apart.

• A key belongs to one request. The same key with a different request — other recipients, content, variables, schedule or mode — is a 409 IdempotencyKeyConflict carrying the original messageId or batchId, never a silent replay of something you did not ask for this time.
• “Different” means different in meaning. JSON key order, the order of recipients in a list, letter case in an email address and an absent versus an empty cc list do not make two requests different.
• A bulk key covers the whole batch. A retried bulk request returns the original batch — every message, the same batchId — with nothing sent or charged twice. A CSV and the same list sent as JSON count as the same request. Creation is also all-or-nothing, so a request that failed left nothing behind to collide with.

• There is no fallback price. A route Infitech has published no rate for is rejected with a 422 naming the route, never guessed at — so you cannot be surprised by a rate after the fact.
• Email is charged per recipient. One email to To + Cc + Bcc addresses costs the email rate × the number of addresses — the same as sending each a separate email. A shared email is reserved in full up front; if one recipient later fails, only that recipient’s share is refunded.
• A reservation is a debit. The balance drops the moment a send is accepted, so two concurrent sends cannot spend the same credit while the first is still queued. There is no separate held-funds figure to reconcile.
• Corrections are new ledger lines. Africa’s Talking prices by network, so a confirmed cost can differ from the one resolved at queue time. The difference is written as its own REFUND or DEBIT entry — a row that changes after the fact is not a ledger.
• Refunds are idempotent. A retried worker job or a duplicate provider callback refunds only what is still outstanding against that message, so nothing pays out twice.
• Sandbox is priced but never charged. A sandbox send reports its estimatedCost so you can size a campaign, and moves no money.

Price a recipient list before committing to it. Documented under Bulk cost preview.

Current rates are on your dashboard’s pricing screen and in the OpenAPI document.

The 202 response is the same shape as an SMS send, with recipients listing every address and the header it is in. It always describes one message, however many people it is addressed to.

Sending one email to several people

• Charged per recipient. A shared email costs the email rate × To + Cc + Bcc — exactly what the same number of separate emails would. The whole amount is reserved at once: if your wallet cannot cover every recipient the request is a 402 and nothing is reserved or sent.
• Up to 50 recipients per email by default, counting To, Cc and Bcc together. Infitech can change the limit; a request over it is a 413 that states both numbers. For more people, use bulk email.
• Each address once. An address repeated within or across to, cc and bcc is a 400 naming it — we do not guess which header you meant. Addresses are compared case-insensitively. Display names ("Mary <mary@x.com>") are not accepted: send the bare address.
• One opted-out recipient refuses the email. If any address is on your suppression list the request is a 403 listing every such address, and nothing is sent or charged. Removing someone silently would change who the email appears to be addressed to. (Bulk sends skip suppressed recipients instead, because each person gets a separate email.)
• Bcc stays private. Bcc addresses are given to the mail server as envelope recipients only. They never appear in the To or Cc headers, and there is no Bcc header.
• Recipients can fail separately. If the mail server accepts some addresses and refuses others, or one address later bounces, only that recipient fails and only its share is refunded. The message becomes PARTIALLY_FAILED, and you get a message.recipient.failed webhook naming the address. See Message lifecycle.
• Opens and clicks are counted per message. Everyone on a shared email receives the same content, so an open or a click cannot be traced to one recipient. A shared email also carries no one-click unsubscribe header, since the header cannot say which recipient is unsubscribing.

Takes recipients or recipientsCsv exactly as bulk SMS does, plus subject, text, html, replyTo, from and fromName from the single email send, and idempotencyKey as above. The response is the same BulkSendAccepted shape: one message per recipient, each with recipientCount: 1, all sharing one batchId.

• Each address once. A repeated address, in the array or the CSV and regardless of case, is a 400 naming both rows, and nothing is created. We do not guess which row’s variables you meant, and we do not email or charge anyone twice. (Bulk SMS still accepts a repeated number.)
• No Cc, Bcc or shared mode. Sending cc, bcc or "mode": "SHARED" here is a 400 pointing to POST /v1/email/send, never silently ignored. "mode": "INDIVIDUAL" is accepted, since it is what a bulk send already is.
• Suppressed recipients are skipped and listed in suppressedRecipients. The others still get their emails.

• Credit is reserved at schedule time, not at send time — so a scheduled send cannot fail later for want of balance.
• Content is rendered at schedule time. A templated scheduled send is immune to a later edit of that template: what you scheduled is what goes out.
• It must be in the future, with about a minute of slack for clock skew. A time already well past is refused rather than quietly sent now.
• There is no horizon limit. A distant schedule costs you your own reserved balance and nobody else anything.

Until it fires, the message sits in QUEUED with a non-null scheduledFor and can be cancelled. Pending ones are listed by GET /messages/scheduled on the session-authenticated surface.

The response is a full message object rather than a bare 204 because it is how you learn whether you beat the sweep. CANCELLED is its own terminal status, kept apart from REJECTED (Infitech refused it) and FAILED (it was attempted and did not arrive): only one of the three means nothing was ever tried, and it was your call.

Any valid key may ask what it is — requiring READ_ONLY would mean a send-only key could not run the snippet that verifies it. Asserting on environment here is a cheap way to catch a test key that reached production.

Every email has one recipient row per address; the message status is worked out from them. A message is FAILED only when every recipient failed, PARTIALLY_FAILED when some did, and DELIVERED only when every recipient was delivered — never while one of the people it was for did not get it. With a single recipient the message status is simply that recipient’s, so a one-address email behaves exactly as it always has.

• A bounce fails only the address it names. That recipient’s share is refunded; the others are untouched. A bounce on a shared email that does not say which address it is about is recorded as a BOUNCED event on the message, and fails and refunds no one, because guessing would be wrong for somebody.
• Addresses that do not exist are suppressed. When a live email is permanently refused because the mailbox does not exist or the address is invalid (enhanced status codes 5.1.1, 5.1.2, 5.1.3, 5.1.6, 5.1.10, 5.2.1), the address joins your suppression list with reason PROVIDER_REPORTED. Temporary failures, full mailboxes and policy blocks do not suppress, and neither does the sandbox.

The two message.recipient.* events fire only for an email with more than one recipient. For a single-recipient message the recipient’s fate is the message’s, and the message.* event already says it. The message-level event still fires whenever the overall status changes, so a handler that only understands message.* misses nothing.

• HTML email only. Plain-text email has nowhere to put an image, and SMS has no open signal at all — neither ever produces an OPENED event.
• First open only. A message has at most one OPENED event, at the first time its image was loaded. Later loads are mostly image-proxy caching and security scanners rather than people re-reading, so they are not counted.
• Opens are not a status and do not fire a webhook; read them from the events endpoint.
• Not in sandbox. Sandbox email never reaches a mailbox, so nobody can open it and no open is simulated.
• Per message, not per person, on a shared email. Everyone on a shared email receives the same content, including the same image, so an open says someone opened it — not who. Send separate emails with bulk email if you need to know which person opened.

• HTML email only. Links in plain-text email and SMS are sent exactly as you wrote them.
• Never rewritten: unsubscribe and opt-out links (by URL or link text), mailto:, tel:, in-page and relative links, and links inside HTML comments. Add data-infisend-notrack to any <a> to leave that link alone.
• Every click counts — unlike opens, a second click, or a click on a different link, is another event.
• Your stored message is unchanged. The rewriting happens as the email is sent; the message log shows your original links.
• Not in sandbox, for the same reason as opens.
• Per message on a shared email, for the same reason as opens: every recipient has the same links.

• Per message: deliveredAt, firstOpenedAt, openCount (0 or 1 — only the first open is recorded), clickCount and clickedLinks. Open and click figures are null for SMS, which has no such signal. Status changes still belong on your webhook — do not poll this.
• Account analytics: from (inclusive) and to (exclusive) ISO timestamps, default the last 30 days, at most 366; optional channel; environment defaults to LIVE. Figures cover messages created in the window.
• Definitions: delivery rate is delivered ÷ attempted. Email has no delivery receipt, so an email counts as delivered once the receiving server accepted it and it has not bounced. Open and click rates are messages with at least one open or click ÷ delivered email. Rates are percentage strings to two places, null when nothing was delivered.
• Every response carries caveats describing what its figures do not mean, so your own dashboards can show them too.

t=1755164487,v1=6c2f8b41d0…9a1b

1. Split the header on commas and read t and v1 by key, not by position — future schemes may append v2 pairs to the same header, and a parser that looks values up by name keeps working when they do.
2. Build the signed string as `${t}.${rawBody}` — the timestamp, a literal full stop, then the request body byte for byte.
3. HMAC-SHA-256 it with your endpoint’s whsec_… secret as UTF-8 bytes (no decoding step) and hex-encode lowercase.
4. Compare against v1 in constant time, and reject anything where t is more than 5 minutes from your clock.

The timestamp is inside the signed string on purpose. Signing the body alone would make a captured delivery replayable forever, since the payload is byte-identical each time; with t covered, the capture expires.

• 5 attempts with exponential backoff. After the last one the delivery is permanently failed and surfaced to you rather than disappearing quietly.
• Delivery is at-least-once and ordering is not guaranteed. Be idempotent on (messageId, status) for message events and on (recipientId, event) for recipient events, and ignore a status you have already advanced past.
• A resend replays the original payload verbatim — same messageId, same status, same occurredAt — under a fresh signature timestamp. You cannot use t to tell an original from a replay.
• Acknowledge fast. Return 200 and do the work afterwards; a handler that blocks on your own downstream call will time out and be retried.

• Variable values are strings. Every formatting choice — thousands separators, timezone, currency symbol — is one you have the context for. What you put in the variable is exactly what the recipient reads.
• Missing variables are a 400, not a blank in the message. A half-rendered SMS costs the same as a correct one.
• Rendering happens when the send is accepted, so editing a template does not change a scheduled message that already referenced it.
• An email template supplies both the subject and the body, which is why a templated email send carries neither.

The same log is available to API keys as GET /v1/messages, with the same parameters, so an integration can reconcile a bulk request by its batchId without a dashboard session. A key lists only messages in its own environment — a sandbox key never sees live traffic, whatever environment it asks for. Each row carries recipientCount and batchId; the recipients themselves are on the single-message read.

Every message row carries the correlation ID of the request that created it, so a line in your logs and a line in ours can be joined without a support conversation.

This is the endpoint to call before a bulk send, because the send itself is all-or-nothing: one unusable row rejects the entire batch. sufficientBalance answers whether a live send of this list would clear the upfront wallet check.

The document is generated from the API’s own controllers and the shared validation schemas, not maintained by hand — there is no second description of any payload in the codebase, which is what makes it worth generating a client from.