# Update Recipient ## API Overview > \[!WARNING] > > This covers the obsolete Legacy Marketing Campaigns API. > \[!NOTE] > > For the most up-to-date information on the Contacts API, please visit the [new Marketing Campaigns Contacts API](/docs/sendgrid/api-reference/contacts). The Contacts Recipients API allows you to manage your recipients. You can add, retrieve, update, and delete recipients, as well as get a count of all recipients and all billable recipients. ## Operation overview ```json {"path":"https://api.sendgrid.com/v3/contactdb/recipients","method":"patch","servers":[{"url":"https://api.sendgrid.com","description":"The Twilio SendGrid v3 API"}]} ``` **This endpoint allows you to update one or more recipients.** The body of an API call to this endpoint must include an array of one or more recipient objects. It is of note that you can add custom field data as parameters on recipient objects. We have provided an example using some of the default custom fields SendGrid provides. ## Operation details ### Authentication API Key ### Headers ```json [{"in":"header","name":"Authorization","required":true,"default":"Bearer <>","schema":{"type":"string"}},{"name":"on-behalf-of","in":"header","description":"The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header. When making a call on behalf of a customer account, the property value should be \"account-id\" followed by the customer account's ID (e.g., `on-behalf-of: account-id `). When making a call on behalf of a Subuser, the property value should be the Subuser's username (e.g., `on-behalf-of: `). See [**On Behalf Of**](/docs/sendgrid/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of) for more information.","required":false,"schema":{"type":"string"},"refName":"#/components/parameters/OnBehalfOf","modelName":"__components_parameters_OnBehalfOf"}] ``` ### Request body ```json {"schema":{"type":"array","example":[{"email":"jones@example.com","last_name":"Jones","first_name":"Guy"}],"items":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"last_name":{"type":"string","description":"The last name of the recipient. This is one of the default custom fields."},"first_name":{"type":"string","description":"The first name of the recipient. This is one of the default custom fields."}}}},"encodingType":"application/json"} ``` ### Responses ```json [{"responseCode":"201","schema":{"description":"","content":{"application/json":{"schema":{"title":"ContactDB: Recipient response","type":"object","required":["error_count","new_count","persisted_recipients","updated_count"],"example":{"error_count":1,"error_indices":[2],"new_count":2,"persisted_recipients":["YUBh","bWlsbGVyQG1pbGxlci50ZXN0"],"updated_count":0,"errors":[{"message":"Invalid email.","error_indices":[2]}]},"refName":"ContactdbRecipientResponse201","modelName":"ContactdbRecipientResponse201","properties":{"error_count":{"type":"number","default":0,"description":"The number of errors found while adding recipients."},"error_indices":{"type":"array","default":[],"description":"The indices of the recipient(s) sent that caused the error. ","items":{"type":"number"}},"new_count":{"type":"number","default":0,"description":"The count of new recipients added to the contactdb."},"persisted_recipients":{"type":"array","default":[],"description":"The recipient IDs of the recipients that already existed from this request.","items":{"type":"string"}},"updated_count":{"type":"number","default":0,"description":"The recipients who were updated from this request."},"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"error_indices":{"type":"array","items":{"type":"number"}}}}}}}}}}},{"responseCode":"400","schema":{"description":"The request body is not valid json","content":{"application/json":{"schema":{"type":"object","example":{"errors":[{"field":"field_name","message":"error message"}]},"refName":"ErrorResponse","modelName":"ErrorResponse","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string","description":"An error message."},"field":{"description":"When applicable, this property value will be the field that generated the error.","nullable":true,"type":"string"},"help":{"type":"object","description":"When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error."}}}},"id":{"type":"string","description":"When applicable, this property value will be an error ID."}}},"examples":{"response":{"value":{"errors":[{"field":null,"message":"Request body is not valid json"}]}}}}}}},{"responseCode":"401","schema":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"errors":[{"field":"field_name","message":"error message"}]},"refName":"ErrorResponse","modelName":"ErrorResponse","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string","description":"An error message."},"field":{"description":"When applicable, this property value will be the field that generated the error.","nullable":true,"type":"string"},"help":{"type":"object","description":"When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error."}}}},"id":{"type":"string","description":"When applicable, this property value will be an error ID."}}},"examples":{"response":{"value":{"errors":[{"field":null,"message":"authorization required"}]}}}}}}}] ``` Update Recipient ```js const client = require("@sendgrid/client"); client.setApiKey(process.env.SENDGRID_API_KEY); const data = [ { email: "jones@example.com", last_name: "Jones", first_name: "Guy", }, ]; const request = { url: `/v3/contactdb/recipients`, method: "PATCH", body: data, }; client .request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) .catch((error) => { console.error(error); }); ``` ```python import os from sendgrid import SendGridAPIClient sg = SendGridAPIClient(os.environ.get("SENDGRID_API_KEY")) data = [ {"email": "jones@example.com", "last_name": "Jones", "first_name": "Guy"} ] response = sg.client.contactdb.recipients.patch(request_body=data) print(response.status_code) print(response.body) print(response.headers) ``` ```csharp using System; using System.Collections.Generic; using System.Threading.Tasks; using SendGrid; public class Program { public static async Task Main() { string apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY"); var client = new SendGridClient(apiKey); var data = @"[ { ""email"": ""jones@example.com"", ""last_name"": ""Jones"", ""first_name"": ""Guy"" } ]"; var response = await client.RequestAsync( method: SendGridClient.Method.PATCH, urlPath: "contactdb/recipients", requestBody: data); Console.WriteLine(response.StatusCode); Console.WriteLine(response.Body.ReadAsStringAsync().Result); Console.WriteLine(response.Headers.ToString()); } } ``` ```java import com.sendgrid.*; import java.io.IOException; import org.json.JSONArray; import java.util.HashMap; import java.util.Arrays; public class Example { public static void main(String[] args) throws IOException { try { SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY")); Request request = new Request(); request.setMethod(Method.PATCH); request.setEndpoint("/contactdb/recipients"); request.setBody(new JSONArray(Arrays.asList(new HashMap() { { put("email", "jones@example.com"); put("last_name", "Jones"); put("first_name", "Guy"); } })).toString()); Response response = sg.api(request); System.out.println(response.getStatusCode()); System.out.println(response.getBody()); System.out.println(response.getHeaders()); } catch (IOException ex) { throw ex; } } } ``` ```go package main import ( "fmt" "github.com/sendgrid/sendgrid-go" "os" ) func main() { apiKey := os.Getenv("SENDGRID_API_KEY") host := "https://api.sendgrid.com" request := sendgrid.GetRequest(apiKey, "/v3/contactdb/recipients", host) request.Method = "PATCH" request.Body = []byte(`[ { "email": "jones@example.com", "last_name": "Jones", "first_name": "Guy" } ]`) response, err := sendgrid.API(request) if err != nil { fmt.Println(err.Error()) os.Exit(1) } else { fmt.Println(response.StatusCode) fmt.Println(response.Body) fmt.Println(response.Headers) } } ``` ```php /sendgrid-php.php'; $apiKey = getenv("SENDGRID_API_KEY"); $sg = new \SendGrid($apiKey); $request_body = json_decode('[ { "email": "jones@example.com", "last_name": "Jones", "first_name": "Guy" } ]'); try { $response = $sg->client ->contactdb() ->recipients() ->patch($request_body); print $response->statusCode() . "\n"; print_r($response->headers()); print $response->body() . "\n"; } catch (Exception $ex) { echo "Caught exception: " . $ex->getMessage(); } ``` ```ruby require 'sendgrid-ruby' include SendGrid sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY']) data = JSON.parse('[ { "email": "jones@example.com", "last_name": "Jones", "first_name": "Guy" } ]') response = sg.client.contactdb.recipients.patch(request_body: data) puts response.status_code puts response.headers puts response.body ``` ```bash curl -X PATCH "https://api.sendgrid.com/v3/contactdb/recipients" \ --header "Authorization: Bearer $SENDGRID_API_KEY" \ --header "Content-Type: application/json" \ --data '[{"email": "jones@example.com", "last_name": "Jones", "first_name": "Guy"}]' ```