Pular para o conteúdo principal

Enviar Email

Os envios transacionais de Email consistem no envio de um Email para um ou mais destinatários que não pertencem à audiência da organização. Como tal, não dependem de um schema previamente definido para a audiência de contactos.

Estes envios permitem a configuração de webhooks. Webhooks são endpoints, parametrizados pelo cliente em cada envio transacional de Email, que serão invocados pela Arpoone para encaminhamento de informação de eventos relativos à actividade do Email enviado;

O endpoint impõe as seguintes limitações:

  • Número máximo de 10 Emails por HTTP request à API da Arpoone, parametrizáveis no campo messages;
  • O tamanho total de cada Email, com anexos, não poderá exceder os 10MB (megabytes). Caso este valor seja excedido, será retornado o erro: PAYLOAD_EXCEEDS_MAX_SIZE;
  • Tamanho total do pedido HTTP não pode exceder 30 MB (megabytes).

Domínios (domain senders)​

Os domínios, domain senders, são os domínios dos remetentes utilizados nos Emails enviados (por exemplo:@arpoone.com). A execução do envio transacional de Email pressupõe a configuração prévia do domain sender utilizado no remetente do envio.

Esta configuração consiste nos seguintes passos:

  • Efectuar a criação do domain sender na plataforma Arpoone
    • Acedido através de: Fotografia de Perfil → Configurações → Remetentes → Domínios de Email;
  • Configurar os valores de DKIM, SPF e Ownership Token no DNS do domínio pretendido – contacte a equipa de suporte para mais informações.

Payload​

Exemplo de payload de envio de Email, com destinatários CC/BCC, webhooks e anexos:

{
    "organizationId": <uuidv4> (Guid),
    "messages": [
        {
            "to": [ ]<string[]> (array de strings),
            "cc": [ ]<string[]> (array de strings),
            "bcc": [ ]<string[]> (array de strings),
            "from": <string>>,
            "displayName": <string>,
            "subject": <string>,
            "textContent": <string>,
            "htmlContent": <string>,
            "expirationDateTime": <datetime>,
            "emailWebhooks": {
                "bounced": {
                    "url": <string>,
                    "enabled": <bool>
                },
                "clicked": {
                    "url": <string>,
                    "enabled": <bool>
                },
                "opened": {
                    "url": <string>,
                    "enabled": <bool>
                },
                "spam": {
                    "url": <string>,
                    "enabled": <bool>
                },
                "unsubscribed": {
                    "url": <string>,
                    "enabled": <bool>
                }
            },
            "attachments": [
                {
                    "mimeType": <string>,
                    "name": <string>,
                    "base64Content": <string> (base64)
                }
            ]
        },
        ...
    ]
}

Parametrização​

A propriedade Messages do payload é um array, logo, permite o envio de vários Emails apartir de um só pedido HTTP.

Descrição dos campos:

  • to – os destinatários primários do Email;
  • cc – os destinatários carbon-copy do Email;
  • bcc – os destinatários blind carbon-copy do Email;
  • from - remetente do Email – esta propriedade deve conter um email válido, cujo domínio deve ser previamente configurado:
    • Por exemplo: se existir um domain sender @arpoone.com configurado, então a propriedade from será "[endereço]@arpoone.com;
    • Se o domain sender não estiver configurado e confirmado, será retornado código de erro FROM_NOT_ALLOWED;
  • displayName - nome do remetente do Email;
  • textContent - conteúdo do Email em formato de texto simples;
  • htmlContent - conteúdo do Email, em formato HTML;
  • expirationDateTime - data-limite, no fuso horário UTC, na qual o Email é enviado – no caso de haver algum atraso temporário nos envios de Emails por parte da plataforma, se a data atual exceder a configurada nesta propriedade, o Email não é enviado;
  • emailWebhooks - endereços URL de destino para notificações de eventos de Email (ver página Email Webhooks). A especificação destes endereços é opcional;
  • attachments - ficheiros a serem enviados no email como anexo.

Por favor, tenha em atenção que existe um limite cumulativo de 50 destinatários (a soma de To, CC e BCC) por cada e-mail individual.

Anexos​

A funcionalidade de envio de anexos carece de activação prévia pela equipa comercial.

O envio de Email transacional suporta a anexação de ficheiros, codificados em base64. Para tal, deverá incluir a propriedade attachments (array). Cada item no array attachments tem de conter 3 propriedades: mimeType, name e base64Content.

Aplicam-se as seguintes restrições:

  • As propriedades mimeType e name não podem exceder os 128 caracteres;
  • A propriedade mimeType deverá ser adequada ao anexo que está codificado em base64 – ao mesmo tempo, a propriedade name deverá conter a correta extensão do ficheiro (no exemplo abaixo, .jpg).

Exemplo de configuração de anexos:

...
"attachments":
[
    {
        "mimeType": "image/jpeg",
        "name": "img.jpg",
        "base64Content": "/9j/4AAQSkZJRgABAQEAYABgAA..."
    }
]
...

Resposta​

De forma semelhante ao corpo do pedido do endpoint de Email transacional, a resposta também contém um array messages. Dentro de cada item em messages, haverá uma propriedade status, juntamente com três arrays de objetos que contêm os identificadores de cada destinatário configurado nos campos To / Cc / Bcc do pedido.

O endpoint de Email transacional devolve o Código de Estado HTTP 200 (HTTP OK) se não houver nenhum erro que impeça o processamento do pedido. A indicação de sucesso/erro para cada mensagem é feita no corpo da resposta, dentro de cada item do array messages, sob a propriedade status.

A propriedade status reflete se o email foi enviado com sucesso ou não, a propriedade cost indica o valor deduzido do saldo da organização, e a propriedade error fornece detalhes caso ocorra algum erro.

Exemplo:

{
    "error": null,
    "messages": [
        {
            "status": "SUCCESS",
            "to": [
                {
                    "email": "example@sendit.pt",
                    "messageId": "6ab84ad8-ef9d-45fa-bc4f-fa54edb135b7"
                }
            ],
            "cc": [
                {
                    "email": "example+cc@sendit.pt",
                    "messageId": "76326eca-600f-4b77-8288-f11fb9491628"
                }
            ],
            "bcc": [
                {
                    "email": "example+bcc@sendit.pt",
                    "messageId": "b6a83257-40a0-486f-b369-ff73297b1ec9"
                }
            ],
            "cost": {
                "amount": 3
            },
            "error": null
        }
    ]
}

Erros​

Em situações de erro, a propriedade error dentro de cada item do array messages (na resposta) será populada com um objeto que contém informações sobre o erro ocorrido:

"error":
{
    "code": "PARAM_EXCEEDS_MAX_LENGTH",
    "param": "DisplayName",
    "description": ""
}

A propriedade code especifica que tipo de erro ocorreu sendo que a propriedade param especifica qual o parâmetro do payload de envio de Email que causou o erro.

A lista completa de códigos de erro pode ser consultada neste link

Aceder à API Reference