# Your first integration This walkthrough builds a small integration end to end with curl: it defines a custom field and a tag, creates or updates a contact that uses them, creates a template from HTML, subscribes a webhook to the result, sends the template to the contact, and receives the webhook. The examples use a fictional organisation, the Birchwood Community Garden, which assigns garden plots to its members. Each step links to the full reference for the endpoint it uses. --- ## Before You Start - **Credentials.** You need your API ID and API Key, and the API must be enabled for your account; see [Authentication](https://developers.envoke.com/guides/authentication/). The examples read the credentials from the `API_ID` and `API_KEY` shell variables set up in [Make a Request](https://developers.envoke.com/guides/authentication/#make-a-request). - **Send prerequisites.** Step 5 uses the Send API, which needs the Transactional API preference set in Envoke, a sender identity, and credits. See [Before Your First Send](https://developers.envoke.com/guides/which-api/#before-your-first-send). - **Real data.** Every request in this walkthrough changes your account, and step 5 sends a real email. Use an email address you control in place of `ama.osei@example.org`. - **Limits.** Every request counts towards your account's [API limits](https://developers.envoke.com/guides/authentication/#api-limits). - **Tools.** The examples use `curl`, and step 3 also uses [`jq`](https://jqlang.org) 1.6 or later to send an HTML file as JSON. --- ## Step 1: Create the Custom Field and the Tag Custom fields and tags are defined once for the account, then set on each contact through the Contact API. Look each one up before creating it: ```bash curl -X GET -gs -u "$API_ID:$API_KEY" "https://e1.envoke.com/v2/customfields?filter%5Bname%5D=Plot_Number&fields=id,name" curl -X GET -gs -u "$API_ID:$API_KEY" "https://e1.envoke.com/v2/tags?filter%5Bname%5D=Volunteer&fields=id,name" ``` Each returns `[]` when nothing has that name, or an array of the matches with their IDs. `filter[name]` matches the whole name; for custom fields it ignores letter case, so the lookup can return `plot_number`. Create only what is missing, and from then on use each name exactly as the API returns it. Create a custom field to hold each member's plot number: ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Plot_Number", "field_type": "text", "description": "Garden plot assigned to the member"}' \ "https://e1.envoke.com/v2/customfields" ``` ```json { "success": true, "result_text": "Created", "result_data": { "id": "9201", "name": "Plot_Number", "description": "Garden plot assigned to the member", "field_type": "text" } } ``` A custom field name can contain only letters, digits, and underscores. A name that is already used, in any letter case, fails with `A custom field named 'Plot_Number' already exists`. See [Custom Field API - Insert](https://developers.envoke.com/v2/customfields/insert/). Create a tag for members who volunteer: ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Volunteer"}' \ "https://e1.envoke.com/v2/tags" ``` ```json { "success": true, "result_text": "Created", "result_data": { "id": "9101", "name": "Volunteer", "group": "" } } ``` *(`result_data` shortened; the response contains every tag field.)* See [Tag API - Insert](https://developers.envoke.com/v2/tags/insert/). Points to know about names: - **Tag names are not unique.** The Tag API does not refuse a name that is already used, so creating `Volunteer` again gives you a second tag with the same name. That is why the lookup comes first. If the lookup returns more than one tag, choose one and use its ID. - **Refer to the tag by its ID.** The Contact API resolves the names in `interests` more loosely than `filter[name]`: it ignores case, treats a space and an underscore as the same, and looks at every kind of list in your account, including subscriptions, import lists, and poll answers, not only tags. A name can therefore pick an item other than your tag. Step 2 sets the tag by the ID returned here, `9101`, which always means this tag. - **Refer to the custom field by its name.** The Contact API does not accept a custom field's ID; `custom_fields` is keyed by name (see [`custom_fields`](https://developers.envoke.com/v1/contacts/fields/#custom_fields)). Custom field names are unique in the account, whatever their letter case. --- ## Step 2: Create or Update the Contact Create the contact, or update it if it already exists, with one upsert request. `upsert=1` turns a create into an update when a contact already matches, and `key_field=remote_id` matches on your own identifier instead of the email address: ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"email": "ama.osei@example.org", "remote_id": "BCG-0417", "first_name": "Ama", "last_name": "Osei", "consent_status": "Express", "consent_description": "Signed the member volunteer form, 2026-04-18", "custom_fields": {"Plot_Number": "B-14"}, "interests": {"9101": "Set"}}' \ "https://e1.envoke.com/v1/contacts?upsert=1&key_field=remote_id" ``` The first time, no contact has the remote ID `BCG-0417`, so the contact is created and returned in full: ```json { "success": true, "result_text": "The contact was successfully created.", "result_data": { "id": "9001", "external_id": "5c1e9a3f7b2d4e6a8c0f1b3d5e7a9c2e", "date_created": "2026-10-28T13:05:12+00:00", "remote_id": "BCG-0417", "first_name": "Ama", "last_name": "Osei", "email": "ama.osei@example.org", "consent_status": "Express", "consent_description": "Signed the member volunteer form, 2026-04-18", "consent_effective_date": "2026-10-28T13:05:12+00:00", "consent_expiry": "", "custom_fields": { "Plot_Number": "B-14" }, "interests": ["Volunteer"], "autoresponders": [] } } ``` *(`result_data` shortened; the response contains every field, with `""` for those not set.)* Sending the same request again matches the contact by `remote_id` and updates it: `result_text` is `The contact was successfully updated.` and `result_data` is the full, updated contact. The contact is given `Express` consent here because the Send API sends to an existing contact only when their consent allows sending (see [Consent fields](https://developers.envoke.com/v1/contacts/fields/#consent-fields)). **Do not send consent on every sync.** Sending `consent_status` `Express` for a contact whose status is `Revoked`, because they unsubscribed, makes `Express` their current status again: the contact is opted back in, and the response does not say so. Send consent only when you have new consent from the person, such as a form they have just signed. When a sync runs from your own records, read the contact first and leave the consent fields out for a contact that already exists: ```bash curl -X GET -gs \ -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v1/contacts?filter%5Bremote_id%5D=BCG-0417&fields=id,consent_status" ``` The response is `[]` when no contact has the remote ID; create the contact with its consent, as above. Otherwise it is an array with the contact's `id` and current `consent_status`; send the upsert without `consent_status` and `consent_description`, which leaves the contact's consent unchanged. Leave out `limit=1` here: with it, a match is returned as a bare object instead of an array. Points to know about this request: - **The parameter is `key_field`, not `keyfield`.** `?keyfield=remote_id` is ignored without an error, so the request matches by `email` instead. - **`email` is required** even when `key_field=remote_id` is used. If your account checks email addresses for duplicates, an email that belongs to another contact fails with `contact with email = ama.osei@example.org already exists`. That contact usually has no `remote_id` yet, for example because the person signed up through a form. Look it up with `GET https://e1.envoke.com/v1/contacts?filter%5Bemail%5D=ama.osei%40example.org&fields=id,email,remote_id`; if it is the same person, give it your identifier with `PATCH https://e1.envoke.com/v1/contacts?key_field=email` and the body `{"email": "ama.osei@example.org", "remote_id": "BCG-0417"}`, then repeat the upsert, which now updates it. See [Email already used by another contact](https://developers.envoke.com/v1/contacts/insert/#email-already-used-by-another-contact). - **More than one match is an error**, even with `upsert`: `Multiple contacts already exist with 'remote_id' value 'BCG-0417'. (IDs: 9001, 9002)`. - **An upsert that updates differs from a create.** Empty values are ignored, a missing `consent_status` leaves the contact's current status unchanged, and a consent downgrade is recorded in the contact's history without becoming current unless `consent_force_downgrade` is `true`. A consent change that is not made current, or is blocked (for example for a contact who reported spam), is not reported in the response. See [Upsert: update when the contact exists](https://developers.envoke.com/v1/contacts/insert/#upsert-update-when-the-contact-exists) and [When a change takes effect](https://developers.envoke.com/v1/contacts/fields/#when-a-change-takes-effect). - **`interests` adds unless told otherwise.** The object form `{"9101": "Set"}` adds the tag with ID `9101`; `{"9101": "Unset"}` removes it. The list form, `["Volunteer"]`, also works, by name, and only adds. In a read, `interests` lists names. - **Custom field keys.** On write, `custom_fields` keys match the field name ignoring case, with a space and an underscore treated as the same, so `"plot number"` writes to `Plot_Number`. In read filters the name is case-sensitive: `filter[custom_fields.Plot_Number]=B-14`. See [`custom_fields`](https://developers.envoke.com/v1/contacts/fields/#custom_fields). - **Warnings are prose.** An unrecognised `country` or `language` value does not fail the request; a warning is appended to `result_text`, after a second period on an upsert that updates: `The contact was successfully updated.. 'Narnia' is not a valid value for country; field will not be updated`. See [Warnings](https://developers.envoke.com/v1/contacts/fields/#warnings). - **Errors come in three shapes**, depending on which check fails: the validation envelope with `result_data.errors`, a field-validation envelope with `result_data.fields` keyed by database column, and a plain envelope for an empty or unreadable body. See [Contact API errors](https://developers.envoke.com/v1/contacts/fields/#error-responses). --- ## Step 3: Create a Template Write the email as HTML that Envoke's drag-and-drop editor can open, so that people in your team can change the wording in Envoke later without touching your code. Save it as `plot-assignment.html`: ```html {@msg-subject}

Hi {fname},

 

Your plot for the season is {@customfield-Plot_Number}. The garden opens on Saturday at 9:00 a.m.

{@brand-address}

Update your email preferences or unsubscribe
``` Create a template from the file. `jq` reads the file and builds the JSON body, escaping the HTML; any JSON library does the same: ```bash jq -n --rawfile html plot-assignment.html '{name: "Plot Assignment", html: $html}' | \ curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d @- \ "https://e1.envoke.com/v2/templates" ``` ```json { "success": true, "result_text": "Created", "result_data": { "id": "9301", "external_id": "8d2f4b6a1c3e5f7a9b0d2c4e6f8a1b3d", "preview_url": "https://engage.envoke.com/m/b4d6f8a0c2e4/m/8d2f4b6a1c3e5f7a9b0d2c4e6f8a1b3d", "name": "Plot Assignment", "status": "published", "language": "en", "group": "", "create_time": "2026-10-28 09:07:40", "modified_time": "2026-10-28 09:07:40" } } ``` The HTML is stored as sent, up to 200 kB; it is not returned in this response, only by `GET https://e1.envoke.com/v2/templates/9301?include_html=1`. `create_time` and `modified_time` are in your account's time zone. Template names are not checked for uniqueness. See [Template API - Insert](https://developers.envoke.com/v2/templates/insert/). What makes the HTML editable, and what it holds: - **The editor's structure.** The `TEMPLATE_VERSION` meta tag makes the template open in the drag-and-drop editor, and the `block-outer`, `block-inner`, and `content-edit` classes mark the section, the two rows, and the regions a user can edit. With the meta tag but without these classes, the template opens in the editor with nothing that can be edited. [Making HTML Editable](https://developers.envoke.com/email-html/editable-templates/) explains the structure and has a complete template with an image and a button; the long `