API reference
Audiences and contacts
Audiences and their contacts, with bulk import.
List audiences
GET
https://api.coffeemail.com.br/v1/product/audiences200Query parameters
limitstring- Quantidade máxima de itens retornados
offsetstring- Quantidade de itens a pular
Create audience
POST
https://api.coffeemail.com.br/v1/product/audiences201Request body
namestring≥ 1≤ 200required- Nome da audiência
descriptionstring≤ 1000- Descrição da audiência
Response 201
idstring (uuid)required- Identificador único da audiência
namestringrequired- Nome da audiência
descriptionstringrequired- Descrição da audiência
activebooleanrequired- Se a audiência está ativa
contactsCountintegermín. 0máx. 9007199254740991required- Quantidade de contatos na audiência
suppressedCountintegermín. 0máx. 9007199254740991- Contatos da audiência que estão suprimidos ou descadastrados (só no detalhe)
createdAtstring (date-time)required- Data de criação da audiência
updatedAtstring (date-time)required- Data da última atualização da audiência
Get audience
GET
https://api.coffeemail.com.br/v1/product/audiences/{id}200Path parameters
idstring≥ 1required- Identificador da audiência
Update audience
PUT
https://api.coffeemail.com.br/v1/product/audiences/{id}200Path parameters
idstring≥ 1required- Identificador da audiência
Request body
namestring≥ 1≤ 200- Novo nome da audiência
descriptionstring≤ 1000- Nova descrição da audiência
activeboolean- Se a audiência está ativa
Delete audience
DELETE
https://api.coffeemail.com.br/v1/product/audiences/{id}200Path parameters
idstring≥ 1required- Identificador da audiência
List contacts
GET
https://api.coffeemail.com.br/v1/product/audiences/{id}/contacts200Path parameters
idstring≥ 1required- Identificador da audiência
Query parameters
limitstring- Quantidade máxima de itens retornados
offsetstring- Quantidade de itens a pular
Response 200
contactsarray<object>required- Lista de contatos
totalintegermín. 0máx. 9007199254740991required- Total de contatos encontrados
Add contact
POST
https://api.coffeemail.com.br/v1/product/audiences/{id}/contacts201Path parameters
idstring≥ 1required- Identificador da audiência
Request body
emailstring (email)required- Endereço de e-mail do contato
firstNamestring≤ 200- Primeiro nome do contato
lastNamestring≤ 200- Sobrenome do contato
metadataobject- Dados extras do contato em formato livre
Response 201
idstring (uuid)required- Identificador único do contato
emailstringrequired- Endereço de e-mail do contato
firstNamestringrequired- Primeiro nome do contato
lastNamestringrequired- Sobrenome do contato
metadataobjectrequired- Dados extras do contato em formato livre
subscribedbooleanrequired- Indica se o contato ainda recebe broadcasts (false após descadastro)
source"api" | "csv" | "manual"- Origem do contato: api, csv (importação) ou manual (painel)
status"subscribed" | "unsubscribed" | "suppressed"- subscribed, unsubscribed (descadastrou) ou suppressed (bounce, reclamação etc.)
suppressionReasonstring- Motivo da supressão quando status = suppressed
createdAtstring (date-time)required- Data de criação do contato
Import contacts
POST
https://api.coffeemail.com.br/v1/product/audiences/{id}/contacts/bulk200Path parameters
idstring≥ 1required- Identificador da audiência
Request body
contactsarray<object>1+ itensaté 10000 itensrequired- Lista de contatos para adicionar em lote
source"api" | "csv" | "manual"- Origem dos contatos; o painel envia csv na importação
Response 200
insertedintegermín. 0máx. 9007199254740991required- Quantidade de contatos inseridos com sucesso
skippedintegermín. 0máx. 9007199254740991required- Quantidade de contatos ignorados
createdintegermín. 0máx. 9007199254740991required- Quantidade de contatos novos criados na organização
existingintegermín. 0máx. 9007199254740991required- Quantidade de contatos que já existiam na organização e foram atualizados
errorsarray<object>required- Lista de erros ocorridos durante a inserção em lote
Update contact
PUT
https://api.coffeemail.com.br/v1/product/audiences/{id}/contacts/{contactId}200Path parameters
idstring≥ 1required- Identificador da audiência
contactIdstring≥ 1required- Identificador do contato
Request body
firstNamestring≤ 200- Novo primeiro nome do contato
lastNamestring≤ 200- Novo sobrenome do contato
metadataobject- Dados extras do contato em formato livre
Remove contact
DELETE
https://api.coffeemail.com.br/v1/product/audiences/{id}/contacts/{contactId}200Path parameters
idstring≥ 1required- Identificador da audiência
contactIdstring≥ 1required- Identificador do contato