Messages

Send email, SMS and WhatsApp messages as your organization, use an idempotency key to retry within its documented retention limits, and see what became of each message, on its own or in a report.

A successful send normally answers 202 Accepted with its id and status. Acceptance is not provider delivery: sending requires enabled outbound delivery, running channel consumers and the channel's provider configuration. No delivery time is guaranteed. On deployments with outbound delivery disabled, an accepted request does not mean a message will be sent. Its id, msg_ followed by 32 hexadecimal characters, is how you read what became of it, here or in a webhook.

202 Accepted

{
  "status": "success",
  "data": { "id": "msg_4f9c2a1e8b7d4c3f9e0a1b2c3d4e5f60", "status": "queued" },
  "errors": null
}

POST/external/v1/messages/email

Send an email

An email goes from one of your organization's verified sender identities, with HTML of its own or made from one of your email templates.

  • Name
    to
    Type
    string[]
    Description

    Optional when cc or bcc supplies recipients. Supply 1 to 50 address entries across to, cc and bcc together; any one list may be absent or empty. An empty total is refused on to.

  • Name
    cc
    Type
    string[]
    Description

    Addresses for the Cc header. They receive the same email body as the other recipients.

  • Name
    bcc
    Type
    string[]
    Description

    Addresses for the Bcc delivery list. Bcc is not hidden from the sender's message records and webhooks.

  • Name
    from
    Type
    string
    Description

    A verified identity's address, or any address on a verified domain identity. Without it, the organization's verified Primary sender is required; there is no fallback to another verified identity. When Oblic sends for an identity, the visible From address is an alias on Oblic's configured sending domain rather than the identity's address.

  • Name
    fromName
    Type
    string
    Description

    The name it is sent as, at most 255 characters, without <, >, " or a line break. Without it, the identity's display name. Oblic adds via Oblic when it sends for the identity.

  • Name
    replyTo
    Type
    string
    Description

    The address replies go to. When Oblic sends for an identity, replies go to the original verified address unless replyTo overrides it.

  • Name
    subject
    Type
    string
    Description

    At most 1,023 characters. Required with html. With templateId, the template's subject is used when you give none.

  • Name
    html
    Type
    string
    Description

    The email's HTML, sent as you give it. Give html or templateId, never both.

  • Name
    text
    Type
    string
    Description

    A plain-text version, sent beside the HTML for mail clients that show text. With templateId, its {{name}} placeholders are filled from variables as written, never escaped.

  • Name
    templateId
    Type
    string
    Description

    The id of an email template to send, 18 ASCII letters and digits.

  • Name
    variables
    Type
    object
    Description

    With templateId, a value for each of the template's {{name}} placeholders: at most 100, each value a string of at most 10,000 characters. Names match whatever their case. A value is HTML-escaped where the HTML holds it, so text sent as <b> shows as <b>.

  • Name
    attachments
    Type
    object[]
    Description

    At most 10 files, each {"fileName": …, "content": …} with the file's bytes in base64, at most 10 MB together. Files such as ZIP archives, CSV and ICS can be accepted; SES-refused extensions and detected executable content are refused. Campaign uploads retain their separate allow-list.

  • Name
    metadata
    Type
    object
    Description

    Your own strings by key, such as your order or tenant id, answered with the message and every webhook of it, and never sent. See Metadata.

All three recipient lists receive the same body. To and Cc addresses are visible in recipient headers; Bcc addresses still appear in the sender's message list and webhooks. The ledger does not record a per-recipient To/Cc/Bcc role.

These lists require compatible API and Functions sender revisions. Activate the updated sender before or together with the API. Attachment scanning is a separate configured gate; acceptance does not prove a file was scanned or is free of malware.

An email of its own HTML

curl -X POST https://api.oblic.app/external/v1/messages/email \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1042-confirmation' \
  -d '{
    "from": "orders@example.com",
    "fromName": "Example Store",
    "to": ["asha@example.org"],
    "subject": "Your order is confirmed",
    "html": "<p>Thank you for your order.</p>"
  }'

An email made from a template

curl -X POST https://api.oblic.app/external/v1/messages/email \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": ["asha@example.org"],
    "templateId": "TEM000R7ZM4Q2VXH00",
    "text": "Hi {{first_name}}, your order {{order_id}} is confirmed.",
    "variables": { "first_name": "Asha", "order_id": "1042" }
  }'

Recipients who unsubscribed, or who are on the suppression list, are skipped: the message is skipped for them, and an email.suppressed webhook says why.

RefusedcdWhen
400the field, such as TO[0]A field is missing or not valid; an empty or oversized combined recipient set is refused on to
400INVALID_REQUESTNeither or both of html and templateId, variables without a template, or no subject
400INVALID_VARIABLESA placeholder has no value, a name is given twice in different cases, or the filled subject is too long
400INVALID FILEAn attachment is too large, or of a type that is not accepted
403EMAIL_SUSPENDEDThe account's email is suspended for its bounces or spam complaints, until Oblic's support lifts it
413MESSAGE_TOO_LARGEThe email is too large to queue
422UNVERIFIED_SENDERfrom is not a verified identity's; the message lists the verified ones
422TEMPLATE_NOT_FOUNDThere is no email template with that id
422TEMPLATE_HAS_MENTIONSThe template holds the dashboard's mentions, such as @unsubscribe, which only campaigns and automations fill
429RATE_LIMITEDOver the account's hourly limit (5,000 recipients by default), or its limit to one address (10 an hour by default); each send counts canonical distinct recipients across all three lists, so a repeated address in that send counts once. Retry-After says when
429QUOTA_EXCEEDEDOver the account's messages for the month (100,000 by default); Retry-After says when

With the reputation worker enabled, its configurable defaults review each account's own email over the last 7 days, once it has sent to 500 recipients: at 2% bounces or 0.05% spam complaints its owners are warned, and at 4% or 0.08% its email is suspended until Oblic's support lifts it. With those defaults, spam complaints are judged only once it has sent to 1,251 recipients, so a single complaint does not suspend an account. Only hard bounces count, and each recipient once. A paused or disabled worker does not perform that periodic review. While an account is suspended an email is refused with EMAIL_SUSPENDED, and one accepted before but not yet sent fails, with an email.failed event whose failureCode is EMAIL_SUSPENDED.


POST/external/v1/messages/sms

Send an SMS

An SMS goes to an Indian mobile number, and must match one of the DLT templates your account may send: the template's fixed text exactly, with each of its variables filled. Give the text, and Oblic finds the template; or give the template's DLT id and its variables.

  • Name
    to
    Type
    string
    Description

    Required: +91 and ten digits, the first 6 to 9. Spaces and dashes are ignored.

  • Name
    text
    Type
    string
    Description

    The message, at most 2,000 characters, as one of your templates with its variables filled: each variable 1 to 30 characters, on one line. Text with any character outside plain ASCII, such as é or ₹, matches only Unicode templates.

  • Name
    templateId
    Type
    string
    Description

    In place of text: the template's DLT id, up to 32 digits.

  • Name
    variables
    Type
    string[]
    Description

    With templateId: a value for each of the template's variables, in order, at most 30 values. Each is 1 to 30 characters on one line, and in plain ASCII unless the template is Unicode.

  • Name
    senderId
    Type
    string
    Description

    The DLT header to send from, at most 11 characters, which must be one of the template's. Without it, the account's default header is preferred.

  • Name
    purpose
    Type
    string
    Description

    otp, transactional (the default) or promotional. A promotional message matches only promotional templates, and the others only non-promotional ones.

  • Name
    unicode
    Type
    boolean
    Description

    true to consider Unicode templates only.

  • Name
    metadata
    Type
    object
    Description

    Your own strings by key, such as your order or tenant id, answered with the message and every webhook of it, and never sent. See Metadata.

An SMS

curl -X POST https://api.oblic.app/external/v1/messages/sms \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: login-7731' \
  -d '{
    "to": "+919812345678",
    "text": "Your Example code is 482913. It is valid for 10 minutes.",
    "purpose": "otp"
  }'

One segment holds up to 160 GSM-7 units; extension characters such as ^ count twice. A Unicode SMS instead holds up to 70 UTF-16 code units: a character outside the basic multilingual plane uses two. Longer messages use segments of 153 GSM-7 units or 67 UTF-16 code units. A promotional SMS goes only between 10:00 inclusive and 21:00 exclusive, India time. Sign-in codes, transactional and service SMS are not refused for an empty wallet.

RefusedcdWhen
400INVALID_NUMBERto is not an Indian mobile number
400INVALID_REQUESTNeither or both of text and templateId
400INVALID_VARIABLESThe variables don't fit the template
402INSUFFICIENT_BALANCEA promotional SMS, and the wallet that pays for the account is empty
422TEMPLATE_NOT_REGISTEREDThe text, or the templateId, matches none of the templates the account may send, or none under senderId
422SENDER_NOT_ALLOWEDsenderId is the header of no template the account may send
422MESSAGE_TYPE_NOT_ENABLEDThe template's type is not one Oblic sends: the types it sends are the account's messageTypes, by default service_implicit only
422URL_NOT_WHITELISTEDA variable holds a link whose domain is not whitelisted on DLT
422OUTSIDE_PROMOTIONAL_HOURSA promotional SMS outside 10:00 to 21:00 India time; Retry-After says when
429RATE_LIMITEDOver the account's hourly limit (1,000 messages by default), or its limit to one number (10 an hour by default); Retry-After says when
429QUOTA_EXCEEDEDOver the account's segments for the month (10,000 by default); Retry-After says when
503SMS_UNAVAILABLEThe SMS couldn't be queued just now, so retry with the same Idempotency-Key; or SMS is not set up on this Oblic

GET /external/v1/sms/account shows the account's limits, the template types Oblic sends, and what it has sent this month.


POST/external/v1/messages/whatsapp

Send a WhatsApp message

A WhatsApp message goes from your account's connected number: an approved template, or, within 24 hours of the person's last message to you, a reply of your own.

  • Name
    to
    Type
    string
    Description

    Required: the number in international format, such as +919812345678.

  • Name
    template
    Type
    string
    Description

    The name of one of your WhatsApp templates, as you created it. Give template or text, never both.

  • Name
    language
    Type
    string
    Description

    The template's language, such as en or hi; en by default.

  • Name
    variables
    Type
    string[]
    Description

    Values for the template's {{1}}, {{2}} and so on, in order: at most 30, each at most 1,024 characters.

  • Name
    headerVariables
    Type
    string[]
    Description

    Values for the variables of the template's text header, in order: at most 5, each at most 1,024 characters.

  • Name
    headerMediaUrl
    Type
    string
    Description

    The https link of the image, video or document the template's header sends, at most 2,048 characters. Without it, the header sends the media the template was approved with.

  • Name
    text
    Type
    string
    Description

    A reply of your own, at most 4,096 characters, which can go only within 24 hours of the person's last message to your number.

  • Name
    metadata
    Type
    object
    Description

    Your own strings by key, such as your order or tenant id, answered with the message and every webhook of it, and never sent. See Metadata.

A WhatsApp template

curl -X POST https://api.oblic.app/external/v1/messages/whatsapp \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "+919812345678",
    "template": "order_shipped",
    "language": "en",
    "variables": ["Asha", "1042"]
  }'

A template's header is filled as its body is. headerVariables fill a text header's variables, and headerMediaUrl gives a media header its image, video or document, or else it sends the one the template was approved with. A template that needs what the API can't send, a location header, a button with a value of its own or a named variable such as {{first_name}}, is refused before anything is sent or charged.

A template with an image header

curl -X POST https://api.oblic.app/external/v1/messages/whatsapp \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "+919812345678",
    "template": "diwali_sale",
    "headerMediaUrl": "https://cdn.example.com/diwali.jpg",
    "variables": ["20%"]
  }'

GET /external/v1/whatsapp/recipients/{number} says whether a number opted out of marketing, and until when a reply of your own can go.

RefusedcdWhen
400INVALID_REQUESTNeither or both of template and text, or headerVariables or headerMediaUrl with text
402INSUFFICIENT_BALANCEA marketing template, and the wallet that pays for the account is empty
422INVALID_NUMBERto is not a number in international format
422WHATSAPP_NOT_CONNECTEDThe account has no connected WhatsApp number
422TEMPLATE_NOT_FOUNDThe account has no template of that name in that language
422TEMPLATE_NOT_APPROVEDMeta has not approved the template
422INVALID_VARIABLESThe number of variables is not the template's, for its body or its text header; or headerVariables for a media header, or headerMediaUrl for a header that isn't one
422MEDIA_REQUIREDThe template's header is an image, a video or a document, and headerMediaUrl isn't an https link; or, without it, the media the template was approved with isn't one
422TEMPLATE_NOT_SENDABLEThe template needs what the API can't send: a location header, a button with a value of its own, or a named variable
422RECIPIENT_OPTED_OUTA marketing template to a number that opted out
422OUTSIDE_SESSION_WINDOWA reply of your own more than 24 hours after the person's last message

Retrying a send

Send an Idempotency-Key header with each send, 1 to 255 characters of your choosing, such as your own order or event id. If a send times out or you can't tell whether it was accepted, send it again with the same key and the same body. Deduplication depends on the retained key state, not a permanent guarantee against every repeated request:

  • The same send again answers 202 with the first message's id, and nothing is sent twice.
  • The same key with a different message, its metadata included, is refused, 409 IDEMPOTENCY_CONFLICT, and nothing is queued.
  • How long a key lasts: Email and WhatsApp key state is held in Redis for 24 hours; cache loss or expiry removes that deduplication state, and the same key can then send again. An SMS key has no time-based expiry in its stored message row: a later SMS needs a key of its own. These bounds do not guarantee delivery.
  • Keys are your organization's, one set per channel, so the same key can be used for an email and an SMS. Under X-Oblic-On-Behalf-Of, they are the sub-account's.
  • A retry is checked again before it is matched: an email whose sender stopped being verified, or a WhatsApp reply whose 24 hours have passed, is refused rather than answered with the first id.

A blank key, or one longer than 255 characters, is 400 INVALID_IDEMPOTENCY_KEY.

For email, nonempty cc and bcc lists are part of the idempotency hash, even if their addresses also occur in to. Missing or empty lists do not change the To-only hash shape; the retained-key and eligibility limits above still apply.


Metadata

Give any send metadata, your own strings by key, to find the message again in your own records: an order, a tenant, a campaign of yours. Oblic stores metadata and returns it in message responses and webhooks, but does not interpret it for delivery or forward it to recipients or providers. It does not redact secrets or sensitive values: validate what you put there; a permitted key name is not a privacy filter.

An SMS with metadata

{
  "to": "+919876543210",
  "text": "Your order 1042 has shipped.",
  "metadata": { "orderId": "1042", "tenant": "acme" }
}
  • Up to 20 keys, each 1 to 40 ASCII letters and digits, _, . or -, and each value a string of at most 500 characters. A number or true is kept as written, as the string "1042" or "true"; a null or an object is refused, 400, and nothing is queued.
  • It comes back in Get a message, in each entry of List messages, and as data.metadata in every webhook of the message: {} for a message sent without.
  • Part of the message: the same Idempotency-Key with other metadata is a different message, 409 IDEMPOTENCY_CONFLICT.

GET/external/v1/messages

List messages

The messages sent through the API, newest first, one entry for each recipient: an email to three addresses is three entries with the same id.

  • Name
    channel
    Type
    string
    Description

    email, sms or whatsapp; repeat it for several.

  • Name
    status
    Type
    string
    Description

    queued, sent, delivered, read, bounced, skipped or failed; repeat it for several.

  • Name
    since
    Type
    string
    Description

    The earliest time it was requested, inclusive, in ISO 8601 with Z or an explicit UTC offset, such as 2026-10-01T00:00:00Z. A local time without an offset is not an instant.

  • Name
    until
    Type
    string
    Description

    The latest time it was requested, exclusive, also with Z or an explicit UTC offset.

  • Name
    limit
    Type
    integer
    Description

    How many, from 1 to 100; 25 by default.

  • Name
    cursor
    Type
    string
    Description

    The last page's next, to read the page after it. See Pagination.

This week's skipped emails

curl -G https://api.oblic.app/external/v1/messages \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d channel=email \
  -d status=skipped \
  -d since=2026-10-19T00:00:00Z

Response

{
  "status": "success",
  "data": {
    "messages": [
      {
        "id": "msg_4f9c2a1e8b7d4c3f9e0a1b2c3d4e5f60",
        "channel": "email",
        "to": "ravi@example.org",
        "status": "skipped",
        "reason": "unsubscribed",
        "requestedAt": "2026-10-20T08:15:02.120Z",
        "sentAt": null,
        "deliveredAt": null,
        "readAt": null,
        "failedAt": null,
        "openedAt": null,
        "clickedAt": null,
        "metadata": { "orderId": "1042" }
      }
    ],
    "next": null
  },
  "errors": null
}
  • status is one set for every channel: queued (not yet sent), sent (the provider accepted it), delivered, read, bounced, skipped (not sent, as to an unsubscribed or suppressed address) and failed. reason says why, such as unsubscribed or suppressed for one skipped.
  • to is the email address, the SMS number with its +91, or the WhatsApp number's digits without +.
  • The times are when each happened, or null; openedAt and clickedAt are an email's.
  • metadata is what the message was sent with, or {}.

GET/external/v1/messages/{messageId}

Get a message

One message and what became of it, by the id its send answered with. An SMS and a WhatsApp message answer in much the same shape, an SMS with its segments and a WhatsApp message with its readAt, and an email in its own, with one entry for each recipient as its events arrive.

An SMS

{
  "status": "success",
  "data": {
    "id": "msg_9a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "channel": "sms",
    "status": "delivered",
    "segments": 1,
    "sentAt": "2026-10-20T08:15:03.410Z",
    "deliveredAt": "2026-10-20T08:15:06.902Z",
    "failedAt": null,
    "failureCode": null,
    "metadata": { "orderId": "1042" }
  },
  "errors": null
}

An email

{
  "status": "success",
  "data": {
    "id": "msg_4f9c2a1e8b7d4c3f9e0a1b2c3d4e5f60",
    "status": "sent",
    "recipients": [
      {
        "email": "asha@example.org",
        "deliveredAt": "2026-10-20T08:16:11Z",
        "openedAt": "2026-10-20T09:02:40Z",
        "bouncedAt": null,
        "complainedAt": null,
        "delayedAt": null
      }
    ],
    "metadata": {}
  },
  "errors": null
}
  • An SMS's status is queued, sent, delivered, undelivered or failed.
  • A WhatsApp message's is queued, sent, delivered, read or failed, with readAt. Its failureCode is Meta's, such as meta:131026.
  • An email's is queued until it is sent, then sent, partially_suppressed when some recipients were skipped, suppressed when every one was, or failed when it couldn't be sent. Each recipient's times come from the email provider's events, so recipients is empty until the first.
  • metadata is what it was sent with, or {}: see Metadata.

A message that isn't the account's, or isn't there, is 404 MESSAGE_NOT_FOUND. An email that was never sent reads as not found here after 24 hours; the list still shows it.


GET/external/v1/reports/summary

Report summary

What became of the messages requested in a period, counted by channel and status, with how many emails were opened, clicked or marked as spam.

  • Name
    from
    Type
    string
    Description

    The period's start, inclusive, in ISO 8601 with Z or an explicit UTC offset; 30 days before to by default.

  • Name
    to
    Type
    string
    Description

    The period's end, exclusive, also with Z or an explicit UTC offset; now by default. It must be after from, and at most 92 days after it.

Response

{
  "status": "success",
  "data": {
    "from": "2026-09-24T00:00:00Z",
    "to": "2026-10-24T00:00:00Z",
    "all": {
      "messages": 1250,
      "statuses": { "queued": 4, "sent": 96, "delivered": 1075, "read": 30, "bounced": 12, "skipped": 18, "failed": 15 },
      "opened": 410,
      "clicked": 96,
      "complained": 1
    },
    "channels": {
      "email": { "messages": 800, "statuses": { "queued": 2, "sent": 40, "delivered": 728, "read": 0, "bounced": 12, "skipped": 18, "failed": 0 }, "opened": 410, "clicked": 96, "complained": 1 },
      "sms": { "messages": 300, "statuses": { "queued": 1, "sent": 36, "delivered": 253, "read": 0, "bounced": 0, "skipped": 0, "failed": 10 }, "opened": 0, "clicked": 0, "complained": 0 },
      "whatsapp": { "messages": 150, "statuses": { "queued": 1, "sent": 20, "delivered": 94, "read": 30, "bounced": 0, "skipped": 0, "failed": 5 }, "opened": 0, "clicked": 0, "complained": 0 }
    }
  },
  "errors": null
}

Every channel and every status is always there, counted with the list's words. from at or after to, or more than 92 days apart, is 400 INVALID_PERIOD.

Was this page helpful?