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": {}
}
'import requests
url = "http://api.gu1.ai/marketplace/messaging/send-email"
payload = {
"to": "<string>",
"fromEmail": "<string>",
"fromSenderId": {},
"templateParams": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({to: '<string>', fromEmail: '<string>', fromSenderId: {}, templateParams: {}})
};
fetch('http://api.gu1.ai/marketplace/messaging/send-email', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/marketplace/messaging/send-email",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'to' => '<string>',
'fromEmail' => '<string>',
'fromSenderId' => [
],
'templateParams' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/marketplace/messaging/send-email"
payload := strings.NewReader("{\n \"to\": \"<string>\",\n \"fromEmail\": \"<string>\",\n \"fromSenderId\": {},\n \"templateParams\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/marketplace/messaging/send-email")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"to\": \"<string>\",\n \"fromEmail\": \"<string>\",\n \"fromSenderId\": {},\n \"templateParams\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/marketplace/messaging/send-email")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"to\": \"<string>\",\n \"fromEmail\": \"<string>\",\n \"fromSenderId\": {},\n \"templateParams\": {}\n}"
response = http.request(request)
puts response.read_bodyReferência API
Enviar e-mail
POST /marketplace/messaging/send-email — e-mail transacional com template ou HTML inline — pela API de mensageria da gu1 para comunicações com clientes.
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": {}
}
'import requests
url = "http://api.gu1.ai/marketplace/messaging/send-email"
payload = {
"to": "<string>",
"fromEmail": "<string>",
"fromSenderId": {},
"templateParams": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({to: '<string>', fromEmail: '<string>', fromSenderId: {}, templateParams: {}})
};
fetch('http://api.gu1.ai/marketplace/messaging/send-email', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/marketplace/messaging/send-email",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'to' => '<string>',
'fromEmail' => '<string>',
'fromSenderId' => [
],
'templateParams' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/marketplace/messaging/send-email"
payload := strings.NewReader("{\n \"to\": \"<string>\",\n \"fromEmail\": \"<string>\",\n \"fromSenderId\": {},\n \"templateParams\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/marketplace/messaging/send-email")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"to\": \"<string>\",\n \"fromEmail\": \"<string>\",\n \"fromSenderId\": {},\n \"templateParams\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/marketplace/messaging/send-email")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"to\": \"<string>\",\n \"fromEmail\": \"<string>\",\n \"fromSenderId\": {},\n \"templateParams\": {}\n}"
response = http.request(request)
puts response.read_bodyRequer integração Email ativa no marketplace. Visão geral em Mensagens — visão geral.
Se omitir Remetente personalizado (
Se enviar
Exemplo de rejeição (domínio não verificado):
Modo template:
Sempre verifique
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
string
required
E-mail do destinatário.
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.string (UUID)
UUID do remetente. Exclusivo com
fromEmail.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ção | Resposta da API |
|---|---|
| Domínio nunca adicionado na Gu1 para a org | Domain "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 verificado | Domain "meu-dominio.com" is not verified yet. Complete DNS records and click Verify under Settings → Email → Domains. |
| Domínio verificado | A 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. |
{
"success": false,
"error": "Domain \"meu-dominio.com\" is not verified yet. Complete DNS records and click Verify under Settings → Email → Domains."
}
object
Mapa para
{{placeholders}}. Padrão {}.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ção | HTTP | Exemplo de error |
|---|---|---|
| Integração Email inativa | 400 | Email integration is not active. Enable Email (global_sender_email) in Applications (Marketplace) for this organization. |
MS_PROVIDER_URL não configurado | 400 | MS_PROVIDER_URL is not configured on the server. Configure the messaging provider to send email. |
| Custo > 0 sem saldo/pack | 400 | Insufficient balance for this send (cost … credits). … |
| Envio OK, falha ao cobrar | 400 | Insufficient balance to record billing for this send. … |
templateId + corpo inline | 400 | Use either templateId + templateParams, or htmlBody/textBody only — not both. |
| Sem template nem corpo | 400 | Provide templateId or htmlBody/textBody. |
Inline sem subject | 400 | subject is required when not using a template. |
| Template inexistente / outra org | 404 | Template not found or not accessible for this organization. |
| Canal do template ≠ email | 400 | Template channel is "<channel>"; email is required. |
| Assunto vazio após variáveis | 400 | The template has no subject or it is empty after replacing variables. … |
fromSenderId e fromEmail | 400 | Send only one of fromSenderId or fromEmail, not both. |
fromSenderId inválido | 400 | fromSenderId does not match a sender for this organization. … |
Domínio do fromEmail não registrado na org | 400 | Domain "…" is not registered in Gu1. Add and verify it under Settings → Email → Domains before using sender "…". |
| Domínio registrado mas DNS não verificado | 400 | Domain "…" is not verified yet. Complete DNS records and click Verify under Settings → Email → Domains. |
Assunto vazio após {{…}} | 400 | Subject is empty after replacing variables. |
| Corpo vazio após render | 400 | htmlBody or textBody is empty after rendering. |
| Sem org na sessão | 401 | { "error": "Organization ID not found" } |
success e error; o provedor pode responder falha com 200 e success: false.Was this page helpful?