Campanha¶
Entidade campanha. Uma campanha é um envio agendado de um conjunto de payloads (Email, SMS).
O <campaign> no URL é o ID numérico da campanha.
Endpoints¶
| Método | URL |
|---|---|
GET |
/campaign/<campaign> |
POST |
/campaign |
PUT |
/campaign/<campaign> |
DELETE |
/campaign/<campaign> |
GET /campaign/<campaign>¶
Payload: Sem payload.
Devolve: A campanha.
Example:
curl -u "username:api_key" -H "Accept: application/json" \
https://app.duo.pt/campaign/{campaign_id}
Response:
{
"success": true,
"data": {
"campaign": {
"id": 1,
"owner": 1,
"list": 1,
"name": "Summer Newsletter 2026",
"domain": 1,
"segments": [],
"recipients": null,
"state": "DRAFT",
"when": {
"date": "2026-06-22 21:54:05.000000",
"timezone_type": 3,
"timezone": "UTC"
},
"event_callback": null
},
"email": null,
"sms": null,
"statistics": {
"delivered": 0,
"bounced": 0,
"opened": 0,
"clicked": 0,
"unsubscribed": 0,
"emails_sent": 0,
"sms_sent": 0,
"sent": 0
}
}
}
O objeto statistics devolve os totais da campanha:
| Campo | Descrição |
|---|---|
emails_sent |
Mensagens de email enviadas por esta campanha |
sms_sent |
Mensagens SMS enviadas por esta campanha |
sent |
Total de mensagens enviadas (emails_sent + sms_sent) |
delivered |
Mensagens com entrega confirmada |
bounced |
Mensagens devolvidas (bounce) |
opened |
Aberturas únicas (apenas email) |
clicked |
Cliques únicos (apenas email) |
unsubscribed |
Remoções de subscrição atribuídas a esta campanha |
Dica
emails_sent e sms_sent dão diretamente o volume por campanha e por canal — não é
preciso percorrer as coleções de eventos para contar mensagens.
POST /campaign¶
| Parâmetro | Tipo | Descrição |
|---|---|---|
name |
string | Nome da campanha |
domain |
int | ID do domínio de bounce (objeto Domain com domínio de bounce activo) |
list |
int | ID da lista de contactos visada pela campanha |
segments[] |
array de int | IDs de segmentos dentro da lista. Pode ocorrer mais do que uma vez. Se nenhum for especificado, a campanha envia para todos os contactos. |
state |
string | Estado da campanha. Estados válidos: DRAFT⮂SCHEDULED⮂READY⇒SENDING⇒(DONE\|ERROR) |
when |
timestamp | Hora de envio agendada. Timestamp Unix (int) ou string ISO 8601. |
event_callback |
string | Opcional. URL chamado quando ocorrem eventos. |
Nota
A transição de DRAFT para outro estado requer que o domínio tenha DNS validado (DKIM, SPF, bounce). A API aceita o PUT sem erro mas mantém o estado inalterado se o domínio não estiver totalmente configurado.
Devolve: A nova campanha.
Example:
curl -u "username:api_key" -H "Accept: application/json" \
-d "name=My+Campaign&domain={domain_id}&list={list_id}&state=DRAFT" \
https://app.duo.pt/campaign
Response:
{
"success": true,
"data": {
"list": {
"id": 1,
"owner": 1,
"name": "Example...",
"default_email_out": null,
"unsubscribe_message": "You have been unsubscribed.",
"email_out_custom_fields": null,
"double_optin": false,
"optout_allowed": false,
"optout_category": null,
"optin_email": null,
"optin_sms": null,
"shared_with_children": false,
"read_shared_with_children": false,
"segments": null
},
"campaign": {
"id": 1,
"owner": 1,
"list": 1,
"name": "Summer Newsletter 2026",
"domain": 1,
"segments": null,
"recipients": null,
"state": "DRAFT",
"when": "2026-06-22T21:54:05+00:00",
"event_callback": null
}
}
}
PUT /campaign/<campaign>¶
| Parâmetro | Tipo | Descrição |
|---|---|---|
name |
string | Nome da campanha |
domain |
int | ID do domínio de bounce (objeto Domain com domínio de bounce activo) |
segments[] |
array de int | IDs de segmentos dentro da lista a visar. Pode ocorrer mais do que uma vez. Se nenhum for especificado, a campanha envia para todos os contactos. |
state |
string | Estado da campanha |
when |
timestamp | Hora de envio agendada |
event_callback |
string | Opcional. URL chamado quando ocorrem eventos. |
Devolve: A campanha editada.
Example:
curl -u "username:api_key" -H "Accept: application/json" -X PUT \
-d "name=Updated+Campaign&state=DRAFT" \
https://app.duo.pt/campaign/{campaign_id}
Response:
{
"success": true,
"data": {
"campaign": {
"id": 1,
"owner": 1,
"list": 1,
"name": "Summer Newsletter 2026",
"domain": 1,
"segments": [],
"recipients": null,
"state": "DRAFT",
"when": {
"date": "2026-06-22 21:54:05.000000",
"timezone_type": 3,
"timezone": "UTC"
},
"event_callback": null
}
}
}
DELETE /campaign/<campaign>¶
Payload: Sem payload.
Devolve: A campanha eliminada.
Example:
curl -u "username:api_key" -H "Accept: application/json" -X DELETE \
https://app.duo.pt/campaign/{campaign_id}
Response:
{
"success": true,
"data": {
"campaign": {
"id": 1,
"owner": 1,
"list": 1,
"name": "Summer Newsletter 2026",
"domain": 1,
"segments": [],
"recipients": null,
"state": "DRAFT",
"when": {
"date": "2026-06-22 21:54:05.000000",
"timezone_type": 3,
"timezone": "UTC"
},
"event_callback": null
}
}
}
Comportamento do Callback¶
Se um URL event_callback estiver definido, é executado um pedido POST contra ele sempre que
ocorre um evento no ciclo de vida de uma mensagem.
Eventos¶
| Evento | Descrição |
|---|---|
submitted |
Mensagem submetida para entrega |
delivered |
Mensagem entregue |
bounced |
Falha permanente de entrega |
opened |
Mensagem aberta |
clicked |
Um link na mensagem foi clicado |
Nota
Os payloads SMS apenas geram eventos delivered e bounced. Os payloads de email geram todos os eventos.
O URL event_callback pode conter uma query string — esses parâmetros são reencaminhados sem alterações.
Parâmetros POST do callback¶
| Parâmetro | Tipo | Descrição |
|---|---|---|
event |
string | Qual evento ocorreu |
when |
int | Timestamp Unix do evento |
telephone[] |
array de string | Números de telefone para eventos SMS (telephone[0], telephone[1], ...) |
email[] |
array de string | Emails para eventos de email (email[0], email[1], ...) |
Nota
Os eventos são agregados temporalmente. Prevê-se um atraso de até cinco minutos entre o evento real e a execução do callback.