API SMTP - Pesquisar E-mails

A API de pesquisa de e-mails da iPORTO permite consultar o histórico de envios realizados através do SMTP. Esta documentação apresenta todos os parâmetros de busca disponíveis para filtrar e localizar mensagens.

Endpoint

GET https://api.iporto.com.br/api/panel/application/delivery/smtp/history

Autenticação

A autenticação é realizada através de Bearer Token no header Authorization. Você pode gerar seu token de API no painel de controle da iPORTO.

Headers Necessários

Header	Valor	Descrição
`Accept`	`application/json`	Formato da resposta esperada
`Authorization`	`Bearer {SEU_TOKEN_JWT_AQUI}`	Token de autenticação da API

Parâmetros de Busca

Todos os parâmetros são opcionais e podem ser combinados para refinar sua pesquisa.

Paginação

Parâmetro	Tipo	Padrão	Descrição
`per_page`	integer	`10`	Número de registros por página
`page`	integer	`1`	Número da página atual

Filtros de Aplicação

Parâmetro	Tipo	Descrição
`customer_application_smtp_id`	integer	ID do aplicativo SMTP
`customer_application_smtp_account_id`	integer	ID da conta de autenticação SMTP

Filtros de Mensagem

Parâmetro	Tipo	Descrição
`message_tracking_code`	string	Código de rastreamento da mensagem
`message_id`	string	ID único da mensagem
`message_id_relay`	string	ID relay da mensagem no servidor
`address_to`	string	Endereço de e-mail do destinatário

Filtros de Status de Entrega

Parâmetro	Tipo	Valores	Descrição
`delivery_status`	string	Ex: `msg:yes:delivery`, `msg:not:delivery`, `msg:yes:finished:with:bounce`	Status de entrega da mensagem
`delivery_sum_hard_bounce`	integer	`0` ou `1`	Filtrar apenas mensagens com hard bounce (use `1` para buscar)
`delivery_sum_soft_bounce`	integer	`0` ou `1`	Filtrar apenas mensagens com soft bounce (use `1` para buscar)

Filtros de Tags e Datas

Parâmetro	Tipo	Formato	Descrição
`message_headers_tag`	string	Separado por vírgula	Tags associadas à mensagem (ex: `newsletter,marketing`)
`start_at`	string	`YYYY-MM-DD HH:mm:ss`	Data/hora inicial do período de busca
`until_at`	string	`YYYY-MM-DD HH:mm:ss`	Data/hora final do período de busca

Exemplo Completo

cURL

curl --location 'https://api.iporto.com.br/api/panel/application/delivery/smtp/history?per_page=10&page=1&customer_application_smtp_id=&customer_application_smtp_account_id=&start_at=2025-09-09%2019%3A23%3A05&until_at=2025-12-08%2019%3A23%3A05&message_id=&address_to=&delivery_status=&delivery_sum_soft_bounce=0&delivery_sum_hard_bounce=0' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer SEU_TOKEN_JWT_AQUI'

PHP

<?php

$curl = curl_init();

$queryParams = http_build_query([
    'per_page' => 10,
    'page' => 1,
    'start_at' => '2025-09-09 19:23:05',
    'until_at' => '2025-12-08 19:23:05',
    'address_to' => 'destinatario@exemplo.com',
    'delivery_status' => 'msg:yes:delivery'
]);

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.iporto.com.br/api/panel/application/delivery/smtp/history?' . $queryParams,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Accept: application/json',
    'Authorization: Bearer SEU_TOKEN_JWT_AQUI'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Python

import requests

url = "https://api.iporto.com.br/api/panel/application/delivery/smtp/history"

headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer SEU_TOKEN_JWT_AQUI'
}

params = {
  'per_page': 10,
  'page': 1,
  'start_at': '2025-09-09 19:23:05',
  'until_at': '2025-12-08 19:23:05',
  'address_to': 'destinatario@exemplo.com',
  'delivery_status': 'msg:yes:delivery'
}

response = requests.get(url, headers=headers, params=params)

print(response.text)

JavaScript (Node.js)

const axios = require('axios');

const params = {
  per_page: 10,
  page: 1,
  start_at: '2025-09-09 19:23:05',
  until_at: '2025-12-08 19:23:05',
  address_to: 'destinatario@exemplo.com',
  delivery_status: 'msg:yes:delivery'
};

const config = {
  method: 'get',
  url: 'https://api.iporto.com.br/api/panel/application/delivery/smtp/history',
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer SEU_TOKEN_JWT_AQUI'
  },
  params: params
};

axios(config)
  .then(function (response) {
    console.log(JSON.stringify(response.data));
  })
  .catch(function (error) {
    console.log(error);
  });

Exemplos de Busca

Buscar todos os e-mails enviados hoje

curl --location 'https://api.iporto.com.br/api/panel/application/delivery/smtp/history?start_at=2025-12-08%2000%3A00%3A00&until_at=2025-12-08%2023%3A59%3A59' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer SEU_TOKEN_JWT_AQUI'

Buscar e-mails com hard bounce

curl --location 'https://api.iporto.com.br/api/panel/application/delivery/smtp/history?delivery_sum_hard_bounce=1' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer SEU_TOKEN_JWT_AQUI'

Buscar e-mails enviados para um destinatário específico

curl --location 'https://api.iporto.com.br/api/panel/application/delivery/smtp/history?address_to=destinatario@exemplo.com' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer SEU_TOKEN_JWT_AQUI'

Buscar e-mails por tag

curl --location 'https://api.iporto.com.br/api/panel/application/delivery/smtp/history?message_headers_tag=newsletter,marketing' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer SEU_TOKEN_JWT_AQUI'

Buscar e-mails por Message ID

curl --location 'https://api.iporto.com.br/api/panel/application/delivery/smtp/history?message_id=abc123xyz' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer SEU_TOKEN_JWT_AQUI'

Resposta da API

Resposta de Sucesso (200 OK)

{
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 12345,
        "customer_id": 1,
        "customer_application_smtp_id": 10,
        "customer_application_smtp_account_id": 5,
        "message_id": "abc123xyz",
        "message_id_relay": "relay-abc123",
        "message_tracking_code": "track-code-123",
        "address_to_recipients": ["destinatario@exemplo.com"],
        "delivery_status": "msg:yes:delivery",
        "delivery_sum_hard_bounce": 0,
        "delivery_sum_soft_bounce": 0,
        "message_headers_tag": ["newsletter", "marketing"],
        "created_at": "2025-12-08T15:30:00.000000Z",
        "updated_at": "2025-12-08T15:30:05.000000Z"
      }
    ],
    "first_page_url": "https://api.iporto.com.br/api/panel/application/delivery/smtp/history?page=1",
    "from": 1,
    "last_page": 10,
    "last_page_url": "https://api.iporto.com.br/api/panel/application/delivery/smtp/history?page=10",
    "next_page_url": "https://api.iporto.com.br/api/panel/application/delivery/smtp/history?page=2",
    "path": "https://api.iporto.com.br/api/panel/application/delivery/smtp/history",
    "per_page": 10,
    "prev_page_url": null,
    "to": 10,
    "total": -1
  }
}

Campos da Resposta

Campo	Tipo	Descrição
`id`	integer	ID único do registro de envio
`customer_id`	integer	ID do cliente
`customer_application_smtp_id`	integer	ID do aplicativo SMTP utilizado
`customer_application_smtp_account_id`	integer	ID da conta de autenticação utilizada
`message_id`	string	ID único da mensagem
`message_id_relay`	string	ID relay no servidor
`message_tracking_code`	string	Código de rastreamento
`address_to_recipients`	array	Lista de destinatários
`delivery_status`	string	Status da entrega
`delivery_sum_hard_bounce`	integer	Número de hard bounces
`delivery_sum_soft_bounce`	integer	Número de soft bounces
`message_headers_tag`	array	Tags associadas
`created_at`	string	Data/hora de criação
`updated_at`	string	Data/hora da última atualização

Resposta de Erro de Autenticação (401 Unauthorized)

{
  "message": "Unauthenticated."
}

Códigos de Status HTTP

Código	Descrição
`200`	Requisição bem-sucedida
`401`	Token de autenticação inválido ou ausente
`403`	Acesso negado
`422`	Parâmetros inválidos
`429`	Muitas requisições (limite de taxa excedido)
`500`	Erro interno do servidor

Status de Entrega

Os possíveis valores para o campo delivery_status incluem:

Status	Descrição
`msg:yes:delivery`	Mensagem entregue com sucesso ao destinatário
`msg:not:delivery`	Mensagem não foi entregue ao destinatário
`msg:not:accepted`	Mensagem não foi aceita pelo servidor de destino
`msg:yes:finished:with:bounce`	Mensagem finalizada com bounce (retorno)

Tipos de Bounce

Hard Bounce

Indica um erro permanente na entrega. Exemplos:

Endereço de e-mail não existe
Domínio inválido
Caixa de entrada desativada

Soft Bounce

Indica um erro temporário na entrega. Exemplos:

Caixa de entrada cheia
Servidor temporariamente indisponível
Mensagem muito grande

Boas Práticas

Use paginação para não sobrecarregar a API e melhorar a performance
Especifique períodos de data para buscas mais rápidas e eficientes
Combine filtros para refinar suas pesquisas e encontrar exatamente o que precisa
Cache os resultados quando apropriado para reduzir chamadas à API
Monitore hard bounces para manter sua lista de e-mails limpa
Use tags para facilitar a organização e busca de mensagens

Limites e Cache

A API utiliza cache interno para melhorar a performance
Cache de 1 minuto para primeira página
Cache de 5 minutos para páginas subsequentes
Taxa de requisições: Consulte seu plano no painel de controle
Resultado de -1 no campo total indica que o total não foi calculado (otimização de performance)

Exemplos de Uso Avançado

Monitorar bounces em um período

curl --location 'https://api.iporto.com.br/api/panel/application/delivery/smtp/history?start_at=2025-12-01%2000%3A00%3A00&until_at=2025-12-08%2023%3A59%3A59&delivery_sum_hard_bounce=1&per_page=50' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer SEU_TOKEN_JWT_AQUI'

Buscar mensagens de uma campanha específica por tag

curl --location 'https://api.iporto.com.br/api/panel/application/delivery/smtp/history?message_headers_tag=black-friday-2025&start_at=2025-11-25%2000%3A00%3A00&until_at=2025-11-30%2023%3A59%3A59&per_page=100' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer SEU_TOKEN_JWT_AQUI'

Verificar entregas bem-sucedidas de uma conta específica

curl --location 'https://api.iporto.com.br/api/panel/application/delivery/smtp/history?customer_application_smtp_account_id=5&delivery_status=msg:yes:delivery&per_page=100' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer SEU_TOKEN_JWT_AQUI'

Suporte

Para dúvidas ou problemas com a API, entre em contato com o suporte da iPORTO através do painel de controle ou visite https://iporto.com.br.

Nesta página

Progresso de leitura 0%

Ações rápidas

iPORTO

Confirma nossas opções de planos e saiba como podemos ajudar a escalar sua operação com automações inteligentes.

Saiba mais

Versão v3.0

Atalhos de teclado

Buscar Ctrl+K

Alternar tema T

Voltar ao topo Home