Pular para o conteúdo
Docs

Crie versões de templates, publique uma por alias e use-as ao enviar.

URL basehttps://api.emailit.com/v2AutenticaçãoErrosLimites de requisições

Criar um template

Cria uma versão de template. As versões que compartilham um alias pertencem ao mesmo template, e apenas uma versão por alias fica publicada por vez. Quando você envia um e-mail com template definido como um alias, o Emailit usa a versão publicada. Requer uma chave de API com escopo full.

POST/templates

Corpo da requisição

namestringObrigatório

Nome do template exibido no painel. Até 191 caracteres.

aliasstringObrigatório

Identificador que agrupa as versões de um template. Até 191 caracteres; apenas letras minúsculas, números, sublinhados e hifens (^[a-z0-9_-]+$).

Se nenhum template usar este alias ainda, a nova versão é publicada imediatamente. Se o alias já existir, a nova versão é criada sem publicação (published_at é null), e você a publica com Publicar um template.

fromstring

Remetente padrão, por exemplo Acme <hello@acme.com>. Até 191 caracteres.

subjectstring

Linha de assunto padrão. Até 191 caracteres. Pode conter variáveis do Temple, como {{ first_name }}.

reply_tostring | string[]

Endereço de resposta (Reply-To) ou um array de endereços. Cada valor deve ser um endereço de e-mail válido.

htmlstring

Corpo HTML.

textstring

Corpo em texto simples.

sourcestring

Documento-fonte do editor, por exemplo o JSON do Dragit de um template criado no editor de arrastar e soltar. Armazenado como está. Com editor: "mjml", contém o MJML: o Emailit o valida, o armazena como um documento MJML e compila o html a partir dele.

editorstring

Editor ao qual o template pertence: html (padrão), text, dragit ou tiptap. mjml está em alfa e aberto apenas à equipe do Emailit; as outras requisições recebem 403 com error: "mjml_alpha". Consulte Editores e API de MJML.

Retorno

Retorna 201 Created com o template em data e uma message de confirmação. O template inclui html, text e source. O Emailit também envia um evento de webhook template.created.

Os templates MJML também retornam um objeto mjml com as versões do documento. Um MJML inválido retorna 422 com errors.source e diagnostics; consulte Validação.

Se um campo falhar na validação, a resposta é 400 com message: "Validation failed" e um objeto errors com as chaves por campo, por exemplo um alias com letras maiúsculas ou um endereço reply_to inválido. A ausência de name ou alias, ou um valor de editor não permitido, retorna em vez disso o erro de validação 400 padrão, com um array details. Consulte Erros.

POST/templates
Terminal
curl https://api.emailit.com/v2/templates \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome email",
    "alias": "welcome-email",
    "subject": "Welcome to Acme, {{ first_name }}",
    "html": "<h1>Welcome, {{ first_name }}</h1>"
  }'
JSON
{
  "data": {
    "id": "tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a",
    "name": "Welcome email",
    "alias": "welcome-email",
    "from": null,
    "subject": "Welcome to Acme, {{ first_name }}",
    "reply_to": null,
    "html": "<h1>Welcome, {{ first_name }}</h1>",
    "text": null,
    "source": null,
    "editor": "html",
    "published_at": "2026-09-30T10:30:00.482119Z",
    "preview_url": null,
    "created_at": "2026-09-30T10:30:00.482119Z",
    "updated_at": "2026-09-30T10:30:00.482119Z"
  },
  "message": "Template was successfully created."
}

Obter um template

Retorna uma versão de template, incluindo o conteúdo dela, e lista as outras versões do mesmo alias em versions. Os templates são buscados apenas pelo ID, não pelo alias. Requer uma chave de API com escopo full.

GET/templates/:id

Parâmetros de caminho

idstringObrigatório

ID do template, por exemplo tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a.

Retorno

Retorna 200 OK com o template em data. Além dos campos do template, a resposta tem um array versions com id, name, published_at, created_at e updated_at de cada uma das outras versões que compartilham o alias, das mais recentes para as mais antigas. A versão publicada é a que tem published_at não nulo.

Retorna 404 com message: "Template not found" se o ID não existir no seu workspace.

GET/templates/{id}
Terminal
curl https://api.emailit.com/v2/templates/tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "data": {
    "id": "tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a",
    "name": "Welcome email",
    "alias": "welcome-email",
    "from": "Acme <hello@acme.com>",
    "subject": "Welcome to Acme, {{ first_name }}",
    "reply_to": ["support@acme.com"],
    "html": "<h1>Welcome, {{ first_name }}</h1>",
    "text": "Welcome, {{ first_name }}",
    "source": null,
    "editor": "html",
    "published_at": "2026-09-30T10:30:00.482119Z",
    "preview_url": null,
    "created_at": "2026-09-28T08:12:45.103882Z",
    "updated_at": "2026-09-30T10:30:00.482119Z",
    "versions": [
      {
        "id": "tem_2xKyB4qLm7RtV9sNd3HwEa6uC1f",
        "name": "Welcome email (October)",
        "published_at": null,
        "created_at": "2026-09-30T14:02:11.550731Z",
        "updated_at": "2026-09-30T14:02:11.550731Z"
      }
    ]
  }
}

Atualizar um template

Atualiza uma versão de template. Envie apenas os campos que você quer alterar. A versão mantém o estado de publicação: uma versão publicada continua publicada e um rascunho continua rascunho. Requer uma chave de API com escopo full.

POST/templates/:id

Parâmetros de caminho

idstringObrigatório

ID do template, por exemplo tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a.

Corpo da requisição

namestring

Nome do template. Até 191 caracteres.

aliasstring

Novo alias. Até 191 caracteres; apenas letras minúsculas, números, sublinhados e hifens. Não pode ser um alias que outro template já usa.

fromstring

Remetente padrão, por exemplo Acme <hello@acme.com>. Até 191 caracteres. Envie uma string vazia para limpá-lo.

subjectstring

Linha de assunto padrão. Até 191 caracteres. Envie uma string vazia para limpá-la.

reply_tostring | string[]

Endereço de resposta (Reply-To) ou array de endereços. Envie uma string vazia para limpá-lo.

htmlstring

Corpo HTML.

textstring

Corpo em texto simples.

sourcestring

Documento-fonte do editor, por exemplo o JSON do Dragit. Em um template MJML, contém o MJML completo: o Emailit o valida e recompila o html, e qualquer html que você enviar é ignorado.

editorstring

html, text, dragit ou tiptap. mjml está em alfa e aberto apenas à equipe do Emailit; alterar o conteúdo de um template MJML sem acesso ao MJML retorna 403 com error: "mjml_alpha". Renomear ou publicar o template funciona para todos. Consulte Editores e API de MJML.

Retorno

Retorna 200 OK com o template atualizado em data e uma message de confirmação. O Emailit também envia um evento de webhook template.updated.

Retorna 400 com message: "Validation failed" e um objeto errors quando um valor é inválido, por exemplo "Alias already exists". Valores com mais de 191 caracteres ou um editor desconhecido retornam o erro de validação 400 padrão. Retorna 404 se o template não existir.

Para que esta versão seja a usada nos envios, chame Publicar um template.

POST/templates/{id}
Terminal
curl -X POST https://api.emailit.com/v2/templates/tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Welcome aboard, {{ first_name }}"}'
JSON
{
  "data": {
    "id": "tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a",
    "name": "Welcome email",
    "alias": "welcome-email",
    "from": "Acme <hello@acme.com>",
    "subject": "Welcome aboard, {{ first_name }}",
    "reply_to": ["support@acme.com"],
    "html": "<h1>Welcome, {{ first_name }}</h1>",
    "text": "Welcome, {{ first_name }}",
    "source": null,
    "editor": "html",
    "published_at": "2026-09-30T10:30:00.482119Z",
    "preview_url": null,
    "created_at": "2026-09-28T08:12:45.103882Z",
    "updated_at": "2026-10-01T09:15:27.640000Z"
  },
  "message": "Template was successfully updated."
}

Listar templates

Retorna a versão publicada de cada template, dos mais recentes para os mais antigos. As versões não publicadas não são listadas; obtenha um template para ver todas as versões do alias dele. Requer uma chave de API com escopo full.

GET/templates

Parâmetros de consulta

pageinteger

Número da página, a partir de 1. Padrão: 1.

per_pageinteger

Templates por página, de 1 a 100. Padrão: 25.

include_contentboolean

Defina como true para incluir html, text e source em cada template. Omitidos por padrão para manter as respostas pequenas.

filter[name]string

Correspondência parcial, sem diferenciar maiúsculas de minúsculas, no nome ou no alias do template.

filter[alias]string

Alias exato.

filter[editor]string

Editor: html, text, dragit, tiptap ou mjml (alfa).

matchstring

all (padrão) exige que todos os filtros key.condition correspondam. or aceita qualquer um deles. Consulte Filtragem.

sortstring

Chave de ordenação: name, alias, created_at (padrão), updated_at ou published_at.

orderstring

Direção da ordenação: asc ou desc (padrão).

Filtros

Os filtros de listagem são um único nível de parâmetros de consulta key.condition=value. Consulte Filtragem para match, order, direction e a lista de condições por tipo.

Chaves de filtro

ChaveTipoCondiçõesObservações
namestringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
aliasstringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
editorstringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
subjectstringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
created_atdateexact, before, after, empty, not_empty

Chaves de ordenação

Este endpoint ordena com sort definido como uma destas chaves e order definido como asc ou desc (aqui, order=<key> retorna 400): name, alias, editor, subject, created_at

Neste endpoint, order só aceita asc ou desc. Passe a chave de ordenação em sort, por exemplo sort=name&order=asc.

Retorno

Retorna 200 OK com os templates em data e os campos de paginação total_records, per_page, current_page e total_pages. Cada template inclui total_versions, o número de versões que compartilham o alias dele.

GET/templates
Terminal
curl https://api.emailit.com/v2/templates \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "data": [
    {
      "id": "tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a",
      "name": "Welcome email",
      "alias": "welcome-email",
      "from": "Acme <hello@acme.com>",
      "subject": "Welcome to Acme, {{ first_name }}",
      "reply_to": ["support@acme.com"],
      "editor": "html",
      "published_at": "2026-09-30T10:30:00.482119Z",
      "preview_url": null,
      "total_versions": 3,
      "created_at": "2026-09-28T08:12:45.103882Z",
      "updated_at": "2026-09-30T10:30:00.482119Z"
    }
  ],
  "total_records": 1,
  "per_page": 25,
  "current_page": 1,
  "total_pages": 1
}

Publicar um template

Publica uma versão de template e despublica todas as outras versões com o mesmo alias, em uma única transação. Use-o para colocar um novo rascunho no ar ou para voltar a uma versão anterior. Requer uma chave de API com escopo full.

POST/templates/:id/publish

Parâmetros de caminho

idstringObrigatório

ID da versão a publicar, por exemplo tem_2xKyB4qLm7RtV9sNd3HwEa6uC1f.

Corpo da requisição

Sem corpo. Publicar uma versão já publicada define um novo published_at.

Retorno

Retorna 200 OK com o template publicado em data e uma message de confirmação. Retorna 404 se o template não existir.

O Emailit envia um evento de webhook template.updated para a versão que você publicou e um para cada versão que foi despublicada.

POST/templates/{id}/publish
Terminal
curl -X POST https://api.emailit.com/v2/templates/tem_2xKyB4qLm7RtV9sNd3HwEa6uC1f/publish \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "data": {
    "id": "tem_2xKyB4qLm7RtV9sNd3HwEa6uC1f",
    "name": "Welcome email (October)",
    "alias": "welcome-email",
    "from": "Acme <hello@acme.com>",
    "subject": "Welcome to Acme, {{ first_name }}",
    "reply_to": ["support@acme.com"],
    "html": "<h1>Welcome, {{ first_name }}</h1><p>Here is your October guide.</p>",
    "text": "Welcome, {{ first_name }}. Here is your October guide.",
    "source": null,
    "editor": "html",
    "published_at": "2026-10-01T09:20:04.118502Z",
    "preview_url": null,
    "created_at": "2026-09-30T14:02:11.550731Z",
    "updated_at": "2026-10-01T09:20:04.118000Z"
  },
  "message": "Template was successfully published."
}

Excluir um template

Exclui permanentemente uma versão de template. As outras versões do mesmo alias são mantidas. Requer uma chave de API com escopo full.

DELETE/templates/:id

Parâmetros de caminho

idstringObrigatório

ID do template, por exemplo tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a.

Retorno

Retorna 200 OK com data: null e uma message de confirmação. O Emailit envia um evento de webhook template.deleted com a versão excluída. Retorna 404 se o template não existir.

Se você excluir a versão publicada, nenhuma versão desse alias fica publicada até que você publique outra, e os envios com esse alias falham. Excluir um rascunho não afeta a versão publicada. A exclusão não pode ser desfeita.

DELETE/templates/{id}
Terminal
curl -X DELETE https://api.emailit.com/v2/templates/tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "data": null,
  "message": "Template was successfully deleted."
}

Esta página foi útil?

Obrigado pelo feedback.

Obrigado, lemos todas as mensagens.