Pular para o conteúdo
← Início

Quickstart: envie seu primeiro email

Este guia envia um email de verdade pelo Pidgely. Você precisa de uma conta (crie a sua; você já entra logado). Confirme seu email pelo link que enviamos: até lá você pode adicionar domínios e templates, mas não criar chaves de API nem enviar.

Você pode enviar o primeiro email na hora, sem mexer no DNS: de qualquer endereço do remetente de teste test.pidgely.com (por exemplo onboarding@test.pidgely.com) para o seu próprio email. Para enviar a outras pessoas, verifique um domínio seu (passo 4).

1. Como criar uma chave de API?

Crie a chave no painel. Ela tem este formato: pdg_k3x7m2qa4bnp6c5d_xyy4u7c2… e aparece só uma vez, então guarde no seu gerenciador de segredos. Para o primeiro teste, uma chave de acesso total é a mais simples; em produção, prefira uma chave sending_access restrita a um domínio.

terminal
export PIDGELY_API_KEY=pdg_sua_chave_aqui

2. Como preparar o envio?

Com cURL não há nada para instalar. Em Go, baixe o SDK oficial.

# nada para instalar
go get github.com/pidgely/pidgely-go

O SDK de Go está publicado (v0.1). Os SDKs de Node.js, Python, PHP e Ruby ainda estão em preview e não foram publicados: por enquanto, use cURL (HTTP puro, funciona em qualquer linguagem) ou Go. Veja o status em SDKs.

3. Como enviar o primeiro email para você mesmo?

Envie do remetente de teste para o email com que você se cadastrou (voce@suaempresa.com abaixo). Qualquer parte antes do @ vale (onboarding@, ola@…); o domínio é test.pidgely.com.

curl -X POST https://api.pidgely.com/emails \
  -H "Authorization: Bearer $PIDGELY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "Acme <onboarding@test.pidgely.com>",
    "to": ["voce@suaempresa.com"],
    "subject": "Olá do Pidgely",
    "html": "<p>Funcionou! 🎉</p>"
  }'
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/pidgely/pidgely-go"
)

func main() {
	ctx := context.Background()
	client := pidgely.NewClient(os.Getenv("PIDGELY_API_KEY"))

	sent, err := client.Emails.Send(ctx, &pidgely.SendEmailRequest{
		From:    "Acme <onboarding@test.pidgely.com>",
		To:      []string{"voce@suaempresa.com"},
		Subject: "Olá do Pidgely",
		Html:    "<p>Funcionou! 🎉</p>",
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(sent)
}

A resposta traz o id do email:

resposta.json
{ "id": "0199d8a2-6f3c-7c51-9e2a-3b1f0c6d4e21" }

O remetente de teste tem dois limites, por isso não serve para falar com desconhecidos:

  • Destinatários: todo destinatário (to, cc e bcc) precisa ser membro da sua organização com email confirmado: você, ou colegas que você convidou. Qualquer outra pessoa recebe 403 sandbox_recipient_not_allowed.
  • Volume: 50 destinatários por dia; depois disso, 429 sandbox_daily_limit_exceeded até 00:00 UTC.

Emails de teste contam na cota do seu plano e aparecem na lista de emails, nos eventos e nos webhooks como qualquer outro.

4. Como adicionar e verificar seu domínio?

Para enviar a qualquer destinatário, envie de um domínio verificado. Adicione o seu no painel ou pela API:

POST /domains
curl -X POST https://api.pidgely.com/domains \
  -H "Authorization: Bearer $PIDGELY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "name": "acme.com" }'

A resposta lista os registros DNS para publicar: um TXT de DKIM, um MX e um TXT de SPF em bounces.acme.com (o return path) e um registro DMARC opcional. Adicione no seu provedor de DNS e peça ao Pidgely para conferir:

POST /domains/:id/verify
curl -X POST https://api.pidgely.com/domains/<id-do-dominio>/verify \
  -H "Authorization: Bearer $PIDGELY_API_KEY"

Domínios novos também são conferidos de novo, automaticamente, a cada poucos minutos. Quando o primeiro domínio é verificado, sua conta sai do modo de teste sozinha. Domínios e DNS (em inglês) explica cada registro e como resolver problemas.

5. Como enviar do seu domínio?

Com o domínio verificado, troque o from por um endereço dele e envie para qualquer pessoa:

terminal
curl -X POST https://api.pidgely.com/emails \
  -H "Authorization: Bearer $PIDGELY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "Acme <onboarding@acme.com>",
    "to": ["entregue@example.com"],
    "subject": "Olá do Pidgely",
    "html": "<p>Funcionou! 🎉</p>"
  }'

Contas novas começam com um limite diário menor na primeira semana (500 destinatários por dia nos 3 primeiros dias, depois 2.000 até o dia 7, nunca acima do seu plano): veja limites e cotas.

6. Como ver o que aconteceu com o email?

Consulte o email para ver o last_event (queued, delivered, bounced…):

check.js
const { data } = await pidgely.emails.get('0199d8a2-6f3c-7c51-9e2a-3b1f0c6d4e21');
console.log(data.last_event);

Em produção, não fique consultando: assine os webhooks, como email.delivered, email.bounced e email.complained.

Próximos passos

A documentação completa (referência da API, guias) está em inglês em docs.pidgely.com.