API CRM Mailpro™ v3 : Referência

POST /token

Obter token de acesso

Obtém um token JWT Bearer utilizando credenciais de cliente. Envie o access_token devolvido como Authorization: Bearer <token> em todos os pedidos subsequentes.

Tipos de concessão suportados

Tempo de vida do token

• Token de acesso: 30 dias
• Token de atualização: 90 dias

Utilize grant_type=refresh_token para obter um novo token de acesso sem voltar a autenticar — o seu SDK deve fazer isto automaticamente quando o token de acesso se aproximar da expiração (estratégia típica: atualizar quando faltarem menos de 24 h).

Armazenar tokens com segurança

Mesmo com um tempo de vida de 30 dias, quem obtiver um access_token pode fazer-se passar pela sua conta até este expirar. Armazene os tokens num cofre de segredos no lado do servidor (Vault, AWS Secrets Manager, Azure Key Vault, variáveis de ambiente num anfitrião reforçado). Nunca incorpore um token em:

• JavaScript do lado do cliente ou em qualquer pacote para o navegador
• Aplicações móveis distribuídas a utilizadores finais (o binário pode ser inspecionado)
• Repositórios Git públicos ou registos de build de CI

Se um token for divulgado, revogue-o através das definições da sua conta Mailpro e solicite um novo.

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/Me

Obter detalhes da conta

Devolve os detalhes do perfil e as definições da conta Mailpro autenticada.

Respostas

GET /Account/Credits

Obter saldo de créditos

Devolve o saldo de créditos restante de email e SMS para a conta.

Respostas

Exemplo 200

{
  "email_credits": 48500,
  "sms_credits": 1200
}

GET /Account/SubscriptionEndDate

Obter data de fim da subscrição

Devolve a data de expiração da subscrição Mailpro atual.

Respostas

GET /Account/Limits

Obter quota mensal da API

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

Cálculo da quota: o limite é calibrado a partir dos créditos da 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. O mapeamento exato é definido pela tarefa de faturação no momento da subscrição e reposto na data de aniversário da subscrição (não no dia 1 do mês civil).

O que consome créditos:

• Cada pedido autenticado à API para endpoints v2, v3 ou sms (cada chamada = 1 crédito, independentemente do resultado — tanto 2xx como a maioria dos erros de negócio 4xx contam).
• Cada evento de webhook despachado para um endpoint subscrito (ex.: contact.created disparado para o seu webhook subscrito = 1 crédito para além da chamada à API que o desencadeou).

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

• Endpoints /health (monitorização).
• Pedidos que falham com 401 (falha de autenticação), 403 (proibido) ou 429 (limitação de taxa).
• Eventos de webhook para clientes sem subscrição correspondente (curto-circuito em cache — sem impacto na quota).

Respostas

POST /Contact

Criar um contacto

Cria um novo contacto CRM com campos personalizados, atribuições de lista e etiquetas opcionais.

Obrigatório:

• email — tem de ser único em toda a conta
• lists — pelo menos uma atribuição de lista é obrigatória

Números de telefone aceitam +41…, 0041… ou 41… com ou sem separadores (máximo 12 dígitos no Contact — consulte Formato do número de telefone na descrição da API).

Campos personalizados são identificados pelo seu id (de GET /Field). Os valores são validados em função do tipo do campo.

Scope OAuth : contacts:write

Corpo do pedido (application/json)

Exemplo

{
  "email": "[email protected]",
  "phone_number": "+41791234567",
  "lists": [
    {
      "id": 101
    }
  ],
  "tags": [
    {
      "id": 5
    }
  ],
  "custom_fields": [
    {
      "id": 1,
      "value": "Alice"
    },
    {
      "id": 2,
      "value": "Dupont"
    }
  ]
}

Respostas

Exemplo 406

{
  "Message": "Contact cannot be created. A contact already exist with the same Email"
}

POST /Contact/Multiple

Importar contactos (em massa)

Cria até 1.000 contactos num único pedido para uma importação em massa eficiente. A resposta inclui uma lista de contactos criados com sucesso e uma lista de erros para contactos que não puderam ser criados (ex.: email duplicado, dados inválidos).

Nota: as listas e etiquetas utilizadas em importações em massa não podem estar associadas a fluxos de trabalho de automação ativos. Se estiverem, toda a importação é rejeitada com HTTP 406.

Scope OAuth : contacts:write

Corpo do pedido (application/json)

Exemplo

[
  {
    "email": "[email protected]",
    "lists": [
      {
        "id": 101
      }
    ],
    "custom_fields": [
      {
        "id": 1,
        "value": "Alice"
      }
    ]
  },
  {
    "email": "[email protected]",
    "lists": [
      {
        "id": 101
      }
    ],
    "custom_fields": [
      {
        "id": 1,
        "value": "Bob"
      }
    ]
  }
]

Respostas

Exemplo 200

{
  "Added": [
    {
      "Email": "[email protected]",
      "Id": "550e8400-e29b-41d4-a716-446655440000"
    },
    {
      "Email": "[email protected]",
      "Id": "660e8400-e29b-41d4-a716-446655440001"
    }
  ],
  "Errors": []
}

GET /Contact/{id}

Obter um contacto

Devolve os detalhes de um contacto específico. Utilize includeTags=true para devolver também as etiquetas atribuídas ao contacto. Utilize includeLists=true para devolver também as listas a que o contacto pertence.

Scope OAuth : contacts:read

Parâmetros

Respostas

Exemplo 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "phone_number": "41791234567",
  "custom_fields": [
    {
      "id": 1,
      "value": "Alice"
    },
    {
      "id": 2,
      "value": "Dupont"
    }
  ],
  "tags": [
    {
      "id": 5
    }
  ],
  "lists": [
    {
      "id": 101
    }
  ]
}

PUT /Contact/{id}

Atualizar um contacto

Atualiza o email, número de telefone, campos personalizados, atribuições de listas e etiquetas de um contacto. O corpo do pedido substitui os dados atuais do contacto — inclua todas as listas e etiquetas às quais quer que o contacto continue atribuído.

Obrigatório no corpo: email e pelo menos uma entrada em lists.

Scope OAuth : contacts:write

Parâmetros

Corpo do pedido (application/json)

Respostas

Exemplo 200

{
  "Result": "Successful operation"
}

DELETE /Contact/{id}

Eliminar um contacto

Elimina permanentemente um contacto do CRM.

Scope OAuth : contacts:write

Parâmetros

Respostas

GET /Contact/{id}/Activity

Atividade de um contacto em 90 dias

Emails recebidos, abertos e clicados, cliente de email preferido e últimas campanhas do contacto.

Scope OAuth : contacts:read

Parâmetros

Respostas

Exemplo 200

{
  "period_days": 90,
  "email_received": 12,
  "email_opened": 7,
  "email_clicked": 2,
  "favorite_email_client": "Gmail",
  "last_campaigns": [
    {
      "id": 5001,
      "name": "Spring Sale 2026",
      "date": "2026-10-01T09:00:00"
    }
  ]
}

PUT /Contact/{id}/Tag/{tagid}

Adicionar etiqueta ao contacto

Atribui uma etiqueta a um contacto. Se a etiqueta já estiver atribuída, a operação não tem efeito.

Scope OAuth : contacts:write

Parâmetros

Respostas

DELETE /Contact/{id}/Tag/{tagid}

Remover etiqueta do contacto

Remove a atribuição de uma etiqueta a um contacto.

Scope OAuth : contacts:write

Parâmetros

Respostas

PUT /Contact/{id}/List/{listid}

Adicionar contacto à lista

Adiciona um contacto a uma lista específica. Devolve HTTP 404 se o contacto tiver previamente cancelado a subscrição desta lista.

Scope OAuth : contacts:write

Parâmetros

Respostas

DELETE /Contact/{id}/List/{listid}

Remover contacto da lista

Remove um contacto de uma lista específica. O próprio contacto não é eliminado.

Scope OAuth : contacts:write

Parâmetros

Respostas

GET /List

Listar listas de contactos

Devolve todas as listas de contactos da conta. Filtre por nome ou data de criação. Ordene alfabeticamente com sortByName=true. Inclua a contagem total de contactos por lista com includeTotalContacts=true.

Scope OAuth : contacts:read

Parâmetros

Respostas

Exemplo 200

[
  {
    "id": 101,
    "name": "Newsletter subscribers",
    "total_contacts": 4521,
    "date_creation": "2025-01-15T10:30:00"
  }
]

POST /List

Criar uma lista de contactos

Cria uma nova lista de contactos. Máximo de 1.000 listas por conta.

Scope OAuth : contacts:write

Corpo do pedido (application/json)

Exemplo

{
  "name": "Spring Campaign 2026"
}

Respostas

Exemplo 200

{
  "id": 102,
  "name": "Spring Campaign 2026",
  "date_creation": "2026-04-14T12:00:00"
}

GET /List/{id}

Obter uma lista de contactos

Devolve os detalhes de uma lista de contactos específica.

Scope OAuth : contacts:read

Parâmetros

Respostas

PUT /List/{id}

Atualizar uma lista de contactos

Renomeia uma lista de contactos existente.

Scope OAuth : contacts:write

Parâmetros

Corpo do pedido (application/json)

Exemplo

{
  "name": "Newsletter subscribers — Europe"
}

Respostas

DELETE /List/{id}

Eliminar uma lista de contactos

Elimina permanentemente uma lista de contactos. Os próprios contactos não são eliminados — apenas a sua pertença a esta lista é removida. As listas utilizadas por fluxos de trabalho de automação ativos não podem ser eliminadas.

Scope OAuth : contacts:write

Parâmetros

Respostas

GET /List/{id}/Contact

Listar contactos numa lista

Devolve os contactos que pertencem a uma lista específica. Filtre por email ou data de adição. Inclua etiquetas e pertenças a listas com os respetivos sinalizadores.

Scope OAuth : contacts:read

Parâmetros

Respostas

GET /List/{listId}/Unsubscribers

Listar cancelamentos de subscrição

Devolve os contactos que cancelaram a subscrição de uma lista específica.

Scope OAuth : contacts:read

Parâmetros

Respostas

GET /Tag

Listar etiquetas

Devolve todas as etiquetas da conta.

Scope OAuth : contacts:read

Parâmetros

Respostas

Exemplo 200

[
  {
    "id": 5,
    "name": "VIP customers"
  },
  {
    "id": 6,
    "name": "Newsletter openers"
  }
]

POST /Tag

Criar uma etiqueta

Cria uma nova etiqueta. Máximo de 1.000 etiquetas por conta.

Scope OAuth : contacts:write

Corpo do pedido (application/json)

Exemplo

{
  "name": "VIP customers"
}

Respostas

GET /Tag/{id}

Obter uma etiqueta

Devolve uma etiqueta específica pelo seu ID.

Scope OAuth : contacts:read

Parâmetros

Respostas

PUT /Tag/{id}

Atualizar uma etiqueta

Renomeia uma etiqueta existente.

Scope OAuth : contacts:write

Parâmetros

Corpo do pedido (application/json)

Exemplo

{
  "name": "VIP customers — updated"
}

Respostas

DELETE /Tag/{id}

Eliminar uma etiqueta

Elimina permanentemente uma etiqueta. A etiqueta é removida de todos os contactos. As etiquetas utilizadas por fluxos de trabalho de automação ativos não podem ser eliminadas.

Scope OAuth : contacts:write

Parâmetros

Respostas

GET /Tag/{id}/Contact

Listar contactos com uma etiqueta

Devolve os contactos aos quais foi atribuída uma etiqueta específica.

Scope OAuth : contacts:read

Parâmetros

Respostas

GET /Field

Listar campos personalizados

Devolve todos os campos personalizados de contacto definidos para a conta. Utilize os valores id devolvidos ao criar ou atualizar contactos.

Parâmetros

Respostas

Exemplo 200

[
  {
    "id": 1,
    "name": "first_name",
    "personalisation_key": "first_name",
    "field_type": "text"
  },
  {
    "id": 2,
    "name": "last_name",
    "personalisation_key": "last_name",
    "field_type": "text"
  }
]

POST /Field

Criar um campo personalizado

Cria um novo campo personalizado de contacto. Máximo de 50 campos por conta. Utilize o id devolvido ao atribuir valores a contactos.

Corpo do pedido (application/json)

Exemplo

{
  "name": "First name",
  "id_field_type": 1,
  "personalize_key": "first_name"
}

Respostas

GET /Field/Types

Listar tipos de campo

Devolve os identificadores de tipo de campo disponíveis para utilizar ao criar um campo personalizado. Tipos comuns: 1 = texto, 2 = número, 3 = data.

Respostas

GET /Field/{id}

Obter um campo personalizado

Devolve a definição e os metadados de um campo personalizado específico.

Parâmetros

Respostas

PUT /Field/{id}

Atualizar um campo personalizado

Atualiza o nome ou a chave de personalização de um campo personalizado.

Parâmetros

Corpo do pedido (application/json)

Respostas

DELETE /Field/{id}

Eliminar um campo personalizado

Elimina permanentemente um campo personalizado e remove o seu valor de todos os contactos. Esta ação não pode ser anulada.

Parâmetros

Respostas

GET /Campaign

Listar campanhas

Devolve uma lista paginada das campanhas de email da conta.

Parâmetros

Respostas

Exemplo 200

[
  {
    "id": 8001,
    "title": "Spring Newsletter April 2026",
    "date_planned": "2026-04-20T09:00:01",
    "count_open": 1823,
    "count_sent": 4521,
    "count_click": 342,
    "count_badmail": 12,
    "count_unsubscription": 8,
    "count_clicking_users": 289,
    "count_complaints": 1,
    "spam_trap": 0,
    "deliverability_score": 98
  }
]

GET /Campaign/{id}

Obter uma campanha

Devolve a configuração e o resumo de estatísticas de uma campanha específica.

Parâmetros

Respostas

PUT /Campaign/{id}

Atualizar uma campanha

Atualiza o título ou a data de envio de uma campanha agendada. As campanhas só podem ser modificadas até 5 minutos antes da hora de envio agendada.

Parâmetros

Corpo do pedido (application/json)

Respostas

DELETE /Campaign/{id}

Eliminar uma campanha

Cancela e elimina permanentemente uma campanha através do seu identificador.

Parâmetros

Respostas

GET /Campaign/Scheduled

Listar as minhas campanhas agendadas

Devolve as campanhas com date_planned no futuro que ainda não foram despachadas. Ordenadas por date_planned ascendente.

Parâmetros

Respostas

Exemplo 200

[
  {
    "id": 5001,
    "id_client": 12345,
    "subject": "Spring Sale 2026",
    "date_planned": "2026-05-01T09:00:00",
    "title": "Spring Sale",
    "id_campaign": 7001,
    "id_list": 101,
    "id_segment": null,
    "number_email": 1250
  }
]

POST /Campaign/{id}/Cancel

Cancelar uma campanha agendada

Cancela uma campanha agendada no futuro. Devolve 409 Conflict se a campanha já tiver sido despachada ou não existir.

Parâmetros

Respostas

Exemplo 200

{
  "result": "ok",
  "cancelled": 5001
}

PATCH /Campaign/{id}/Reschedule

Reagendar uma campanha agendada

Atualiza a data de envio planeada de uma campanha agendada. A nova data tem de estar no futuro e dentro de 90 dias.

Nome do campo no corpo: a API aceita date_planned (snake_case, primário), bem como os aliases legados PlanDate e scheduled_time. Forneça qualquer um deles — é utilizado o primeiro que não seja nulo.

Parâmetros

Corpo do pedido (application/json)

Respostas

Exemplo 200

{
  "result": "ok",
  "id": 5001,
  "date_planned": "2026-12-31T14:30:00"
}

GET /Campaign/{id}/ByHour

Estatísticas por hora

Devolve a divisão horária de aberturas e cliques da campanha.

Parâmetros

Respostas

GET /Campaign/{id}/ByDay

Estatísticas por dia

Devolve a divisão diária de aberturas e cliques da campanha.

Parâmetros

Respostas

GET /Campaign/{id}/Openings

Listar aberturas de email

Devolve uma lista paginada de contactos que abriram o email da campanha.

Parâmetros

Respostas

GET /Campaign/{id}/Clicks

Listar cliques em ligações

Devolve uma lista paginada de contactos que clicaram numa ligação na campanha.

Parâmetros

Respostas

GET /Campaign/{id}/HardBounces

Listar devoluções permanentes

Devolve os endereços de email que tiveram devolução permanente durante esta campanha.

Parâmetros

Respostas

GET /Campaign/{id}/Links

Listar ligações monitorizadas

Devolve dados de desempenho de cliques para cada ligação monitorizada na campanha.

Parâmetros

Respostas

GET /Campaign/{id}/OS

Estatísticas por SO / dispositivo

Devolve a divisão de aberturas e cliques por sistema operativo e tipo de dispositivo.

Parâmetros

Respostas

GET /Campaign/{id}/EmailClients

Estatísticas por cliente de email

Devolve a divisão de aberturas por cliente de email (Gmail, Outlook, Apple Mail…).

Parâmetros

Respostas

GET /Campaign/{id}/Countries

Estatísticas por país

Devolve a distribuição geográfica das aberturas e cliques.

Parâmetros

Respostas

POST /Send/Mail

Enviar email transacional

Envia um email transacional pontual para um único destinatário.

Destinatário: forneça email (endereço em linha) OU id_contact (contacto do CRM) — não ambos. Utilizar id_contact permite a personalização automática com os valores dos campos personalizados do contacto.

Conteúdo: forneça body_html (HTML em linha) OU id_message (modelo guardado) — não ambos. Se ambos forem indicados, prevalece id_message.

Obrigatórios: id_sender_email, subject e um de (email ou id_contact), e um de (body_html ou id_message).

Corpo do pedido (application/json)

Exemplo

{
  "id_sender_email": 201,
  "email": "[email protected]",
  "subject": "Your order #12345 has shipped",
  "body_html": "<p>Hello {{first_name}}, your order is on its way!</p>",
  "reply_to": "[email protected]",
  "fields": [
    {
      "id": 1,
      "value": "Alice"
    }
  ],
  "attachments": [
    {
      "filename": "invoice.pdf",
      "content": "JVBERi0xLjQKJVBERi0xLjQK..."
    }
  ]
}

Respostas

Exemplo 200

{
  "message": "Successful operation",
  "id_single_send": 8001
}

Exemplo 404

{
  "Message": "Not enough credit available"
}

GET /Send/{id}/Status

Obter o estado de entrega de um e-mail transacional

Devolve o estado de entrega atual de um e-mail transacional enviado com POST /Send/Mail. Passe o id_single_send que essa chamada devolveu.

Valores possíveis: delivered (aceite pelo servidor do destinatário, ver diag_code), bounced (recusado — bounce_type: hard endereço inválido ou recusa definitiva, soft recusa após novas tentativas), sent (entregue ao servidor de correio, ainda sem resposta), scheduled (ainda não enviado, date_planned no futuro) e queued (à espera de envio). delivered e bounced são finais: pare de consultar. Cada email tem um estado final no máximo 48 horas após o envio; consulte no máximo a cada 15 minutos (cada chamada conta para a sua quota da API) ou utilize os webhooks email.delivered / email.bounced. Só o cliente que enviou o email pode ler o seu estado — qualquer outro id devolve 404.

Parâmetros

Respostas

Exemplo 200

{
  "id_single_send": 8001,
  "email": "[email protected]",
  "status": "delivered",
  "date_planned": "2026-04-15T14:30:00",
  "status_date": "2026-04-15T14:30:07",
  "diag_code": "2.0.0 (success)",
  "bounce_type": null
}

POST /Send/Campaign

Enviar campanha de email

Envia uma campanha de email em massa para uma ou mais listas de contactos.

Obrigatório:

• id_message — o modelo a enviar (de GET /Message)
• id_sender_email — o endereço do remetente (de GET /SenderEmail)
• lists — pelo menos uma lista de contactos alvo
• campaign_title — etiqueta para o registo de estatísticas

Segmento: opcionalmente filtre destinatários por um segmento guardado (id_segment). O segmento filtra contactos dentro das listas especificadas.

Agendamento: defina date_planned para uma data/hora futura ISO 8601. As campanhas podem ser editadas ou canceladas até 5 minutos antes da hora agendada.

Corpo do pedido (application/json)

Exemplo

{
  "id_message": 501,
  "id_sender_email": 201,
  "lists": [
    {
      "id": 101
    }
  ],
  "campaign_title": "Spring Newsletter April 2026",
  "date_planned": "2026-04-20T09:00:00"
}

Respostas

Exemplo 200

{
  "Message": "Successful operation. Campaigns can be edited or deleted until 5 minutes prior to send.",
  "IdCampaign": 8001
}

GET /Send

Listar envios agendados

Devolve a lista de campanhas de email à espera de serem enviadas (agendadas, ainda não processadas).

Parâmetros

Respostas

DELETE /Send/{id}

Cancelar um envio agendado

Cancela e elimina um envio de email agendado que ainda não foi processado. Não é possível cancelar envios que estejam a ser processados atualmente.

Parâmetros

Respostas

GET /Send/Mail/Scheduled

Listar os emails individuais agendados

Devolve os emails individuais enviados com POST /Send/Mail e uma data futura, ainda não expedidos. As campanhas são listadas por GET /Campaign/Scheduled.

Scope OAuth : email:send

Respostas

Exemplo 200

[
  {
    "id_single_send": 880123,
    "email": "[email protected]",
    "subject": "Your invoice",
    "date_planned": "2026-12-01T09:00:00"
  }
]

POST /Send/Mail/{id}/Cancel

Cancelar um email individual agendado

Cancela o email enquanto não tiver sido expedido.

Scope OAuth : email:send

Parâmetros

Respostas

Exemplo 200

{
  "result": "ok",
  "cancelled": 880123
}

PATCH /Send/Mail/{id}/Reschedule

Reagendar um email individual agendado

Altera a data de envio. A nova data tem de ser futura e dentro de 90 dias. POST também é aceite.

Scope OAuth : email:send

Parâmetros

Corpo do pedido (application/json)

Respostas

Exemplo 200

{
  "result": "ok",
  "id": 880123,
  "date_planned": "2026-12-15T09:00:00"
}

GET /SenderEmail

Listar endereços de remetente

Devolve os endereços de email de remetente validados configurados para a conta.

Parâmetros

Respostas

Exemplo 200

[
  {
    "id": 201,
    "email": "[email protected]",
    "sender_name": "Your Company Newsletter",
    "is_validated": true
  }
]

POST /SenderEmail

Adicionar um endereço de remetente

Adiciona o endereço com os mesmos controlos da aplicação e envia-lhe um email de validação. Pode ser utilizado depois de clicar na hiperligação desse email. Uma conta pode ter até 25 remetentes, validados ou pendentes.

Scope OAuth : email:templates:write

Corpo do pedido (application/json)

Respostas

Exemplo 200

{
  "result": "ok",
  "confirmation_sent": true,
  "domain_has_mx": true
}

POST /SenderEmail/{id}/ResendValidation

Enviar novamente o email de validação

Para um endereço ainda a aguardar validação.

Scope OAuth : email:templates:write

Parâmetros

Respostas

Exemplo 200

{
  "result": "ok",
  "confirmation_sent": true
}

GET /SenderEmail/{id}/Authentication

Verificar o domínio de um remetente (SPF, DKIM, DMARC, MX)

Verifica o domínio em direto no DNS e devolve os registos a publicar. Apenas leitura. O DKIM é ativado na aplicação: dkim_settings_url abre o ecrã certo.

Scope OAuth : email:templates:read

Parâmetros

Respostas

Exemplo 200

{
  "domain": "example.com",
  "spf": {
    "valid": true,
    "record": "v=spf1 include:spf.mailpro.com -all",
    "recommended_record": "v=spf1 include:spf.mailpro.com -all",
    "change_needed": false
  },
  "dkim": {
    "valid": true,
    "records": [
      {
        "host": "key._domainkey.example.com",
        "value": "v=DKIM1;k=rsa;p=MIIBIjANBgkq...",
        "validated": true
      }
    ]
  },
  "dmarc": {
    "valid": true,
    "record": "v=DMARC1; p=quarantine"
  },
  "mx": {
    "valid": true,
    "record": "mail.example.com"
  },
  "dkim_settings_url": "https://app.mailpro.com/dkim/list?d=example.com"
}

GET /History/Email

Listar histórico de envios de email

Devolve o registo de envios de email anteriores da conta.

Parâmetros

Respostas

GET /History/SMS

Listar histórico de envios de SMS

Devolve o registo de envios de SMS anteriores da conta.

Parâmetros

Respostas

GET /Segment

Listar segmentos

Devolve todos os segmentos dinâmicos guardados da conta.

Scope OAuth : contacts:read

Parâmetros

Respostas

GET /Segment/{id}/Contact

Listar os contactos de um segmento

Com id_list, devolve apenas os contactos dessa lista que entram no segmento: os que uma campanha lista + segmento alcançaria. O total está no cabeçalho X-Total-Count.

Scope OAuth : contacts:read

Parâmetros

Respostas

GET /Segment/{id}/Count

Contar os contactos de um segmento

Apenas o número, para conhecer antecipadamente a dimensão de um envio. Com id_list, conta apenas os contactos dessa lista que entram no segmento.

Scope OAuth : contacts:read

Parâmetros

Respostas

Exemplo 200

{
  "total": 1250
}

GET /Segment/{id}/contact/{contactId}/check

Verificar se um contacto corresponde a um segmento

Verifica se um contacto específico (por GUID) corresponde atualmente às regras de um determinado segmento. Útil para acionar lógica de automação a pedido.

Scope OAuth : contacts:read

Parâmetros

Respostas

POST /Sms/SingleSMS

Enviar SMS único

Envia um SMS único para um número de telefone diretamente. Utilize-o para mensagens transacionais (OTPs, confirmações de encomenda, alertas). O número de telefone aceita +41…, 0041… ou 41… com ou sem separadores — consulte Formato do número de telefone na descrição da API para entradas aceites / rejeitadas.

Corpo do pedido (application/json)

Exemplo

{
  "phone_number": "+41791234567",
  "message": "Your verification code is 9473. Valid for 10 minutes."
}

Respostas

POST /Sms/Campaign

Enviar campanha de SMS

Envia uma mensagem SMS para o campo phone_number de todos os contactos em uma ou mais listas. Os contactos sem número de telefone são ignorados.

Corpo do pedido (application/json)

Exemplo

{
  "lists": [
    {
      "id": 101
    }
  ],
  "message": "Flash sale today — 20% off. Shop at mailpro.com",
  "date_planned": "2026-04-20T10:00:00"
}

Respostas

GET /Sms

Listar histórico de SMS

Devolve o registo de envios de SMS (único e em campanha) da conta.

Parâmetros

Respostas

DELETE /Sms/{id}

Cancelar um SMS agendado

Cancela um envio de SMS agendado pendente.

Parâmetros

Respostas

GET /Sms/Scheduled

Listar envios de SMS agendados

Devolve envios de SMS com date_planned futuro (ainda não despachados), ordenados por data ascendente.

Parâmetros

Respostas

POST /Sms/{id}/Cancel

Cancelar um SMS agendado

Cancela um envio de SMS agendado apenas se ainda não tiver sido despachado.

Parâmetros

Respostas

PATCH /Sms/{id}/Reschedule

Reagendar um SMS agendado

Atualiza a data de envio planeada de um SMS agendado. A nova data tem de estar no futuro e dentro de 90 dias. Falha se o SMS já tiver sido despachado.

Nome do campo no corpo: a API aceita date_planned (snake_case, primário), bem como os aliases legados PlanDate e scheduled_time. Forneça qualquer um deles.

Parâmetros

Corpo do pedido (application/json)

Respostas

GET /FolderList

Listar pastas de listas

Devolve as pastas utilizadas para organizar as listas de contactos.

Parâmetros

Respostas

GET /FolderList/{id}

Obter uma única pasta de listas

Devolve os detalhes de uma pasta de listas pelo seu ID.

Parâmetros

Respostas

GET /FolderMessage

Listar pastas de mensagens

Devolve as pastas utilizadas para organizar os modelos de mensagens de email.

Parâmetros

Respostas

POST /Import/Upload

Carregar um ficheiro de contactos (CSV / XLSX) para importação em massa

Carregue um ficheiro CSV ou XLSX para importar contactos para uma lista. O ficheiro é armazenado e colocado em fila para processamento assíncrono — o endpoint devolve um import_job_id de imediato.

Tipo de pedido: multipart/form-data

Campos de formulário obrigatórios:

• id_list (inteiro) — ID da lista de destino
• file (binário) — o ficheiro CSV ou XLSX a carregar
• json_match_fields (string, JSON) — que coluna do ficheiro vai para que campo do contacto. email_position = coluna do e-mail, numerada a partir de 0 (obrigatório), phone_position = coluna do número de telemóvel ou -1, fields = IDs dos restantes campos (ver GET /Field), fields_position = coluna de cada um deles, update_fields = atualizar os contactos existentes. Correspondência ausente ou inválida: resposta 400, nenhuma importação é criada.

Opcional:

• webhook_url (string) — URL HTTPS chamado quando o processamento termina. Recebe uma carga útil JSON com o estado final (sucesso / falha) e contagens de linhas importadas / ignoradas / inválidas.

Formato do ficheiro:

• Codificado em UTF-8
• A primeira linha pode conter os cabeçalhos (deteção automática: uma primeira linha sem nenhum endereço de e-mail é ignorada)
• As colunas são associadas aos campos por json_match_fields
• Tamanho máximo do ficheiro: 50 MB

Corpo do pedido (multipart/form-data)

Respostas

Exemplo 200

{
  "result": "OK",
  "import_job_id": 14,
  "internal_name": "230575-20260420142615-contacts.csv"
}

GET /Webhook

Listar webhooks

Devolve todos os webhooks configurados na conta autenticada.

Respostas

POST /Webhook

Criar um webhook

Cria uma nova subscrição de webhook. A resposta contém um secret que is apresentado apenas uma vez — armazene-o imediatamente, no lado do servidor. Utilize-o para verificar a assinatura HMAC de cada carga útil recebida.

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

Corpo do pedido (application/json)

Exemplo

{
  "url": "https://example.com/hooks/mailpro",
  "events": [
    "email.delivered",
    "email.bounced",
    "contact.created"
  ],
  "description": "Integração Slack"
}

Respostas

Exemplo 201

{
  "id": 42,
  "url": "https://example.com/hooks/mailpro",
  "events": [
    "email.delivered",
    "email.bounced",
    "contact.created"
  ],
  "description": "Integraçã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 /Webhook/{id}

Obter um webhook

Parâmetros

Respostas

PUT /Webhook/{id}

Atualizar um webhook

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

Parâmetros

Corpo do pedido (application/json)

Respostas

DELETE /Webhook/{id}

Eliminar um webhook

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

Parâmetros

Respostas

POST /Webhook/{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 do corpo) para o seu endpoint. Útil para verificar a acessibilidade e a verificação de assinatura antes de depender de eventos reais.

Parâmetros

Corpo do pedido (application/json)

Exemplo

{
  "eventType": "ping"
}

Respostas

Exemplo 202

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

POST /Webhook/{id}/rotate-secret

Rodar o segredo HMAC

Gera um novo segredo HMAC e invalida o antigo de imediato. O novo segredo é devolvido uma única vez na resposta — armazene-o. Cada entrega a partir deste momento será assinada com o novo segredo.

Utilize isto se suspeitar que o seu segredo foi comprometido.

Parâmetros

Respostas

Exemplo 200

{
  "secret": "whsec_XyzA9876BcdE5432FghI1098JklM7654NopQ"
}

GET /Webhook/{id}/deliveries

Listar tentativas de entrega

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

Parâmetros

Respostas

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

Reproduzir uma entrega

Coloca em fila uma nova tentativa de entrega com a mesma carga útil do original. Útil para reacionar uma entrega falhada após corrigir o seu endpoint. Uma NOVA linha Webhook_Delivery é criada (a original é preservada para auditoria). A reprodução passa pela política de novas tentativas padrão (10s → 1min → 5min → 30min → 2h → 6h → 24h, depois abandonada).

Parâmetros

Respostas

GET /Suppression/Bounces

Listar os bounces da conta

Os mais recentes primeiro. O total está no cabeçalho X-Total-Count.

Scope OAuth : email:read

Parâmetros

Respostas

Exemplo 200

[
  {
    "id": 5521,
    "source": "contact",
    "type": "hard",
    "email": "[email protected]",
    "date": "2026-10-12T08:30:00",
    "diag_code": "550 5.1.1 User unknown",
    "id_list": 101
  }
]

DELETE /Suppression/Bounces/{id}

Remover um bounce

source e type são obrigatórios, tal como devolvidos por GET /Suppression/Bounces: um id sozinho não é único.

Scope OAuth : contacts:write

Parâmetros

Respostas

Exemplo 200

{
  "result": "ok",
  "id": 5521,
  "restored": false
}

POST /Suppression/Bounces/{id}/Restore

Repor nas suas listas um contacto com hard bounce

Apenas para um hard bounce com a origem contact.

Scope OAuth : contacts:write

Parâmetros

Respostas

Exemplo 200

{
  "result": "ok",
  "id": 5521,
  "restored": true
}

GET /Suppression/Unsubscribers

Listar os cancelamentos de subscrição da conta

Os mais recentes primeiro. O total está no cabeçalho X-Total-Count.

Scope OAuth : contacts:read

Parâmetros

Respostas

Exemplo 200

[
  {
    "id": 9012,
    "source": "api3",
    "email": "[email protected]",
    "date": "2026-10-20T16:05:00",
    "list_name": null,
    "comment": "Asked by phone"
  }
]

POST /Suppression/Unsubscribers

Adicionar um cancelamento de subscrição

Sem id_list, a subscrição do endereço é cancelada para toda a conta. Com id_list, apenas nessa lista de cancelamento.

Scope OAuth : contacts:write

Corpo do pedido (application/json)

Respostas

Exemplo 200

{
  "result": "ok",
  "already_unsubscribed": false
}

DELETE /Suppression/Unsubscribers/{id}

Remover um cancelamento de subscrição

source é obrigatório, tal como devolvido por GET /Suppression/Unsubscribers: um id sozinho não é único.

Scope OAuth : contacts:write

Parâmetros

Respostas

Exemplo 200

{
  "result": "ok",
  "removed": 9012
}