Mensagens da API

Envie e-mails, SMS e mensagens de WhatsApp pela sua organização, use uma chave de idempotência para repetir solicitações dentro dos limites de retenção documentados e consulte o resultado de cada mensagem, individualmente ou em um relatório.

Um envio bem-sucedido normalmente responde 202 Accepted com seu identificador e estado. Aceitação não é entrega pelo provedor: o envio exige entrega de saída habilitada, consumidores do canal em execução e a configuração do provedor desse canal. Não há prazo de entrega garantido. Em implantações com entrega de saída desabilitada, aceitar a solicitação não significa que uma mensagem será enviada. Seu identificador, msg_ seguido de 32 caracteres hexadecimais, permite consultar o resultado aqui ou em um webhook.

202 Aceito

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

POST/external/v1/messages/email

Enviar um e-mail

Um e-mail parte de uma das identidades de remetente verificadas da sua organização, com HTML próprio ou gerado por um dos seus modelos de e-mail.

  • Nome
    to
    Tipo
    string[]
    Descrição

    Opcional quando cc ou bcc fornece destinatários. Informe de 1 a 50 entradas de endereço no total entre to, cc e bcc; qualquer lista individual pode estar ausente ou vazia. Um total vazio é recusado em to.

  • Nome
    cc
    Tipo
    string[]
    Descrição

    Endereços do cabeçalho Cc. Eles recebem o mesmo conteúdo de email que os demais destinatários.

  • Nome
    bcc
    Tipo
    string[]
    Descrição

    Endereços da lista de entrega Bcc. Bcc não fica oculto nos registros de mensagens nem nos webhooks do remetente.

  • Nome
    from
    Tipo
    string
    Descrição

    O endereço de uma identidade verificada ou qualquer endereço em uma identidade de domínio verificada. Se omitido, é necessário o remetente principal verificado da organização; não há seleção alternativa de outra identidade verificada. Quando a Oblic envia por uma identidade, o endereço De visível é um alias no domínio de envio configurado da Oblic, não o endereço da identidade.

  • Nome
    fromName
    Tipo
    string
    Descrição

    O nome do remetente, com até 255 caracteres, sem <, >, " ou quebra de linha. Se omitido, usa-se o nome de exibição da identidade. A Oblic acrescenta via Oblic quando envia por essa identidade.

  • Nome
    replyTo
    Tipo
    string
    Descrição

    O endereço que recebe as respostas. Quando a Oblic envia por uma identidade, as respostas vão para o endereço original verificado, a menos que replyTo o substitua.

  • Nome
    subject
    Tipo
    string
    Descrição

    Até 1,023 caracteres. Obrigatório com html. Com templateId, usa-se o assunto do modelo quando nenhum é informado.

  • Nome
    html
    Tipo
    string
    Descrição

    O HTML do e-mail, enviado como fornecido. Informe html ou templateId, nunca ambos.

  • Nome
    text
    Tipo
    string
    Descrição

    Uma versão em texto simples, enviada junto com o HTML para clientes que exibem texto. Com templateId, seus marcadores {{name}} são preenchidos com variables como escritos, sem escape.

  • Nome
    templateId
    Tipo
    string
    Descrição

    O identificador do modelo de e-mail a enviar, com 18 letras e dígitos ASCII.

  • Nome
    variables
    Tipo
    object
    Descrição

    Com templateId, um valor para cada marcador {{name}} do modelo: no máximo 100, cada valor uma string de até 10,000 caracteres. Os nomes correspondem sem distinguir maiúsculas de minúsculas. O valor recebe escape HTML onde aparece no HTML, de modo que o texto enviado como <b> é exibido como <b>.

  • Nome
    attachments
    Tipo
    object[]
    Descrição

    No máximo 10 arquivos, cada um como {"fileName": …, "content": …} com os bytes em base64, somando no máximo 10 MB. Arquivos como ZIP, CSV e ICS podem ser aceitos; extensões recusadas pelo SES e conteúdo executável detectado são recusados. Os uploads de campanhas mantêm sua lista de permissões separada.

  • Nome
    metadata
    Tipo
    object
    Descrição

    Suas próprias strings por chave, como o identificador do pedido ou do tenant, retornadas com a mensagem e cada webhook dela, mas nunca enviadas. Consulte Metadados.

As três listas de destinatários recebem o mesmo conteúdo. Os endereços To e Cc ficam visíveis nos cabeçalhos dos destinatários; os endereços Bcc continuam aparecendo na lista de mensagens e nos webhooks do remetente. O registro não armazena um papel To/Cc/Bcc por destinatário.

Essas listas exigem versões compatíveis da API e do remetente Functions. Ative o remetente atualizado antes da API ou junto com ela. A verificação de anexos é uma etapa configurada separadamente; a aceitação não comprova que um arquivo foi verificado nem que está livre de malware.

Um e-mail com HTML próprio

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>"
  }'

Um e-mail a partir de um modelo

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" }
  }'

Destinatários que cancelaram a inscrição ou estão na lista de supressão são ignorados: a mensagem fica como skipped para eles, e uma notificação email.suppressed por webhook informa o motivo.

RecusacdCondição
400o campo, como TO[0]Um campo está ausente ou é inválido; um conjunto combinado de destinatários vazio ou acima do limite é recusado em to
400INVALID_REQUESTNão foi informado nenhum entre html e templateId, ou ambos foram informados; há variables sem modelo ou falta o assunto
400INVALID_VARIABLESUm marcador não tem valor, um nome aparece duas vezes com capitalização diferente ou o assunto preenchido é longo demais
400INVALID FILEUm anexo é grande demais ou de um tipo não aceito
403EMAIL_SUSPENDEDO envio de e-mails da conta está suspenso por devoluções ou denúncias de spam, até a liberação pelo suporte da Oblic
413MESSAGE_TOO_LARGEO e-mail é grande demais para entrar na fila
422UNVERIFIED_SENDERfrom não pertence a uma identidade verificada; a mensagem lista as identidades verificadas
422TEMPLATE_NOT_FOUNDNão existe modelo de e-mail com esse identificador
422TEMPLATE_HAS_MENTIONSO modelo contém menções do painel, como @unsubscribe, que somente campanhas e automações preenchem
429RATE_LIMITEDAcima do limite por hora da conta (5,000 destinatários por padrão) ou do limite para um endereço (10 por hora por padrão); cada envio conta destinatários distintos normalizados entre as três listas, portanto um endereço repetido naquele envio conta uma vez. Retry-After informa quando
429QUOTA_EXCEEDEDO limite mensal de mensagens da conta foi excedido (100,000 por padrão); Retry-After informa quando tentar novamente

Com o worker de reputação habilitado, seus padrões configuráveis avaliam os e-mails de cada conta nos últimos 7 dias após o envio a 500 destinatários: com 2% de devoluções ou 0.05% de denúncias de spam, os proprietários são avisados; com 4% ou 0.08%, o envio de e-mails é suspenso até a liberação pelo suporte da Oblic. Nesses padrões, denúncias de spam só são avaliadas após o envio a 1,251 destinatários; uma única denúncia, portanto, não suspende a conta. Somente devoluções permanentes contam, uma vez por destinatário. Um worker pausado ou desabilitado não realiza essa avaliação periódica. Enquanto a conta está suspensa, um e-mail é recusado com EMAIL_SUSPENDED; um já aceito, mas ainda não enviado, falha com um evento email.failed cujo failureCode é EMAIL_SUSPENDED.


POST/external/v1/messages/sms

Enviar um SMS

Um SMS é enviado a um celular indiano e deve corresponder a um dos modelos DLT permitidos para a conta: o texto fixo deve ser idêntico ao do modelo e todas as variáveis devem estar preenchidas. Informe o texto para a Oblic encontrar o modelo ou informe o identificador DLT do modelo e suas variáveis.

  • Nome
    to
    Tipo
    string
    Descrição

    Obrigatório: +91 e dez dígitos, com o primeiro entre 6 e 9. Espaços e hífens são ignorados.

  • Nome
    text
    Tipo
    string
    Descrição

    A mensagem, com até 2,000 caracteres, deve corresponder a um dos seus modelos com as variáveis preenchidas: cada variável tem de 1 a 30 caracteres em uma linha. Texto com qualquer caractere fora do ASCII simples, como é ou ₹, corresponde somente a modelos Unicode.

  • Nome
    templateId
    Tipo
    string
    Descrição

    No lugar de text: o identificador DLT do modelo, com até 32 dígitos.

  • Nome
    variables
    Tipo
    string[]
    Descrição

    Com templateId: um valor para cada variável do modelo, na ordem, até 30 valores. Cada valor tem de 1 a 30 caracteres em uma linha, em ASCII simples, a menos que o modelo seja Unicode.

  • Nome
    senderId
    Tipo
    string
    Descrição

    O cabeçalho DLT do remetente, com até 11 caracteres, que deve ser um dos cabeçalhos do modelo. Se omitido, prefere-se o cabeçalho padrão da conta.

  • Nome
    purpose
    Tipo
    string
    Descrição

    otp, transactional (padrão) ou promotional. Uma mensagem promocional corresponde somente a modelos promocionais, e as demais somente a modelos não promocionais.

  • Nome
    unicode
    Tipo
    boolean
    Descrição

    true para considerar somente modelos Unicode.

  • Nome
    metadata
    Tipo
    object
    Descrição

    Suas próprias strings por chave, como o identificador do pedido ou do tenant, retornadas com a mensagem e cada webhook dela, mas nunca enviadas. Consulte Metadados.

Uma mensagem 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"
  }'

Um segmento comporta até 160 unidades GSM-7; caracteres de extensão como ^ contam duas vezes. Um SMS Unicode comporta até 70 unidades de código UTF-16: um caractere fora do plano multilíngue básico usa duas. Mensagens maiores usam segmentos de 153 unidades GSM-7 ou 67 unidades de código UTF-16. Um SMS promocional só é enviado entre 10:00 inclusive e 21:00 exclusive, no horário da Índia. Códigos de acesso, SMS transacionais e de serviço não são recusados por carteira vazia.

RecusacdCondição
400INVALID_NUMBERto não é um número de celular indiano
400INVALID_REQUESTNão foi informado nenhum entre text e templateId, ou ambos foram informados
400INVALID_VARIABLESAs variáveis não correspondem ao modelo
402INSUFFICIENT_BALANCEO SMS é promocional e a carteira que paga pela conta está vazia
422TEMPLATE_NOT_REGISTEREDO texto ou o templateId não corresponde a nenhum modelo permitido para a conta, ou a nenhum sob senderId
422SENDER_NOT_ALLOWEDsenderId não é o cabeçalho de nenhum modelo permitido para a conta
422MESSAGE_TYPE_NOT_ENABLEDO tipo do modelo não é enviado pela Oblic: os tipos enviados são os messageTypes da conta, por padrão apenas service_implicit
422URL_NOT_WHITELISTEDUma variável contém um link cujo domínio não está na lista permitida do DLT
422OUTSIDE_PROMOTIONAL_HOURSUm SMS promocional fora do intervalo de 10:00 a 21:00 no horário da Índia; Retry-After informa quando tentar novamente
429RATE_LIMITEDO limite horário da conta foi excedido (1,000 mensagens por padrão), ou o limite para um número (10 por hora por padrão); Retry-After informa quando tentar novamente
429QUOTA_EXCEEDEDO limite mensal de segmentos da conta foi excedido (10,000 por padrão); Retry-After informa quando tentar novamente
503SMS_UNAVAILABLENão foi possível enfileirar o SMS agora; tente novamente com a mesma Idempotency-Key; ou o SMS não está configurado nesta instalação da Oblic

GET /external/v1/sms/account mostra os limites da conta, os tipos de modelo enviados pela Oblic e o que foi enviado neste mês.


POST/external/v1/messages/whatsapp

Enviar uma mensagem de WhatsApp

Uma mensagem de WhatsApp parte do número conectado à conta: um modelo aprovado ou, nas 24 horas após a última mensagem da pessoa, uma resposta livre.

  • Nome
    to
    Tipo
    string
    Descrição

    Obrigatório: o número em formato internacional, como +919812345678.

  • Nome
    template
    Tipo
    string
    Descrição

    O nome de um dos seus modelos de WhatsApp, tal como criado. Informe template ou text, nunca ambos.

  • Nome
    language
    Tipo
    string
    Descrição

    O idioma do modelo, como en ou hi; en por padrão.

  • Nome
    variables
    Tipo
    string[]
    Descrição

    Valores para {{1}}, {{2}} e os demais marcadores do modelo, na ordem: no máximo 30, cada um com até 1,024 caracteres.

  • Nome
    headerVariables
    Tipo
    string[]
    Descrição

    Valores para as variáveis do cabeçalho de texto do modelo, na ordem: no máximo 5, cada um com até 1,024 caracteres.

  • Nome
    headerMediaUrl
    Tipo
    string
    Descrição

    O link https da imagem, do vídeo ou do documento enviado no cabeçalho do modelo, com até 2,048 caracteres. Se omitido, o cabeçalho envia a mídia com a qual o modelo foi aprovado.

  • Nome
    text
    Tipo
    string
    Descrição

    Uma resposta livre, com até 4,096 caracteres, que só pode ser enviada nas 24 horas após a última mensagem da pessoa para o seu número.

  • Nome
    metadata
    Tipo
    object
    Descrição

    Suas próprias strings por chave, como o identificador do pedido ou do tenant, retornadas com a mensagem e cada webhook dela, mas nunca enviadas. Consulte Metadados.

Um modelo de WhatsApp

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"]
  }'

O cabeçalho de um modelo é preenchido como o corpo. headerVariables preenche variáveis de um cabeçalho de texto, e headerMediaUrl fornece a imagem, o vídeo ou o documento de um cabeçalho de mídia; sem ele, usa-se a mídia aprovada com o modelo. Um modelo que exige algo que a API não pode enviar, como cabeçalho de localização, botão com valor próprio ou variável nomeada como {{first_name}}, é recusado antes de qualquer envio ou cobrança.

Um modelo com imagem no cabeçalho

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} informa se um número recusou marketing e até quando uma resposta livre pode ser enviada.

RecusacdCondição
400INVALID_REQUESTNão foi informado nenhum entre template e text, ou ambos foram informados, ou há headerVariables ou headerMediaUrl com text
402INSUFFICIENT_BALANCEO modelo é de marketing e a carteira que paga pela conta está vazia
422INVALID_NUMBERto não é um número em formato internacional
422WHATSAPP_NOT_CONNECTEDA conta não tem número de WhatsApp conectado
422TEMPLATE_NOT_FOUNDA conta não tem modelo com esse nome nesse idioma
422TEMPLATE_NOT_APPROVEDA Meta não aprovou o modelo
422INVALID_VARIABLESA quantidade de variáveis não corresponde ao corpo ou cabeçalho de texto do modelo; ou há headerVariables para um cabeçalho de mídia, ou headerMediaUrl para um cabeçalho que não é de mídia
422MEDIA_REQUIREDO cabeçalho do modelo é imagem, vídeo ou documento, e headerMediaUrl não é um link https; ou, se omitido, a mídia aprovada com o modelo também não tem link https
422TEMPLATE_NOT_SENDABLEO modelo exige algo que a API não pode enviar: cabeçalho de localização, botão com valor próprio ou variável nomeada
422RECIPIENT_OPTED_OUTUm modelo de marketing para um número que recusou esse tipo de mensagem
422OUTSIDE_SESSION_WINDOWUma resposta livre mais de 24 horas após a última mensagem da pessoa

Repetir um envio

Envie um cabeçalho Idempotency-Key em cada envio, com 1 a 255 caracteres de sua escolha, como o identificador do pedido ou evento. Se ocorrer timeout ou você não souber se o envio foi aceito, repita com a mesma chave e o mesmo corpo. A deduplicação depende do estado retido da chave, não de uma garantia permanente contra toda solicitação repetida:

  • Repetir o mesmo envio responde 202 com o identificador da primeira mensagem, sem enviar nada duas vezes.
  • A mesma chave com outra mensagem, incluindo seus metadata, é recusada com 409 IDEMPOTENCY_CONFLICT, sem enfileirar nada.
  • Duração da chave: o estado das chaves de e-mail e WhatsApp é mantido no Redis por 24 horas; perda ou expiração do cache elimina esse estado de deduplicação, e a mesma chave pode então enviar novamente. Uma chave SMS não expira por tempo na linha armazenada da mensagem: um SMS posterior precisa de sua própria chave. Esses limites não garantem entrega.
  • As chaves pertencem à sua organização, com um conjunto por canal; a mesma chave pode ser usada para um e-mail e um SMS. Sob X-Oblic-On-Behalf-Of, pertencem à subconta.
  • Uma repetição é validada novamente antes da correspondência: um e-mail cujo remetente deixou de ser verificado, ou uma resposta de WhatsApp cujas 24 horas passaram, é recusado em vez de retornar o primeiro identificador.

Uma chave vazia ou com mais de 255 caracteres resulta em 400 INVALID_IDEMPOTENCY_KEY.

No email, as listas cc e bcc não vazias fazem parte do hash de idempotência, mesmo que seus endereços também estejam em to. Listas ausentes ou vazias não mudam a estrutura do hash de solicitações apenas To; os limites de retenção de chave e de elegibilidade acima continuam valendo.


Metadados

Inclua metadata em qualquer envio, suas próprias strings por chave, para localizar a mensagem nos seus registros: um pedido, tenant ou campanha. A Oblic armazena os metadados e os retorna nas respostas de mensagens e nos webhooks, mas não os interpreta para entrega nem os encaminha a destinatários ou provedores. Não remove segredos ou dados sensíveis: valide o que inserir; um nome de chave permitido não é um filtro de privacidade.

Um SMS com metadados

{
  "to": "+919876543210",
  "text": "Your order 1042 has shipped.",
  "metadata": { "orderId": "1042", "tenant": "acme" }
}
  • Até 20 chaves, cada uma com 1 a 40 letras e dígitos ASCII, _, . ou -, e cada valor uma string de até 500 caracteres. Um número ou true é preservado como escrito, como string "1042" ou "true"; null ou objeto é recusado com 400, sem enfileirar nada.
  • Eles retornam em Obter uma mensagem, em cada entrada de Listar mensagens e como data.metadata em todo webhook da mensagem: {} para uma mensagem enviada sem metadados.
  • São parte da mensagem: a mesma Idempotency-Key com outros metadados é outra mensagem e resulta em 409 IDEMPOTENCY_CONFLICT.

GET/external/v1/messages

Listar mensagens

As mensagens enviadas pela API, da mais recente para a mais antiga, com uma entrada por destinatário: um e-mail para três endereços gera três entradas com o mesmo id.

  • Nome
    channel
    Tipo
    string
    Descrição

    email, sms ou whatsapp; repita o parâmetro para vários valores.

  • Nome
    status
    Tipo
    string
    Descrição

    queued, sent, delivered, read, bounced, skipped ou failed; repita o parâmetro para vários valores.

  • Nome
    since
    Tipo
    string
    Descrição

    O instante inicial da solicitação, inclusive, em ISO 8601 com Z ou deslocamento UTC explícito, como 2026-10-01T00:00:00Z. Uma hora local sem deslocamento não identifica um instante.

  • Nome
    until
    Tipo
    string
    Descrição

    O instante final da solicitação, exclusive, também com Z ou deslocamento UTC explícito.

  • Nome
    limit
    Tipo
    integer
    Descrição

    A quantidade, de 1 a 100; 25 por padrão.

  • Nome
    cursor
    Tipo
    string
    Descrição

    O next da última página, para ler a seguinte. Consulte Paginação.

E-mails ignorados nesta semana

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

Resposta

{
  "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 usa o mesmo conjunto em todos os canais: queued (ainda não enviado), sent (aceito pelo provedor), delivered, read, bounced, skipped (não enviado, por exemplo para endereço com inscrição cancelada ou suprimido) e failed. reason informa o motivo, como unsubscribed ou suppressed para uma mensagem ignorada.
  • to é o endereço de e-mail, o número SMS com +91 ou os dígitos do número de WhatsApp sem +.
  • Os horários indicam quando cada evento ocorreu, ou null; openedAt e clickedAt são do e-mail.
  • metadata contém o que foi associado à mensagem no envio, ou {}.

GET/external/v1/messages/{messageId}

Obter uma mensagem

Uma mensagem e seu resultado, pelo identificador retornado no envio. Um SMS e uma mensagem de WhatsApp têm respostas de formato semelhante, com segments no SMS e readAt no WhatsApp; um e-mail usa formato próprio, com uma entrada por destinatário conforme chegam seus eventos.

Uma mensagem 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
}

Um e-mail

{
  "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
}
  • O status de um SMS é queued, sent, delivered, undelivered ou failed.
  • O de uma mensagem de WhatsApp é queued, sent, delivered, read ou failed, com readAt. Seu failureCode é o da Meta, como meta:131026.
  • O de um e-mail é queued até o envio, depois sent, partially_suppressed quando alguns destinatários foram ignorados, suppressed quando todos foram, ou failed quando o envio falhou. Os horários de cada destinatário vêm dos eventos do provedor de e-mail, então recipients fica vazio até o primeiro evento.
  • metadata contém o que foi associado no envio, ou {}: consulte Metadados.

Uma mensagem que não pertence à conta ou não existe retorna 404 MESSAGE_NOT_FOUND. Um e-mail nunca enviado passa a não ser encontrado aqui após 24 horas; a lista continua a exibi-lo.


GET/external/v1/reports/summary

Resumo do relatório

O resultado das mensagens solicitadas em um período, contado por canal e estado, com quantas mensagens de e-mail foram abertas, clicadas ou marcadas como spam.

  • Nome
    from
    Tipo
    string
    Descrição

    O início do período, inclusive, em ISO 8601 com Z ou deslocamento UTC explícito; por padrão, 30 dias antes de to.

  • Nome
    to
    Tipo
    string
    Descrição

    O fim do período, exclusive, também com Z ou deslocamento UTC explícito; por padrão, agora. Deve ser posterior a from e estar a no máximo 92 dias dele.

Resposta

{
  "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
}

Todos os canais e estados estão sempre presentes, contados com os termos da lista. from igual ou posterior a to, ou um intervalo maior que 92 dias, resulta em 400 INVALID_PERIOD.

Esta página foi útil?