API SMS Mailpro™ : Referência

POST /token

Obter token de acesso (redireccionamento 307 para /v3/token)

Obtém um token JWT Bearer utilizando as credenciais do cliente Mailpro. Envie o access_token devolvido como Authorization: Bearer <token> em todos os pedidos subsequentes. O mesmo token é igualmente válido na API CRM v3 e na API Email v2.

> ⚙ Detalhe de implementação — POST /sms/token é um redireccionamento > temporário 307 para POST /v3/token (configurado na camada de reescrita do > web.config do IIS). O HTTP 307 preserva tanto o método (POST) como > o corpo do pedido, pelo que qualquer cliente HTTP em conformidade com a norma > segue o redireccionamento de forma transparente — continua a enviar pedidos para /sms/token e recebe > de volta um JWT válido. Não há lógica de emissão de tokens duplicada; a > API SMS nunca emite tokens por si própria.

Tipos de grant suportados

Tempo de vida do token

• Token de acesso: 30 dias
• Refresh token: 90 dias

Utilize grant_type=refresh_token para renovar o token de acesso sem reautenticação. Guarde os tokens no lado do servidor (Vault, variáveis de ambiente); nunca os incorpore em JavaScript de browser ou em binários de aplicações móveis. Consulte a documentação do /token da API CRM v3 para a nota de segurança completa.

Corpo do pedido (application/x-www-form-urlencoded)

Respostas

Exemplo 200

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 31535999,
  "userName": "12345",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "application": null
}

Exemplo 400

{
  "error": "invalid_grant",
  "error_description": "The username or password is incorrect."
}

GET /account/limits.{format}

Obter quota mensal da API

Devolve a quota mensal de pedidos à API para o cliente autenticado.

Cálculo da quota: o limite é calibrado a partir dos créditos de subscrição de email (tipicamente subscription_credits × 5). Para um plano de 10 000 emails/mês, isto resulta num orçamento mensal de 50 000 pedidos. Reinicia na data de aniversário da subscrição (e não no dia 1 do mês de calendário).

O que consome créditos:

• Todos os pedidos à API autenticados para endpoints v2, v3 ou sms.
• Todos os eventos de webhook despachados para um endpoint subscrito.

O que é GRATUITO (não consome créditos):

• Endpoints /health.
• Pedidos que falham com 401, 403 ou 429.
• Eventos de webhook para clientes sem subscrição correspondente.

A quota é partilhada entre as 3 APIs Mailpro (v2, v3, sms) — um cliente = um orçamento mensal em toda a plataforma. Os envios SMS consomem adicionalmente o saldo de créditos SMS dedicado (GET /credit/get.{format}).

Scope OAuth : account:read

Parâmetros

Respostas

Exemplo 200

{
  "monthlyLimit": 50000,
  "remaining": 32847,
  "used": 17153,
  "isFree": false,
  "remainedSendsForFree": null
}

POST /send/add.{format}

Enviar SMS em massa para uma lista de contactos

Envia uma mensagem SMS para todos os números de telefone de uma lista de contactos. Suporta agendamento: defina scheduled_time para uma data futura para enviar mais tarde, ou omita-o para enviar imediatamente.

Consumo de créditos: os créditos são debitados no momento do envio. Mensagens longas (>160 caracteres GSM-7) são divididas em várias partes, cada uma consumindo créditos adicionais.

A resposta devolve { "Error": "Insufficient Credit", "Code": 202 } se a conta não tiver créditos suficientes.

Scope OAuth : sms:send

Parâmetros

Corpo do pedido (application/x-www-form-urlencoded)

Respostas

Exemplo 200

{
  "Id": 6001,
  "Message": "Flash sale today only — 30% off all orders. Shop now at mailpro.com/shop",
  "ScheduledTime": "2026-04-20T10:00:00",
  "To": [
    "42"
  ]
}

Exemplo 202

{
  "Error": "Insufficient Credit",
  "Code": 202
}

Exemplo 400

{
  "Error": "Malformed Input",
  "Code": 103
}

GET /send/add_single.{format}

Enviar um SMS único (GET)

Envia um único SMS para um destinatário através de um pedido GET. Útil para integrações simples nas quais POST não está disponível. As credenciais e a mensagem são passadas como parâmetros de query.

Nota: evite utilizar GET para mensagens sensíveis — os parâmetros de query aparecem nos registos do servidor. Prefira POST /send/add_single.

Scope OAuth : sms:send

Parâmetros

Respostas

Exemplo 200

{
  "Id": 5001,
  "Message": "Your appointment is confirmed for tomorrow at 10:00.",
  "ScheduledTime": "2026-04-15T09:00:00",
  "To": "0041791234567",
  "Charge": "1"
}

POST /send/add_single.{format}

Enviar um SMS único

Envia uma única mensagem SMS para um número de telefone destinatário. Suporta agendamento através de scheduled_time.

Consumo de créditos: os créditos são debitados no momento do envio. O campo Charge na resposta mostra quantos créditos foram consumidos.

A resposta devolve { "Error": "Insufficient Credit", "Code": 202 } se a conta não tiver créditos suficientes.

Scope OAuth : sms:send

Parâmetros

Corpo do pedido (application/x-www-form-urlencoded)

Respostas

Exemplo 200

{
  "Id": 5001,
  "Message": "Your verification code is 8472. Valid for 10 minutes.",
  "ScheduledTime": "2026-04-15T14:30:00",
  "To": "0041791234567",
  "Charge": "1"
}

Exemplo 202

{
  "Error": "Insufficient Credit",
  "Code": 202
}

Exemplo 400

{
  "Error": "Malformed Input",
  "Code": 103
}

GET /send/list.{format}

Listar campanhas SMS

Devolve a lista de campanhas SMS (envios em massa) para a conta. Paginação através dos cabeçalhos NumberOfRecords e PageNumber.

Utilize type_to para filtrar por tipo de envio:

• 0 (predefinição) — envios em massa para uma lista
• 1 — envios individuais únicos

Scope OAuth : sms:send

Parâmetros

Respostas

Exemplo 200

[
  {
    "Id": 5001,
    "Message": "Your verification code is 8472",
    "ScheduledTime": "2026-04-15T09:00:00",
    "To": "41791234567"
  }
]

POST /send/del.{format}

Cancelar ou eliminar um envio SMS

Cancela um envio SMS agendado pendente, ou elimina um envio concluído do histórico. Apenas os envios agendados para o futuro podem ser cancelados. Os envios em curso não podem ser parados.

Scope OAuth : sms:send

Parâmetros

Corpo do pedido (application/x-www-form-urlencoded)

Respostas

Exemplo 200

{
  "Result": "OK"
}

Exemplo 500

{
  "Error": "Delete failed",
  "Code": 500
}

GET /send/scheduled.{format}

Listar os meus envios SMS agendados

Devolve os envios SMS (únicos ou de campanha) agendados para uma data futura que ainda não foram despachados. Útil antes de invocar /cancel ou /reschedule.

Os registos são ordenados por scheduled_time ascendente.

Scope OAuth : sms:send

Parâmetros

Respostas

Exemplo 200

[
  {
    "Id": 9001,
    "Message": "Black Friday: 30% off until midnight.",
    "ScheduledTime": "2026-11-27T12:00:00",
    "To": "+33671234567"
  }
]

POST /send/{id_send}/cancel.{format}

Cancelar um envio SMS agendado

Cancela um SMS agendado que ainda não foi despachado. Se o envio já tiver sido processado (ou não existir / pertencer a outro cliente), devolve 409 Conflict.

Scope OAuth : sms:send

Parâmetros

Corpo do pedido (application/x-www-form-urlencoded)

Respostas

Exemplo 200

{
  "Result": "OK",
  "Cancelled": 9001
}

Exemplo 409

{
  "error": "conflict",
  "message": "Send not found, not owned by client, or already dispatched."
}

PATCH /send/{id_send}/reschedule.{format}

Reagendar um envio SMS agendado

Actualiza a data planeada de um SMS agendado que ainda não foi despachado. A nova data tem de estar no futuro e dentro de 90 dias.

Nome do campo de data: a API aceita scheduled_time (principal) bem como os aliases legados PlanDate, date_planned e DatePlanned. Forneça qualquer um deles — o primeiro não nulo é utilizado.

Scope OAuth : sms:send

Parâmetros

Corpo do pedido (application/x-www-form-urlencoded)

Respostas

Exemplo 200

{
  "Result": "OK",
  "Id": 9001,
  "NewScheduledTime": "2026-12-31T14:30:00"
}

Exemplo 409

{
  "error": "conflict",
  "message": "Reschedule failed — send not found, already dispatched, or new date out of range."
}

GET /list/list.{format}

Listar listas de contactos telefónicos

Devolve todas as listas de contactos SMS da conta. Utilize os valores Id devolvidos ao enviar campanhas SMS em massa ou ao adicionar números de telefone.

Scope OAuth : sms:contacts:read

Parâmetros

Respostas

Exemplo 200

{
  "Items": [
    {
      "AddressBookId": 42,
      "Name": "Newsletter subscribers",
      "TotalNumberPhones": 1547
    },
    {
      "AddressBookId": 43,
      "Name": "Loyalty program",
      "TotalNumberPhones": 823
    }
  ]
}

POST /list/add.{format}

Criar uma lista de contactos

Cria uma nova lista de contactos SMS com o nome indicado. A lista começa vazia — adicione números de telefone com POST /phone/add. Máximo de 1000 listas por conta (mesmo limite nas três API Mailpro e na app). Devolve HTTP 422 se o limite for atingido.

Parâmetros

Corpo do pedido (application/x-www-form-urlencoded)

Respostas

Exemplo 200

{
  "Id": 44,
  "Name": "Spring campaign 2026",
  "NumberPhones": 0
}

Exemplo 400

{
  "Error": "Malformed Input",
  "Code": 103
}

POST /list/edit.{format}

Renomear uma lista de contactos

Actualiza o nome de exibição de uma lista de contactos SMS existente. Os números de telefone na lista não são afectados.

Scope OAuth : sms:contacts:write

Parâmetros

Corpo do pedido (application/x-www-form-urlencoded)

Respostas

POST /list/del.{format}

Eliminar uma lista de contactos

Elimina permanentemente uma lista de contactos SMS e todos os números de telefone que ela contém. Esta acção não pode ser anulada.

Scope OAuth : sms:contacts:write

Parâmetros

Corpo do pedido (application/x-www-form-urlencoded)

Respostas

GET /phone/list.{format}

Listar números de telefone numa lista de contactos

Devolve uma lista paginada de números de telefone numa lista de contactos específica. Utilize address_book_id para especificar a lista a obter. Paginação: NumberOfRecords e PageNumber (5000 por página por predefinição, página 1).

Scope OAuth : sms:contacts:read

Parâmetros

Respostas

Exemplo 200

{
  "Items": [
    {
      "Id": 1001,
      "Number": "41791234567",
      "FirstName": "Alice",
      "LastName": "Dupont"
    },
    {
      "Id": 1002,
      "Number": "33612345678",
      "FirstName": "Bob",
      "LastName": "Martin"
    }
  ]
}

POST /phone/add.{format}

Adicionar número(s) de telefone a uma lista

Adiciona um ou mais números de telefone a uma lista de contactos.

Número único: utilize o campo number.

Importação em massa: utilize o campo phone_list com os números separados por ponto e vírgula: +41791234567;+33612345678;0049301234567

Os números de telefone aceitam o formato +, 00 ou simples — consulte Formato do número de telefone na descrição da API para a lista completa de entradas aceites / rejeitadas. Os números duplicados são silenciosamente ignorados, salvo se force=1 estiver definido.

Scope OAuth : sms:contacts:write

Parâmetros

Corpo do pedido (application/x-www-form-urlencoded)

Respostas

Exemplo 200

{
  "Id": 1003,
  "Number": "0041791234567",
  "FirstName": "Alice",
  "LastName": "Dupont"
}

POST /phone/edit.{format}

Actualizar uma entrada de número de telefone

Actualiza o número de telefone e/ou os dados de contacto de uma entrada existente. Utilize number_id (obtido em /phone/list) para identificar a entrada a actualizar. Apenas os campos fornecidos no pedido são actualizados.

Scope OAuth : sms:contacts:write

Parâmetros

Corpo do pedido (application/x-www-form-urlencoded)

Respostas

POST /phone/del.{format}

Remover um número de telefone de uma lista

Remove permanentemente uma entrada específica de número de telefone da sua lista de contactos. Utilize number_id (obtido em /phone/list) para identificar a entrada.

Scope OAuth : sms:contacts:write

Parâmetros

Corpo do pedido (application/x-www-form-urlencoded)

Respostas

GET /credit/get.{format}

Obter saldo de créditos SMS

Devolve o saldo actual de créditos SMS para a sua conta. Os créditos SMS são consumidos no momento do envio. Um SMS padrão (≤160 caracteres GSM-7) custa 1 crédito. Mensagens mais longas ou mensagens com caracteres especiais podem custar mais.

> Nota: isto devolve o seu saldo de créditos de envio SMS, não a sua quota de pedidos à API. > Para a quota da API consulte GET /account/limits.{format}.

Scope OAuth : sms:read

Parâmetros

Respostas

Exemplo 200

{
  "TotalCredits": 5000
}

GET /history/list.{format}

Listar histórico de envios SMS

Devolve um registo paginado de todas as campanhas SMS passadas enviadas a partir desta conta. Os resultados estão ordenados por data descendente (mais recente primeiro). Paginação: NumberOfRecords e PageNumber (cabeçalhos ou query, 5000 por página por predefinição).

Scope OAuth : sms:read

Parâmetros

Respostas

Exemplo 200

{
  "Items": [
    {
      "Id": 583294,
      "DateSent": "2026-07-17T18:56:39.813",
      "Message": "Your verification code is 8472",
      "Charge": 3,
      "Parts": 1
    }
  ]
}

POST /import/upload.{format}

Carregar um ficheiro de números de telefone (CSV / XLSX) para importação em massa

Carregue um ficheiro CSV ou XLSX para importar números de telefone para uma lista de contactos. O ficheiro é armazenado e colocado em fila para processamento assíncrono — o endpoint devolve imediatamente um ImportJobId.

Tipo de pedido: multipart/form-data

Campos de formulário obrigatórios:

• id_client (inteiro) — o seu ID de cliente Mailpro
• api_key (string) — a sua chave de API
• id_list (inteiro) — ID da lista de contactos de destino
• file (binário) — o ficheiro CSV ou XLSX a carregar

Opcional:

• webhook_url (string) — URL HTTPS invocado quando o processamento termina. Recebe um payload JSON com o estado final (success / failed) e contagens das linhas importadas / ignoradas / inválidas.

Formato do ficheiro:

• Codificado em UTF-8
• Primeira linha = cabeçalhos (um tem de ser Phone ou PhoneNumber — sem distinção entre maiúsculas e minúsculas)
• Números em formato internacional (E.164), p. ex. +41791234567
• Tamanho máximo do ficheiro: 50 MB

Scope OAuth : sms:contacts:write

Parâmetros

Corpo do pedido (multipart/form-data)

Respostas

Exemplo 200

{
  "Result": "OK",
  "ImportJobId": 15,
  "InternalName": "230575-20260420142616-phones.csv"
}

GET /webhooks

Listar webhooks

Devolve todos os webhooks configurados na conta autenticada.

Respostas

Exemplo 200

{
  "items": [
    {
      "id": 14,
      "url": "https://example.com/hooks/mailpro",
      "description": "Integração com o Slack",
      "is_active": true,
      "created_at": "2026-07-01T21:09:52.43",
      "updated_at": "2026-07-21T18:56:08.02",
      "last_delivery_at": "2026-07-21T18:56:07.653",
      "last_delivery_status": 200,
      "consecutive_failures": 0,
      "events": [
        "sms.delivered",
        "sms.failed"
      ]
    }
  ],
  "total": 1
}

POST /webhooks

Criar um webhook

Cria uma nova subscrição de webhook. A resposta contém um secret que é mostrado apenas uma vez — guarde-o imediatamente, no lado do servidor. Utilize-o para verificar a assinatura HMAC de cada payload recebido.

Limites: máximo de 20 webhooks por conta, máximo de 50 eventos por webhook.

Corpo do pedido (application/json)

Exemplo

{
  "url": "https://example.com/hooks/mailpro",
  "events": [
    "sms.delivered",
    "sms.failed"
  ],
  "description": "Integração com o Slack"
}

Respostas

Exemplo 201

{
  "id": 42,
  "url": "https://example.com/hooks/mailpro",
  "events": [
    "sms.delivered",
    "sms.failed"
  ],
  "description": "Integração com o Slack",
  "isActive": true,
  "consecutiveFailures": 0,
  "autoDisabledAt": null,
  "autoDisabledReason": null,
  "createdAt": "2026-05-25T10:00:00Z",
  "updatedAt": "2026-05-25T10:00:00Z",
  "secret": "whsec_AbcD1234EfgH5678IjkL9012MnoP3456QrsT"
}

GET /webhooks/{id}

Obter um webhook

Parâmetros

Respostas

PUT /webhooks/{id}

Actualizar um webhook

Actualização parcial — apenas os campos enviados são modificados.

Parâmetros

Corpo do pedido (application/json)

Respostas

DELETE /webhooks/{id}

Eliminar um webhook

Elimina permanentemente o webhook e o seu histórico de entregas completo.

Parâmetros

Respostas

POST /webhooks/{id}/test

Enviar um evento de teste

Coloca em fila um evento ping imediato (ou qualquer outro tipo de evento através do campo eventType no corpo) para o seu endpoint. Útil para verificar a acessibilidade e a verificação da assinatura antes de confiar em eventos reais.

Parâmetros

Corpo do pedido (application/json)

Exemplo

{
  "eventType": "ping"
}

Respostas

Exemplo 202

{
  "deliveryId": 1234,
  "eventId": "evt_8f3a9b2c4d1e5f6789abcdef01234567",
  "eventType": "ping"
}

POST /webhooks/{id}/rotate-secret

Rotacionar o segredo HMAC

Gera um novo segredo HMAC e invalida o antigo imediatamente. O novo segredo é devolvido uma vez na resposta — guarde-o. Todas as entregas a partir deste momento serão assinadas com o novo segredo.

Utilize esta opção se suspeitar que o seu segredo foi comprometido.

Parâmetros

Respostas

Exemplo 200

{
  "secret": "whsec_XyzA9876BcdE5432FghI1098JklM7654NopQ"
}

GET /webhooks/{id}/deliveries

Listar tentativas de entrega

Devolve o histórico de tentativas de despacho para este webhook (retenção de 30 dias). Útil para depuração — que eventos foram enviados, códigos de estado recebidos, contagens de tentativas, mensagens de erro.

Parâmetros

Respostas

POST /webhooks/{id}/deliveries/{deliveryId}/replay

Repetir uma entrega

Coloca em fila uma nova tentativa de entrega com o mesmo payload do original. Útil para voltar a desencadear uma entrega que falhou após corrigir o seu endpoint. É criada uma NOVA linha Webhook_Delivery (o original é preservado para fins de auditoria). A repetição segue a política de repetição padrão (mesmo agendamento de backoff, mesma regra de desactivação automática às 10 falhas).

Parâmetros

Respostas