Ir para o conteúdo

Objeto de e-mail

O objeto email permite que você modifique ou crie e-mails por meio dos nossos endpoints de envio de mensagens.

Objeto de e-mail

{
  "app_id": (required, string), see App Identifier,
  "subject": (optional, string),
  "from": (required, valid email address in the format "Display Name <[email protected]>"),
  "reply_to": (optional, valid email address in the format "[email protected]" - defaults to your workspace's default reply to if not set) - use "NO_REPLY_TO" to set reply-to address to null,
  "bcc": (optional, one of the BCC addresses defined in your workspace's email settings) if provided and the BCC feature is enabled for your account, this address gets added to your outbound message as a BCC address,
  "body": (required unless email_template_id is given, valid HTML),
  "plaintext_body": (optional, valid plaintext, defaults to autogenerating plaintext from "body" when this is not set),
  "preheader": (optional*, string) recommended length 50-100 characters,
  "email_template_id": (optional, string) if provided, Braze uses the subject/body/should_inline_css values from the given email template UNLESS they are specified here, in which case Braze overrides the provided template,
  "message_variation_id": (optional, string) used when providing a campaign_id to specify which message variation this message should be tracked under,
  "extras": (optional, valid Key-Value Hash) extra hash - for SendGrid users, this is passed to SendGrid as Unique Arguments,
  "headers": (optional, valid Key-Value Hash) hash of custom extensions headers (available for SparkPost, SendGrid, or Amazon SES),
  "should_inline_css": (optional, boolean) whether to inline CSS on the body. If not provided, falls back to the default CSS inlining value for the workspace,
  "attachments": (optional, array) array of JSON objects that define the files you need attached, defined by "file_name", "url", and optionally "basic_auth_credential",
    "file_name": (required, string) the name of the file you want to attach to your email, excluding the extension (for example, ".pdf"). Attach files up to 2 MB. This is required if you use "attachments",
    "url": (required, string) the corresponding URL of the file you want to attach to your email. The file name's extension is detected automatically from the URL defined, which should return the appropriate "Content-Type" as a response header. This is required if you use "attachments",
    "basic_auth_credential": (optional, string) the name of the stored basic authentication credential to use when the attachment URL requires a login,
}
  • Identificador do app
    • Qualquer app_id válido de um app configurado no seu espaço de trabalho funciona para todos os usuários do espaço de trabalho, independentemente de o usuário ter ou não o app específico no perfil.
  • Para saber mais sobre pré-cabeçalhos e as práticas recomendadas, consulte Estilo de e-mail.

Os tipos de anexo válidos são: txt, csv, log, css, ics, jpg, jpe, jpeg, gif, png, bmp, psd, tif, tiff, svg, indd, ai, eps, doc, docx, rtf, odt, ott, pdf, pub, pages, mobi, epub, mp3, m4a, m4v, wma, ogg, flac, wav, aif, aifc, aiff, mp4, mov, avi, mkv, mpeg, mpg, wmv, xls, xlsx, ods, numbers, odp, ppt, pptx, pps, key, zip, vcf e pkpass.

Você encontra o email_template_id na parte inferior de qualquer modelo de e-mail criado com o editor de HTML. Veja a seguir um exemplo de como é esse ID:

Seção de identificador de API de um modelo de e-mail em HTML.

Exemplo de objeto de e-mail com anexo

{
  "external_user_ids": ["YOUR_EXTERNAL_USER_ID"],
  "messages":{
     "email":{
        "app_id":"YOUR_APP_ID",
        "attachments":[{
            "file_name":"YourFileName",
            "url":"https://exampleurl.com/YourFileName.pdf"
         }]
     }
  }
}

Autenticação para anexos de arquivos de e-mail

Use uma credencial de autenticação básica armazenada quando o URL de um anexo exigir login. Isso se aplica aos anexos no objeto de e-mail em /messages/send e ao array attachments de nível superior em /campaigns/trigger/send.

  1. Acesse Configurações > Gerenciamento de credenciais.
  2. Selecione Adicionar credencial.
  3. Selecione Autenticação básica.
  4. Insira um nome para a credencial, um nome de usuário e uma senha.
  5. Inclua uma propriedade basic_auth_credential em cada anexo que exige autenticação e defina-a com o nome dessa credencial. O exemplo a seguir usa o nome de credencial company_basic_auth_credential_name em um objeto de e-mail:
{
  "external_user_ids": ["recipient_user_id"],
  "messages":{
    "email":{
      "app_id": "153e8a29-fd6d-4f77-ade7-1a4ca08d457a",
      "subject": "Basic auth attachment test",
      "from": "mail <[email protected]>",
      "body": "my attachment test",
      "attachments":[
        { "file_name":"checkout_receipt.pdf",
        "url":"https://fileserver.company.com/user123-checkout_receipt.pdf",
        "basic_auth_credential": "company_basic_auth_credential_name" }
      ]
    }
  }
}

Recuperação, cache e performance de anexos

Quando a Braze busca um arquivo a partir de uma url de anexo:

  • Cache: A Braze pode reutilizar um arquivo recuperado recentemente por até aproximadamente 24 horas. Se você precisar que cada envio use imediatamente uma nova versão do arquivo, use uma URL diferente para cada versão (por exemplo, um caminho ou uma consulta que mude quando o arquivo mudar).
  • Tempos limite: Os hosts devem responder rapidamente. Se a URL do anexo estiver lenta ou travar, o envio da mensagem pode falhar. Procure obter respostas em até cerca de dois minutos.
  • Segurança: Não coloque informações pessoais identificáveis (IPI) nem segredos nas URLs de anexos (incluindo strings de consulta), porque as URLs podem aparecer em logs ou em sistemas downstream.
  • Firewalls: Se a URL só puder ser acessada a partir de redes específicas, permita o tráfego da Braze de acordo com a lista de IPs permitidos do Connected Content. Use credenciais de autenticação básica quando o arquivo exigir login.
New Stuff!