Documentação Maildo
Referência de endpoints
Rotas implementadas de workspace com corpos mínimos, respostas e limites de disponibilidade.
Antes de chamar
Base da aplicação: https://app.maildo.com.br. Todas as rotas abaixo começam por /v1. Salvo as consultas de configuração pública, exigem uma identidade válida; as operações de workspace também exigem autorização. Leia autenticação, CSRF e idempotência.
Esta é uma referência curada das famílias documentadas, não o catálogo administrativo completo. Ela não publica configurações de infraestrutura, schemas internos, credenciais ou dados de clientes. IDs entre chaves são os IDs retornados pelo servidor, não valores para copiar literalmente.
Contatos
Lista os contatos do workspace em data.items, com data.nextOffset.
Importa de 1 a 1.000 contatos por chamada. Até 20 atributos de texto por contato. Duplicatas não são sobrescritas nem recebem novo consentimento por reimportação.
{
"contacts": [
{
"email": "ana@example.com",
"name": "Ana",
"attributes": {
"company": "Exemplo"
},
"consent": {
"purpose": "marketing",
"source": "opt_in_form",
"capturedAt": "2026-10-22T12:00:00.000Z",
"evidenceRef": "consent-example-001"
}
}
]
}Exemplo ilustrativo, não autorizado para importação real. Use a origem, a data e a evidência genuínas do consentimento. O resultado de importação inclui imported, duplicateCount, suppressedCount, suppressionScope e items. A importação não envia mensagens. Não existe um endpoint genérico de atualização ou exclusão de contato documentado nesta versão.
Templates
Lista os templates, com paginação.
Retorna o template, suas versões e hasMoreVersions.
Retorna uma versão publicada específica.
Cria o rascunho. Retorna id, workspaceId, revision, draft e updatedAt dentro de data.
{
"name": "Boas-vindas",
"subject": "Olá, {{name}}",
"mode": "blocks",
"blocks": [
{
"id": "welcome",
"kind": "text",
"text": "Olá, {{name}}!"
},
{
"id": "unsubscribe",
"kind": "unsubscribe",
"label": "Cancelar inscrição"
}
]
}Recebe um rascunho completo e retorna html, text, sanitizationWarnings e compatibilityWarnings. Não envia mensagem.
Corpo: {"expectedRevision":1,"draft":{...rascunho completo...}}. Uma revisão desatualizada deve ser resolvida antes de salvar novamente.
Corpo: {"expectedRevision":1}. Retorna uma versão imutável, incluindo id, version, subject, html, text e avisos de renderização.
Exige senderId, recipientEmail, recipientPermissionConfirmed:true e exatamente um entre draft ou templateVersionId. A permissão deve ser real. Depende de transporte habilitado e pode gerar uma mensagem; um job enfileirado não comprova entrega.
Campanhas
Criação, enfileiramento e retomada exigem transporte disponível. Não use esses exemplos enquanto a conta e o serviço não estiverem liberados. O modo SQL sem transporte retorna 503 transport_unavailable para essas operações.
Lista campanhas, com paginação.
Consulta campanha e revisão atual.
Lista destinatários com contactId, email, name, jobId, state e reason.
Cria rascunho com name, templateVersionId, senderId, contactIds e purpose (marketing ou transactional). Use IDs reais autorizados; até 5.000 contatos por criação.
{
"name": "Atualizações",
"templateVersionId": "<ID da versão publicada>",
"senderId": "<ID do remetente autorizado>",
"contactIds": [
"<ID do contato autorizado>"
],
"purpose": "marketing"
}Corpo: {"expectedRevision":1}. Exige estado draft. Retorna a campanha com status queued, não confirmação de entrega.
Corpo: {"expectedRevision":2,"status":"paused"}. Destinos permitidos: paused, queued e cancelled. queued retoma apenas uma campanha pausada. Consulte a revisão e o estado antes de mudar.
As respostas incluem status, revision, recipientCount e os snapshots da campanha. No contrato de código revisado, priceSnapshot registra uma referência comercial em BRL quando configurado; valores e moeda podem ser null quando desconhecidos. A publicação desta referência não comprova que a atualização monetária já foi instalada no ambiente. Não representa fatura, pagamento ou saldo. O faturamento automático não está implementado.
Cadastro e domínios
Consulta pública de disponibilidade do cadastro. Retorna enabled e activation; quando aplicável, domainProvisioningEnabled.
Exige identidade verificada, mesmo sem workspace operacional. Retorna workspaceRequest e domains dentro de data.
Corpo mínimo: name, company e useCase. name deve ter 2–120 caracteres, company 2–160 e useCase 20–2.000. contactEmail é opcional e usa o e-mail verificado por padrão.
{
"name": "Equipe Exemplo",
"company": "Exemplo Ltda",
"useCase": "Enviar atualizações consentidas aos nossos clientes."
}O resultado inicial tem state PENDING e dailyLimit 0. A criação da solicitação não libera envio. Um domain opcional registra o domínio solicitado, mas não cria automaticamente sua solicitação de domínio.
Corpo: {"domain":"news.example.com"}. Use apenas um domínio cujo controle você pode comprovar. Retorna registros e instruções específicos da solicitação.
Corpo: {}. Pode criar uma identidade no provedor; não é uma consulta inofensiva de DNS. Exige configuração e autorização de provisionamento.
Corpo: {}. Revalida e reconcilia o estado do domínio; depende do provisionamento habilitado.
Corpo: {}. Exige estado TECHNICALLY_VERIFIED com evidência recente (menos de 24 horas). Retorna REVIEW_PENDING; não habilita envio.
Essas três ações podem retornar 503 provisioning_disabled. Nunca fabrique valores TXT, DKIM, SPF ou DMARC: use os registros da solicitação e preserve os registros existentes do domínio. Não há rota de domínios em /v1/workspace/domains.
Remetentes e conversas
Retorna data como array de remetentes autorizados para o workspace. Não aceita parâmetros de paginação.
Lista conversas, com paginação.
Retorna data como array de mensagens da conversa, da mais antiga à mais recente. Não aceita parâmetros de paginação.
Resposta individual sujeita a permissões, proteção CSRF, idempotência e transporte habilitado. Pode enviar uma mensagem real. Corpo: {"replyToMessageId":"<UUID da mensagem recebida nesta conversa>","text":"Resposta"}. Apenas esses campos são aceitos; text deve ser não vazio e ter até 20.000 caracteres. A conversa deve estar aberta ou pendente, com contexto anterior de saída, consentimento e remetente válidos, sem bloqueio aplicável. O resultado é um job enfileirado, não confirmação de entrega.
A disponibilidade do inbox não comprova homologação do recebimento de e-mails. Eventos de entrega não são mensagens humanas. Veja o guia de conversas.