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": {}
}
'
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
Remetente completo (domínio verificado + remitente cadastrado). Exclusivo com fromSenderId.
​
fromSenderId
string (UUID)
UUID do remitente. Exclusivo com fromEmail.
Se omitir fromEmail e fromSenderId, a API usa o remetente padrão do provedor de mensagens (variáveis de ambiente no servidor, ex.: MS_PROVIDER_FROM_EMAIL / MS_PROVIDER_FROM_NAME, com fallback como SENDGRID_FROM_* ou noreply@gueno.com + Güeno). Comportamento esperado, não é erro.
​
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 não registrado400Domain "…" is not registered in Güeno. …
Domínio não verificado400Domain "…" is not verified yet. …
Remetente não cadastrado400Sender "…" is not configured. …
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.