Aplicações e API

Ligar uma aplicação

Uma aplicação é uma parte do seu software que trabalha com o Mailroomly através das suas próprias chaves. Os administradores ligam aplicações nas Aplicações, que abrem com O que quer fazer?:

• Enviar email a partir da minha aplicação abre Ligar uma aplicação.
• Receber eventos no meu sistema leva ao passo Webhook de uma aplicação. Com várias aplicações, pergunta Que aplicação recebe os eventos?; sem nenhuma, liga primeiro uma.
• Ligar um agente de IA liga um agente que trabalha para a organização (Agentes de IA) ou, com Em seu nome, o seu próprio agente.
• Mudar do Postmark é um guia de três passos para código feito para o Postmark (Mudar do Postmark).
• Mudar do SendGrid é o mesmo para código feito para o SendGrid (Mudar do SendGrid).
• Mudar do Mailgun é o mesmo para código feito para o Mailgun (Mudar do Mailgun).

A seguir vêm As suas aplicações, cada uma com o estado da chave, o número de chaves e Webhook ligado ou Sem webhook, e, recolhido, Para programadores: Entregas de webhooks e Enviar um email de teste em seu nome. O Ctrl K oferece os mesmos objetivos.

O que quer fazer? e as suas aplicações

Antes de uma aplicação enviar, a sua organização precisa de um endereço de envio: um domínio verificado ou o endereço gratuito (Endereços e domínios).

Importante

A chave, que começa por mp_live_, só é mostrada uma vez. Copie-a para a configuração ou o cofre de segredos da aplicação: o Mailroomly guarda apenas um hash e não a consegue mostrar outra vez. O código em Experimente lê-a da variável de ambiente MAILROOMLY_API_KEY, para que copiar o código nunca espalhe a chave.

Aplicações e chaves

Abra uma aplicação em As suas aplicações. A página tem dois separadores, Configurar e Entregas. Configurar tem três passos numerados, cada um marcado Feito quando está:

1. Chave de API (para enviar): se alguma chave já foi usada, e as chaves da aplicação. Feito depois do primeiro pedido de uma chave.
2. Webhook (opcional): para onde o Mailroomly envia os eventos da aplicação (Webhooks).
3. Enviar um teste como esta aplicação: um email enviado como a aplicação, só para si (Enviar um email de teste).

Os passos de uma aplicação, com as suas chaves

Criar uma chave

Dê a cada ambiente e a cada integração a sua própria chave, só com o que precisa. Em Chaves, escolha Criar chave:

1. Um Nome, por exemplo "Produção".

2. As Permissões:

   Permissão	Permite
   Enviar mensagens	Enviar email: a API REST, os endpoints compatíveis com Postmark e o MCP
   Ler a atividade	Pesquisar mensagens e os seus eventos
   Listar endereços	Listar os endereços da organização
   Ler caixas de entrada	Ler as conversas dos endereços
   Responder a partir das caixas	Responder e reencaminhar a partir dos endereços, e deixar rascunhos
   Deixar rascunhos para aprovação	Deixar respostas para uma pessoa enviar, editar ou descartar, e passar conversas às pessoas. Sem Responder a partir das caixas, a chave nunca envia sozinha.
   Ler endereços bloqueados / Gerir endereços bloqueados	Ver / adicionar e remover endereços bloqueados
   Contactos	Adicionar e atualizar contactos e listas, e registar os eventos que iniciam automações (Contactos e listas)
   Campanhas	Tudo o que Contactos permite, e modelos, imagens, newsletters e automações, incluindo o envio. O que a chave inicia espera 15 minutos, enquanto os administradores o podem cancelar (Marketing a partir das suas aplicações e agentes)

3. A que emails acede esta chave? (abaixo).

4. Restringir a tipos de email específicos (opcional): transacional, marketing ou ambos.

5. Um Limite diário de destinatários (opcional): a quantos destinatários a chave pode enviar por dia, para que uma chave exposta ou descontrolada não consuma todo o envio da organização. Deixe-o vazio para Sem limite próprio: os limites da organização continuam a aplicar-se.

6. Escolha Criar chave. Chave criada mostra a chave uma vez, com código de exemplo; copie-a e escolha Já guardei a chave.

A linha de cada chave mostra o limite e a Última utilização, que ajuda a encontrar chaves que ninguém usa. Alterar limite define ou retira o limite diário a qualquer momento. Acima do limite, os envios da chave são recusados até à meia-noite UTC, e os administradores recebem um aviso nesse dia (aviso). O limite conta todos os domínios.

A que emails acede uma chave

Alterar acesso, na linha da chave, altera-o a qualquer momento. A chave mantém o segredo, e a alteração aplica-se a partir do pedido seguinte.

Atenção

Tirar endereços a uma chave faz parar de imediato o que os usa: enviar a partir deles é recusado e o seu email deixa de poder ser lido. Antes de guardar, o Mailroomly lista-os, indica de quais a chave enviou nos últimos 30 dias e quais pertencem à aplicação, e pede a sua confirmação. A leitura de email não aparece aí, por isso um endereço sem envios pode continuar em uso.

Dar mais a uma chave avisa todos os administradores (aviso). Só uma pessoa com sessão iniciada no Mailroomly altera aquilo a que uma chave acede; um agente não pode (o que fica com uma pessoa com sessão iniciada).

Substituir ou revogar uma chave

• Substituir, para uma chave perdida ou exposta: uma chave nova com o mesmo nome, permissões, âmbito e limite diário fica no seu lugar, e a antiga é revogada de imediato. A chave nova é mostrada uma vez. O que ainda usar a chave antiga deixa de funcionar até ter a nova. Se não for possível revogar a antiga, o diálogo avisa que ainda funciona e oferece Revogar a chave antiga.
• Revogar desativa uma chave de imediato.

Atenção

Revogar não pode ser anulado: os pedidos com a chave falham de imediato. Substitua a chave na aplicação antes de revogar a antiga.

Eliminar uma aplicação

Eliminar aplicação revoga de imediato todas as chaves e para os webhooks; as entregas que ainda estavam à espera ficam Falhada. Antes de eliminar uma aplicação responsável por endereços, dê a esses endereços outra aplicação responsável ou um webhook próprio, na página de cada endereço (Endereços e domínios).

Enviar o primeiro email

As aplicações enviam pela API REST, com a chave no cabeçalho Authorization: Bearer. Com a chave na variável de ambiente MAILROOMLY_API_KEY e um remetente no seu domínio verificado:

curl https://app.mailroomly.com/api/v1/messages \
  -H "Authorization: Bearer $MAILROOMLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": "Loja <ola@mail.exemplo.pt>", "to": ["cliente@exemplo.pt"], "subject": "A sua encomenda", "text": "Obrigado pela sua encomenda."}'

O Mailroomly responde 202 com o id da mensagem e "status": "QUEUED": o email foi aceite e segue em segundo plano. Acompanhe-o na Atividade (A página de um envio) ou pelo seu webhook.

• O from tem de ser um endereço num domínio verificado da sua organização, dentro do âmbito da chave.
• Indique um corpo em html, em text, ou ambos. Até 50 destinatários no total (to, cc, bcc).
• Acrescente um idempotencyKey por acontecimento do negócio (por exemplo "fatura-2026-0042"): um pedido repetido devolve o primeiro resultado em vez de enviar duas vezes.
• Os destinatários que bloqueou ficam de fora e aparecem em suppressedRecipients. Quando não sobra nenhum, a resposta é 422 ALL_RECIPIENTS_SUPPRESSED: não tente outra vez.
• Até 500 mensagens de uma vez vão para /api/v1/messages/batch.

Todos os campos, erros e limites estão na referência da API REST (em inglês). O código feito para o Postmark, o SendGrid ou o Mailgun mantém os seus pedidos: Mudar do Postmark, Mudar do SendGrid, Mudar do Mailgun.

Tipos de email

Cada email é de um de dois tipos, e o tipo decide como sai:

• O email transacional passa sempre à frente.
• O email de marketing leva uma ligação e cabeçalhos de cancelamento da subscrição para cada destinatário: ponha {{unsubscribe_url}} no corpo onde a ligação deve aparecer. Envie uma mensagem por destinatário (/api/v1/messages/batch), para que os destinatários não se vejam uns aos outros.
• O marketing exige um plano que o inclua e a aceitação dos termos de serviço por um administrador, não pode ser enviado a partir do endereço gratuito e, a partir do seu domínio, exige o registo DMARC do domínio. Uma conta nova envia marketing em vagas crescentes (Confiança de envio).
• Uma chave pode ficar limitada a um tipo com Restringir a tipos de email específicos.

Campanhas e cancelamentos da subscrição: Campanhas e marketing.

Webhooks

Um webhook diz à sua aplicação o que aconteceu ao email dela: o Mailroomly envia cada evento para um URL seu, assinado para que a aplicação confirme que vem do Mailroomly. Cada aplicação tem um URL de webhook, o seu formato e os eventos que quer.

O segredo de assinatura. Em Detalhes avançados, o Segredo de assinatura (para verificar os webhooks que recebe) começa por whsec_. Não é uma chave de API: o seu endpoint usa-o para confirmar a assinatura que acompanha cada webhook. Mostrar segredo mostra-o. Como confirmar a assinatura, com código: referência dos webhooks (em inglês).

A chave de verificação. Uma aplicação no formato Compatível com SendGrid mostra também, em Detalhes avançados, a sua Chave de verificação (Event Webhook assinado do SendGrid): o seu handler de eventos do SendGrid confirma com ela a assinatura de cada webhook, em vez da chave que o SendGrid lhe deu (Mudar do SendGrid).

A signing key do Mailgun. No formato Compatível com Mailgun, o segredo de assinatura é também a webhook signing key: o seu handler do Mailgun verifica cada webhook com ele, em vez da chave que o Mailgun lhe deu (Mudar do Mailgun).

Atenção

Rodar segredo substitui o segredo de imediato, para todas as entregas a partir daí, incluindo as repetições, e com ele a chave de verificação de uma aplicação compatível com SendGrid. Atualize primeiro o seu endpoint, ou deixe-o aceitar os dois segredos durante algum tempo; a nova chave de verificação coloca-se no handler logo depois de rodar.

O seu endpoint deve responder com um 2xx em menos de 10 segundos e fazer o trabalho depois. Os eventos podem chegar mais de uma vez e fora de ordem: use o id de cada evento para ignorar os repetidos.

Um endereço também pode enviar cada email que recebe para o seu próprio URL do webhook de receção, assinado com o segredo da aplicação responsável e no formato dela (Endereços e domínios).

Entregas e reenvio

Aplicações › Para programadores › Entregas de webhooks mostra todas as entregas aos webhooks das aplicações e dos endereços; o separador Entregas de uma aplicação mostra só as dela. Pode filtrar por estado, aplicação e evento:

Detalhes mostra o conteúdo enviado, as tentativas, o URL para onde foi da última vez e a última resposta do seu endpoint. Para um email recebido, o conteúdo mostrado é uma referência à mensagem: o texto e os anexos são acrescentados de cada vez que é enviada, não ficam guardados com a entrega.

Uma entrega que falha é tentada outra vez 1 minuto depois, e a seguir ao fim de 5 minutos, 30 minutos, 2, 6, 12 e 24 horas. Depois da 8.ª tentativa fica Falhada, e os administradores recebem o aviso Entregas de webhook falhadas (aviso). Um URL que aponta para uma rede interna é recusado, e as suas entregas ficam Falhada de imediato.

As repetições e os reenvios vão sempre para o URL do webhook atual, por isso basta corrigir o URL. Quando o seu endpoint voltar a funcionar, selecione as entregas e escolha Reenviar … selecionadas, ou Reenviar todas as falhadas desta aplicação: voltam à fila e recebem de novo o calendário completo de tentativas. Um agente com Gerir aplicações lista-as com list_webhook_deliveries e reenvia-as com replay_webhooks.

Pedidos

Aplicações › Para programadores › Pedidos mostra todos os pedidos que as suas aplicações e agentes de IA fizeram, pela API ou por MCP, nos últimos 30 dias, do mais recente para o mais antigo: quando, o pedido (o endpoint, ou a ferramenta MCP), o resultado, quem o fez (a aplicação e a chave, ou o token do agente) e quanto demorou. O separador Pedidos de uma aplicação mostra só os dela; em Os meus agentes, Ver os pedidos mostra os de um token.

Todos os pedidos, com o resultado e o motivo de uma falha

Pode filtrar por resultado (Só o que falhou), aplicação ou agente, canal (API ou MCP) e período. Selecione um pedido para ver o código de erro, o motivo em palavras simples, o cliente de onde veio e o ID do pedido; um pedido que enviou um email tem uma ligação para ele. O que um pedido enviou nunca fica guardado com ele: o email guarda o seu próprio conteúdo.

Porque foi recusado, em palavras simples, com os detalhes

Os administradores veem todos os pedidos da organização. As outras pessoas veem os pedidos dos seus próprios agentes, e a chave de uma aplicação ou o token de um agente só lê os seus.

Enviar um email de teste

Há dois testes, para duas perguntas:

Enviar um email de teste envia um email em seu nome. Não pertence a nenhuma aplicação, por isso nunca chega aos webhooks das suas aplicações. Escolha o remetente em De (um dos seus endereços, ou Outro endereço… num domínio verificado), os destinatários, o assunto, o Tipo, o Corpo em HTML, o Corpo em texto ou ambos, e as Etiquetas, e escolha Enviar teste. Email aceite mostra o Estado atual: e Abrir o email e a sua cronologia; os destinatários deixados de fora por estarem bloqueados aparecem listados. Por baixo do formulário, O mesmo email pela API mostra-o em cURL, Node e Python, pronto a correr com a chave de uma aplicação.

Os emails de teste são email real: contam para os limites diários como os outros (Limites diários).

Referências

Para programadores, em inglês:

• REST API: autenticação, envio, mensagens, endereços bloqueados, aplicações e chaves, entregas de webhooks.
• Webhooks: os eventos, os formatos, a assinatura com código, as repetições e o reenvio.
• Postmark compatibility: os endpoints /email e o formato de webhook do Postmark.
• SendGrid compatibility: o endpoint /v3/mail/send, o Event Webhook e o Inbound Parse.
• Mailgun compatibility: os endpoints /v3/{domain}/messages, os webhooks do Mailgun e os reencaminhamentos das suas routes.
• MCP server: as ferramentas que um agente de IA usa.