Skip to main content
POST
/
marketplace
/
messaging
/
send-email
Enviar e-mail
curl --request POST \
  --url http://api.gu1.ai/marketplace/messaging/send-email \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "to": "<string>",
  "fromEmail": "<string>",
  "fromSenderId": {},
  "templateParams": {}
}
'

Documentation Index

Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt

Use this file to discover all available pages before exploring further.

Requer integração Email ativa no marketplace. Visão geral em Mensagens — visão geral.

​
Endpoint

POST https://api.gu1.ai/marketplace/messaging/send-email

​
Cabeçalhos

Authorization: Bearer SUA_API_KEY
Content-Type: application/json
X-Organization-ID: <uuid>   # opcional

​
Corpo

​
to
string
required
E-mail do destinatário.
​
fromEmail
string
Endereço completo (ex.: noreply@meu-dominio.com). O domínio deve estar registrado e verificado na organização (Configurações → E-mail → Domínios). Não é obrigatório cadastrar esse endereço em Remetentes se o domínio já estiver verificado. Exclusivo com fromSenderId.
​
fromSenderId
string (UUID)
UUID do remetente. Exclusivo com fromEmail.
Se omitir fromEmail e fromSenderId, a API usa o remetente padrão da plataforma Gu1. Comportamento esperado, não é erro.

​
Remetente personalizado (fromEmail)

Se enviar fromEmail, por exemplo example@meu-dominio.com, a API valida o domínio (meu-dominio.com) antes do envio. A resposta é 400 com { "success": false, "error": "<mensagem em inglês>" }; o e-mail não é enviado até o domínio estar verificado.
SituaçãoResposta da API
Domínio nunca adicionado na Gu1 para a orgDomain "meu-dominio.com" is not registered in Gu1. Add and verify it under Settings → Email → Domains before using sender "example@meu-dominio.com".
Domínio na Gu1 mas DNS ainda não verificadoDomain "meu-dominio.com" is not verified yet. Complete DNS records and click Verify under Settings → Email → Domains.
Domínio verificadoA requisição segue; qualquer local-part nesse domínio é aceito sem linha em Remetentes. Se o endereço existir em Remetentes, usa-se o nome configurado.
Exemplo de rejeição (domínio não verificado): 
{
  "success": false,
  "error": "Domain \"meu-dominio.com\" is not verified yet. Complete DNS records and click Verify under Settings → Email → Domains."
}
​
templateParams
object
Mapa para {{placeholders}}. Padrão {}.
Modo template: templateId (canal email). Sem htmlBody/textBody. subject opcional como fallback. Modo inline: subject obrigatório; htmlBody e/ou textBody. Sem templateId.

​
Exemplo (inline + variáveis)

{
  "to": "user@example.com",
  "subject": "Seu código: {{token}}",
  "htmlBody": "<p>Código: <strong>{{token}}</strong></p>",
  "templateParams": { "token": "482910" }
}

​
Erros e HTTP

Na maioria dos casos: { "success": false, "error": "<mensagem em inglês>" }. Corpos inválidos podem retornar outro formato (ex.: Zod) com 400. Mensagens de negócio em error são em inglês.
SituaçãoHTTPExemplo de error
Integração Email inativa400Email integration is not active. Enable Email (global_sender_email) in Applications (Marketplace) for this organization.
MS_PROVIDER_URL não configurado400MS_PROVIDER_URL is not configured on the server. Configure the messaging provider to send email.
Custo > 0 sem saldo/pack400Insufficient balance for this send (cost … credits). …
Envio OK, falha ao cobrar400Insufficient balance to record billing for this send. …
templateId + corpo inline400Use either templateId + templateParams, or htmlBody/textBody only — not both.
Sem template nem corpo400Provide templateId or htmlBody/textBody.
Inline sem subject400subject is required when not using a template.
Template inexistente / outra org404Template not found or not accessible for this organization.
Canal do template ≠ email400Template channel is "<channel>"; email is required.
Assunto vazio após variáveis400The template has no subject or it is empty after replacing variables. …
fromSenderId e fromEmail400Send only one of fromSenderId or fromEmail, not both.
fromSenderId inválido400fromSenderId does not match a sender for this organization. …
Domínio do fromEmail não registrado na org400Domain "…" is not registered in Gu1. Add and verify it under Settings → Email → Domains before using sender "…".
Domínio registrado mas DNS não verificado400Domain "…" is not verified yet. Complete DNS records and click Verify under Settings → Email → Domains.
Assunto vazio após {{…}}400Subject is empty after replacing variables.
Corpo vazio após render400htmlBody or textBody is empty after rendering.
Sem org na sessão401{ "error": "Organization ID not found" }
Sempre verifique success e error; o provedor pode responder falha com 200 e success: false.