Envío usando HTTP
La API HTTP permite enviar un contenido a uno o varios destinatarios con un sólo POST, utilizar variables de reemplazo para personalizarlos, e incluir etiquetas y atributos para su seguimiento.

Ejemplo básico

Empecemos por el ejemplo más sencillo posible:
1
curl -X POST \
2
https://transactional.myperfit.com/v1/mail/send \
3
-H 'Authorization: MI_API_KEY' \
4
-H 'Content-Type: application/json' \
5
-d '{
6
"from": { "email": "[email protected]" },
7
"subject": "Asunto de prueba",
8
"content": {"html": "<h1>Funciona! 💪</h1>"},
9
"recipients": [{"to": {"email": "[email protected]"}}]
10
}'
Copied!

Ejemplo usando una plantilla

Otra forma de indicar el contenido es utilizando una plantilla diseñada en la aplicación web, donde ya incluyen el remitente asunto y contenido.
1
curl -X POST \
2
https://transactional.myperfit.com/v1/mail/send \
3
-H 'Authorization: MI_API_KEY' \
4
-H 'Content-Type: application/json' \
5
-d '{
6
"template_id": "etpl_efd23wnfo23edsoirsnde",
7
"recipients": [{"to": {"email": "[email protected]"}}]
8
}'
Copied!
post
https://transactional.myperfit.com/v1
/mail/send
/mail/send

Estructura del mensaje

Los únicos parámetros requeridos del body son: from.email, subject, content (al menos uno: html o text) y recipients (al menos uno, incluyendo al menos to.email).
  • from: Object, requerido. Email y nombre del remitente.
    • email: String, requerido.
    • name: String, opcional.
  • reply_to: Object, opcional. Dirección y nombre de respuesta.
    • email: String, requerido.
    • name: String, opcional.
  • subject: String, requerido, max 200 chars. Asunto del correo.
  • content: Object, requerido. Se debe indicar al menos un tipo.
    • html: String, opcional, max 300KB. Contenido de tipo text/html.
    • text: String, opcional, max 300KB. Contenido de tipo text/plain.
  • template_id: String, opcional. El id de la plantilla a utilizar, en lugar de indicar el content. En caso de usar una plantilla, dejan de ser requeridos los campos from, reply_to, subject y content. En caso de indicar alguno de ellos, sus valores reemplazarán a los definidos en la plantilla.
  • attachments: Array de objects, opcional.
    • file_name: String, requerido. Nombre del archivo adjunto.
    • mime_type: String, requerido. Tipo mime del archivo adjunto.
    • data: String, requerido. Contenido del archivo adjunto en base64.
  • headers: Object, opcional. Mapa string-string con headers adicionales a incluir.
  • recipients: Array de objetos, requerido. Debe contener al menos un elemento.
    • to: Object, requerido. Email y nombre del destinatario.
      • email: String, requerido.
      • name: String, opcional.
    • cc: Array de objects, opcional. Listado de destinatarios en copia.
      • email: String, requerido.
      • name: String, opcional
    • bcc: Array de objects, opcional. Misma estructura que el cc. Listado de destinatarios en copia oculta.
    • substitutions: Object, opcional. Modelo de reemplazo asociado a este destinatario.
    • custom_args: Object, opcional. Mapa string-string con información de identificación y seguimiento. Se informarán junto con los eventos de monitoreo.
    • tags: Array de strings, opcional. Etiquetas de identificación y seguimiento de este batch. Se informarán junto con los eventos de monitoreo.
  • substitutions: Object, opcional. Modelo de reemplazo asociado a todo el batch.
  • tracking: Object, opcional.
    • open: Object, opcional.
      • enable: Boolean, opcional, default: true. Activar monitoreo de aperturas.
    • click: Object, opcional.
      • enable: Boolean, opcional, default: true Activar monitoreo de clicks.
    • ganalytics: Object, opcional. Códigos de seguimiento para Google Analytics.
      • utm_source: String, opcional.
      • utm_medium: String, opcional.
      • utm_campaign: String, opcional.
      • utm_content: String, opcional.
      • utm_term: String, opcional.
  • batch_code: String, opcional. Identificador alfanumérico (se limpan todos los caracteres que no sean [a-z0-9]).
  • tags: Array de strings, opcional. Etiquetas de identificación y seguimiento de este batch. Se informarán junto con los eventos de monitoreo.
  • launch_date: Fecha. Posponer el envío de este batch hasta la fecha y hora indicadas. Si no se indica se envía en forma inmediata.
Este objeto JSON incluye todas las opciones mencionadas.
1
{
2
"from": {
3
"email": "[email protected]",
4
"name": "Diego"
5
},
6
"reply_to": {
7
"email": "[email protected]",
8
"name": "Diego"
9
},
10
"subject": "Hola ${contact.first_name}, este es el asunto",
11
"content": {
12
"html": "<!DOCTYPE ...><html><body><h1>Hola mundo!</h1></body></html>",
13
"text": "Contenido de tipo texto"
14
},
15
"headers": {
16
"X-My-Header": "my custom header value"
17
},
18
"recipients" : [
19
{
20
"to": {
21
"email": "[email protected]",
22
"name": "Nombre Recipient"
23
},
24
"cc": [
25
{
26
"email": "[email protected]",
27
"name": "Nombre CC1"
28
},
29
{
30
"email": "[email protected]",
31
"name": "Nombre CC2"
32
}
33
],
34
"bcc": [
35
{
36
"email": "[email protected]",
37
"name": "Nombre BCC1"
38
},
39
{
40
"email": "[email protected]",
41
"name": "Nombre BCC2"
42
},
43
],
44
"substitutions": {
45
"contact": {
46
"email": "[email protected]",
47
"name": "Diego",
48
"gender": "M",
49
"age": 35,
50
"ciudad": "Buenos Aires",
51
}
52
},
53
"custom_args": {
54
"internal_id": "43231312",
55
"other_attr": "1234"
56
},
57
"tags": ["cliente frecuente"]
58
}
59
],
60
"substitutions": {
61
"account": {
62
"business_name": "Perfit",
63
"address": "San Nicolas 3940, CABA, Argentina",
64
}
65
},
66
"attachments": [
67
{
68
"file_name": "file.png",
69
"mime_type": "image/png",
70
"data": "base64data"
71
}
72
],
73
"tracking": {
74
"open": {
75
"enable": true
76
},
77
"click": {
78
"enable": true
79
},
80
"ganalytics": {
81
"utm_source": "Perfit",
82
"utm_medium": "email",
83
"utm_campaign": "my campaign"
84
}
85
},
86
"batch_code": "mycampaign1234",
87
"tags": ["electro"],
88
"launch_date": "2019-08-20T13:30:00Z",
89
}
90
Copied!
Cuando es necesario hacer un gran número de requests, es altamente recomendable mantener las conexiones HTTP abiertas usando keep-alive. Esto evita todo el overhead que se introduce al establecer las conecciones TCP. En las pruebas realizadas se vieron incrementos de ~5x en los requests por segundo alcanzados.