Documentação da API
Guia completo para integrar o VuyMail na sua aplicação. Envie emails transacionais e marketing com nossa API RESTful simples e poderosa.
Início Rápido
1. Obtenha sua API Key
Acesse o dashboard em /dashboard/credentials e gere uma nova chave de API.
2. Envie seu primeiro email
Teste a API enviando um email simples:
curl -X POST https://api.vuymail.com/v1/email/send \ -H "X-API-Key: sua_chave_api_aqui" \ -H "Content-Type: application/json" \ -d '{ "from": "[email protected]", "to": "[email protected]", "subject": "Meu primeiro email via API", "text": "Conteúdo em texto puro", "html": "<h1>Olá!</h1><p>Email via VuyMail API</p>" }'
Autenticação
Todas as requisições da API requerem autenticação via chave de API.
Como autenticar:
Gere uma chave de API no dashboard (/dashboard/credentials)
Inclua a chave no header X-API-Key em todas as requisições
Mantenha sua chave em segredo - nunca a exponha em código frontend
Referência da API
Endpoint de Envio
/api/v1/email/sendEnvia um email usando as credenciais do seu mailbox.
Campos da Requisição
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
from | string | Sim | Email remetente (deve ser seu mailbox) |
to | string | string[] | Sim | Email(s) destinatário(s) |
subject | string | Sim | Assunto do email |
text | string | Recomendado | Versão em texto puro |
html | string | Não | Versão HTML |
cc | string | string[] | Não | Destinatários CC |
bcc | string | string[] | Não | Destinatários BCC |
replyTo | string | Não | Endereço Reply-To |
priority | high | normal | low | Não | Prioridade do email |
headers | object | Não | Headers customizados |
attachments | array | Não | Anexos (max 20MB total) |
Formato de Resposta
Sucesso (200):
json
{ "success": true, "data": { "messageId": "<[email protected]>", "accepted": ["[email protected]"], "rejected": [], "usage": { "daily": { "limit": 100, "used": 45, "remaining": 55 }, "monthly": { "limit": 1000, "used": 234, "remaining": 766 } }, "rateLimit": { "limit": 60, "remaining": 59, "reset": "2026-03-04T15:30:00.000Z" } } }
Erro (4xx/5xx):
json
{ "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Mensagem de erro descritiva", "details": { "limit": 60, "resetAt": "2026-03-04T15:30:00.000Z", "retryAfter": 42 } } }
Códigos de Erro
Código | Status | Descrição |
|---|---|---|
MISSING_API_KEY | 401 | Nenhuma chave API fornecida |
INVALID_API_KEY | 401 | Chave API inválida ou revogada |
RATE_LIMIT_EXCEEDED | 429 | Muitas requisições |
DAILY_LIMIT_EXCEEDED | 403 | Cota diária de emails excedida |
MONTHLY_LIMIT_EXCEEDED | 403 | Cota mensal de emails excedida |
MAILBOX_NOT_FOUND | 400 | Mailbox remetente não existe |
MAILBOX_INACTIVE | 403 | Mailbox remetente está inativo |
UNAUTHORIZED_MAILBOX | 403 | Você não é dono deste mailbox |
EMAIL_SEND_FAILED | 500 | Erro SMTP ou falha na entrega |
Limites de Taxa
Baseado em IP (Anti-DDoS):
20 requisições por minuto por endereço IP
Aplica-se a todas as chaves API do mesmo IP
Baseado em Chave API (Dependente do Plano):
Plano | Requisições/minuto |
|---|---|
Free | 10 |
Starter | 30 |
Pro | 60 |
Business | 100 |
Cotas de Envio
As cotas de envio de email são aplicadas por plano:
Plano | Limite Diário | Limite Mensal |
|---|---|---|
Free | 10 | 100 |
Starter | 50 | 500 |
Pro | 200 | 2.000 |
Business | 500 | 5.000 |
Boas Práticas de Segurança
Nunca exponha chaves API em código frontend ou repositórios públicos
Use variáveis de ambiente para armazenar chaves
Rotacione as chaves API periodicamente
Use apenas HTTPS para requisições da API
Monitore os logs da API para atividades incomuns (/dashboard/logs)
Configure alertas para eventos de cota excedida
Monitoramento
Acompanhe o uso da sua API no dashboard:
Logs de API: /dashboard/logs - Todas as requisições da API com códigos de status
Logs de Email: /dashboard/logs - Emails enviados com status de entrega
Uso de Cota: /dashboard - Estatísticas de cota em tempo real
Dicas de Uso
Sempre inclua versões `text` e `html` para melhor entregabilidade
Use headers customizados para melhorar a pontuação anti-spam
Envie emails em lote de forma eficiente - Use BCC para múltiplos destinatários ao invés de múltiplas chamadas da API
Trate limites de taxa graciosamente - Implemente exponential backoff no seu código
Valide emails antes de enviar - Use regex de validação de email apropriado
Exemplo de headers customizados:
json
"headers": { "List-Unsubscribe": "<mailto:[email protected]>", "X-Entity-Ref-ID": "unique-id-12345" }
Solução de Problemas
"SMTP password not configured"
Mailbox foi criado antes da funcionalidade de senha SMTP
Solução:
Deletar e recriar o mailbox
"SMTP password decryption failed"
A chave de criptografia foi alterada ou corrompida
Solução:
Contatar suporte ou recriar mailboxes
"Too many requests"
Atingindo limite de taxa
Solução:
Aguardar o tempo de reset ou fazer upgrade do plano
"Daily/Monthly limit exceeded"
Cota esgotada
Solução:
Aguardar o reset ou comprar emails adicionais
